Items are organized in different sections on a board called groups. Each board contains at least one group that houses one or more items.

Queries

You can use the groups query to retrieve group data via the API.

Required scope:boards:read
Returns an array containing metadata about one or a collection of groups on a specific board
Can only be nested within another query (e.g., boards)

query {
  boards(ids: 1234567890) {
    groups {
      title
      id
    }
  }
}

Arguments

You can use the following argument to reduce the number of results returned in your groups query.

Argument	Description
ids `[String]`	The specific groups to return.

Fields

You can use the following fields to specify what information your groups query will return.

Field	Description
archived `Boolean`	Returns `true` if the group is archived.
color `String!`	The group's color.
deleted `Boolean`	Returns `true` if the group is deleted.
id `ID!`	The group's unique identifier.
items_page `ItemsResponse!`	The group's items.
position `String!`	The group's position on the board.
title `String!`	The group's title.

Mutations

The API allows you to create, update, and delete groups using the following mutations. These operations let you programmatically control a group's full lifecycle.

Create group

Required scope:boards:write

The create_group mutation creates a new empty group via the API. You can specify which fields to return in the mutation response.

mutation {
  create_group(
    board_id: 1234567890, 
    group_name: "new group", 
    relative_to: "test_group", 
    group_color: "#ff642e", 
    position_relative_method: before_at
	) {
    id
  }
}

Arguments

You can use the following arguments to define the new group's characteristics.

Argument	Description	Accepted Values
board_id `ID!`	The board's unique identifier.
group_color `String`	The group's HEX code color.	See a full list of accepted HEX code values and their corresponding colors here (don't forget to include # in your string!)
group_name `String!`	The new group's name. Maximum of 255 characters.
position `String` (DEPRECATED)	The group's position on the board.	The group's position is determined using a string containing only a number value (no letters or special characters). The higher the value, the lower the group sits on the board; the lower the value, the higher the group sits on the board. If you provide an invalid input using letters or special characters, the group will go to the top of the board. You will get an error if you provide a `number` rather than a `string`. For example:* Assume Group 1 has a position of 10000 and Group 3 has a position of 30000. If you want to create a new group between the other two called Group 2, it needs a position greater than 10000 and less than 30000.
relative_to `String`	The unique identifier of the group you want to create the new one in relation to. The default creates the new group below the specified `group_id`. You can also use this argument in conjunction with `position_relative_method` to specify if you want to create the new group above or below the group in question.
position_relative_method `PositionRelative`	The desired position of the new group.	You can use this argument in conjunction with `relative_to` to specify which group you want to create the new group above or below. `before_at`: This enum value creates the new group above the `relative_to` value. If you don't use the `relative_to` argument, the new group will be created at the bottom of the board. `after_at`: This enum value creates the new group below the `relative_to` value. If you don't use the `relative_to` argument, the new group will be created at the top of the board.

Update group

Required scope:boards:write

The update_group mutation updates an existing group via the API. You can specify which fields to return in the mutation response.

mutation {
  update_group(
    board_id: 1234567890, 
    group_id: "test group id", 
    group_attribute: relative_position_before, 
    new_value: "test_group"
	) { 
    id
  } 
}

Arguments

You can use the following arguments to specify which group to update and its new value.

Argument	Description	Accepted Values
board_id `ID!`	The board's unique identifier.
group_attribute `GroupAttributes!`	The group attribute to update.	`color` `position` `relative_position_after` `relative_position_before` `title`
group_id `String!`	The group's unique identifier.
new_value `String!`	The new attribute value.	See a full list of accepted color values here. When updating a group's position using the `relative_position_after` or `relative_position_before` attributes, the new attribute value should be the unique identifier of the group you intend to place the updated group above or below.

Duplicate group

Required scope:boards:write

The duplicate_group mutation duplicates a group and all of its items via the API. You can specify which fields to return in the mutation response.

🚧
This mutation has an additional rate limit of 40 mutations per minute.

mutation {
  duplicate_group(
    board_id: 1234567890, 
    group_id: "test group id", 
    add_to_top: true
	) {
    id
  }
}

Arguments

You can use the following arguments to specify which group to duplicate and its new properties.

Argument	Description
add_to_top `Boolean`	Boolean to add the new group to the top of the board.
board_id `ID!`	The board's unique identifier.
group_id `String!`	The group's unique identifier.
group_title `String`	The group's title.

Move item to group

The move_item_to_group mutation moves an item between groups on the same board via the API. You can specify which fields to return in the mutation response.

mutation {
  move_item_to_group(
    item_id: 1234567890, 
    group_id: "test group id"
	) {
    id
  }
}

Arguments

You can use the following arguments to specify which item to move and to which group.

Argument	Description
group_id `String!`	The group's unique identifier.
item_id `ID`	The item's unique identifier.

Archive group

Required scope:boards:write

The archive_group mutation archives a group and all of its items via the API. You can specify which fields to return in the mutation response.

mutation {
  archive_group(
    board_id: 1234567890, 
    group_id: "test group id"
	) {
    id
    archived
  }
}

Arguments

You can use the following arguments to specify which group to archive.

Argument	Description
board_id `ID!`	The board's unique identifier.
group_id `String!`	The group's unique identifier.

Delete group

Required scope:boards:write

The delete_group mutation deletes a group and all of its items via the API. You can specify which fields to return in the mutation response.

mutation {
  delete_group(
    board_id: 1234567890
    group_id: "Test Group ID"
  ) {
    id
    deleted
  }
}

Arguments

You can use the following arguments to specify which group to delete.

Argument	Description
board_id `ID!`	The board's unique identifier.
group_id `String!`	The group's unique identifier.