[RELEASED] Creating new labels with the API

:sparkles::sparkles:Hi everyone!

After much anticipation, you are now able to create new Status and Dropdown labels using our API!

To do so, use the create_labels_if_missing boolean argument to create any missing labels in your Status and Dropdown columns. This argument will default to false, so if you don’t define it as true the missing labels will not get created and your API calls will fail.

Because creating new labels changes a board’s structure, you must have the permissions to change board structure in order to successfully use this argument.

Here is an example query using this argument:

mutation {
  create_item (board_id: 12345678, item_name: "New item", column_values: "{\"status\" : \"New Label\"}", create_labels_if_missing: true) {
    id
  }
}

Currently, this parameter has been added to the following mutations:

  • create_item()
  • change_simple_column_value()
  • change_column_value()
  • change_multiple_column_values()
  • create_subitem()

Thanks everyone and happy building!

-Helen

11 Likes

Hey Helen - Has the ability to delete the default labels like “done” or “stuck” via the API been implemented yet? My team loves using the “status” column but the default values don’t always make sense.

Thanks!

1 Like

Hi Helen, I’m new here.

Is there a way to create a status column and add custom labels without having to create items?

I am having an issue where I need to create two status columns in more than 500 boards and in all cases, the labels must follow a standard of our company so that users can choose a status that we have defined. Is there a possibility of creating the columns by configuring the status option types, colors, etc.?

Something like:

mutation {
  create_column(board_id: BOARD_ID, column_type: status, title: "Column Name", labels: ["Label 1", "Label 2", "Label 3"]) {
    id
  }
}

Note: this is only an example that doesn’t work.

Regards,

Hi @RogerLovato,

You will need an item when you add the labels.

You’ll need two operations to achieve this:

Create the status column

mutation{
  create_column(board_id: 12345678, title:"Work Status", description: "This is my work status column", column_type:status) {
    id
    title
    description
  }
}

and then update the column to include the labels

mutation {
  change_multiple_column_values(item_id:11111, board_id:22222, column_values: "{\"status15\" : {\"label\" : \"Done\"}}") {
    id
  }
}

Hi @alessandra.
How to create a status column and specify colors to labels. I tried smth like this:

{
    "query": "mutation ( $title: String!, $description: String!, $defaults: JSON!, $column_type: ColumnType!, $board_id: Int!,  ) { create_column ( title: $title, description: $description, defaults: $defaults, column_type: $column_type, board_id: $board_id,  ) { id } }",
    "variables": {
        "title": "Custom Status",
        "description": "Description",
        "defaults": "{\"labels\":{\"0\":\"Working on it\",\"1\":\"Done\",\"2\":\"Stuck\",\"3\":\"Custom Label\",\"4\":\"Almost Done\",\"6\":\"test3\",\"7\":\"test2\",\"8\":\"test4\"},\"labels_colors\":{\"0\":{\"color\":\"#fdab3d\"},\"1\":{\"color\":\"#00c875\"},\"2\":{\"color\":\"#e2445c\"},\"3\":{\"color\":\"#ffadad\"},\"4\":{\"color\":\"#9CD326\"},\"6\":{\"color\":\"#FF158A\"},\"7\":{\"color\":\"#579bfc\"},\"8\":{\"color\":\"#CAB641\"}}}",
        "column_type": "status",
        "board_id": 1258885613
    }
}

Labels were created successfully, but colors didn’t.

Hello @Dev and welcome to the community!

I hope you like it here :muscle:

As explained in this article:

By default, every index value matches a specific color. For example, the Green status has the index 1. Here’s a full list of the indexes and matching values.

When you create a new Status label, it will follow the default index value and its index will not change. However, the color of a status label can be changed. Therefore, you cannot assume a label’s color and index will always match.

Take the following example:

Index: 2 will have a color value of #e2445c. Thus, using this index value will set the Status column value to a Red-shadow color, as shown below:

512|smartxauto

And on the board, this will appear as such:

|autoxauto

The color values are not static and can be changed within the Status column labels. You can find more info on this here.

Then, the index value will remain the same, but the color value will be changed. For example, if I chose Black as the new color, this is how the color value would appear in the API:

|autoxauto

And this is how the item would appear on the board:

|autoxauto

As such, using index values does not guarantee that you will populate the same color values across multiple boards.

If you encounter a mismatch of index values when sending data between boards in your account, we recommend changing the color of the labels back to the default values manually.

So in this case, you can use the given indexes to select a color according to the table.

Let me know if you have any other questions :slightly_smiling_face:

Cheers,
Matias

Looks like a bot answer. Actually it’s not an answer to my question. It’s just a copy-paste from documentation page. Not what I need.
Can you show here a sample of request how to create e.g. label “Custom label” with color “sky” via API?

Hello again,

I am sorry if that was not clear, here is an example where I am using the index of “sky” (153) to create a new column with a label called “Custom label” and the color “sky”:

mutation {
  create_column(
    board_id: 1234567890
    title: "My status column"
    column_type: status
    defaults: "{\"labels\":{\"153\": \"Custom label\"}}"
  ) {
    id
  }
}

Is that what you needed?

Cheers,
Matias

1 Like

Yep, great. Thank you very much.

1 Like

Happy to help @Dev :grin:

Haha @Dev your post made me laugh! :laughing: @Matias.Monday is definitely not a bot – but you never know these days!!!

2 Likes

Hi @Matias.Monday,

Is there a way to modify the labels of an existing Status column via API?

For example:
A board has a status column with only the default values (0 - Working on it, 1 - Done, 2 - Stuck). If I want to modify the “Working on it” label to say “In progress” but keep the same index and colour, is that possible?

I have tried something like below, but this creates a new label with an index +1 above the current highest value which is a different colour (e.g. blue or purple instead of orange)

mutation {
  change_column_value(
    board_id: 123456789, 
    item_id: 123456789, 
    column_id: "status", 
    value: "{\"index\":0,\"label\":\"In review\"}", 
    create_labels_if_missing: true
  ) {
    id
  }
}

Any guidance would be appreciated!

Currently there is not a way to modify existing labels, only create brand new ones.

1 Like

Hi everyone, I’m new here and I really like what I read. I have a question. I have a board that I use as a model for other boards (in general I just duplicate this board).
Is there a way that if I add a new label on a category of this board, it will automatically be added to every other boards that look the same? (I have a 100s of them) same for deleting…
I really trouble with this

You can add a new label when you mutate an item on a board, but there is no way to delete them today.

Additionally when a board is created from a template its not linked to the template anymore. This means no changes to the template are reflected on the boards created from it - every board has to be manually updated with the new labels (or an item changed to the new value by API). Removing labels is 100% a manual task today - since you also can’t remove a label thats in use.

I know the 2024 roadmap has linked templates though, where changes to the structure of the template board will be reflected on the deployed boards. I do not know if that includes labels. (nor how they would handle removing a label thats in use)