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

Get groups

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

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

Fields

Field	Type	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

Required scope:boards:write

Create group

Creates a new empty group. Returns Group.

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

Arguments

Argument	Type	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 (DEPRECATED)	`String`	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

Updates a group. Returns Group.

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

Arguments

Argument	Type	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

Duplicates a group and all of its items. Returns Group.

🚧
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

Argument	Type	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

Moves an item between groups on the same board. Returns Group.

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

Arguments

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

Archive group

Archives a group and all of its items. Returns Group.

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	Type	Description
board_id	`ID!`	The board's unique identifier.
group_id	`String!`	The group's unique identifier.

Delete group

Deletes a group and all of its items. Returns Group.

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

Arguments

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