Subitems are special items that are "nested" under the items on your board. They can be accessed via the subitem column, which can be added from the column's center or by right-clicking an item to expose its dropdown menu. Like items, subitems store data within their columns.

Queries

You can use the subitems query to retrieve subitem data via the API.

Required scope:boards:read
Returns an array containing metadata about one or a collection of subitems
Can only be nested within another query (e.g., items); can't be queried directly at the root

query {
  items(ids: 1234567890) {
    subitems {
      id
      column_values {
        value
        text
      }
    }
  }
}

Fields

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

Field	Description	Enum Values
assets `[Asset]`	The subitem's assets/files.
board `Board`	The board that contains the subitem.
column_values `[ColumnValue]`	The subitem's column values.
created_at `Date`	The subitem's creation date.
creator `User`	The subitem's creator.
creator_id `String!`	The unique identifier of the user who created the subitem. Returns `null` if the item was created by default on the board.
email `String!`	The subitem's email.
group `Group`	The subitem's group.
id `ID!`	The subitem's unique identifier.
linked_items `[Item!]!`	The subitem's linked items.
name `String!`	The subitem's name.
parent_item `Item`	A subitem's parent item. If used for a parent item, it will return `null`.
relative_link `String`	The subitem's relative path.
state `State`	The subitem's state.	`active` `all` `archived` `deleted`
subitems `[Item]`	The subitem's subitems.
subscribers `[User]!`	The subitem's subscribers.
updated_at `Date`	The date the subitem was last updated.
updates `[Update]`	The subitem's updates.
url `String!`	The subitem's link.

Mutations

The API allows you to create subitems using the following mutation.

Create subitem

Required scope:boards:write

The create_subitem mutation creates a new subitem via the API. You can specify which fields to return in the mutation response.

The data of each subitem is stored in the subitem board columns (same as items), each of which holds a particular piece of information. Each column has a specific type, and different column types expect a different set of parameters to update their values. When sending data to a particular column, use a JSON-formatted string. If you're using JavaScript, you can use JSON.stringify() to convert a JSON object into a string.

You can also use simple values in this mutation or combine them with regular values. Read more about sending data for each column in our column types reference.

mutation {
  create_subitem(
    parent_item_id: 1234567890, 
    item_name: "New subitem", 
    column_values: "{\"date0\":\"2023-05-25\"}"
	) {
    id
    board {
      id
    }
  }
}

Arguments

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

Argument	Description
column_values `JSON`	The column values of the new subitem.
create_labels_if_missing `Boolean`	Creates status/dropdown labels if they're missing. Requires permission to change the board structure.
item_name `String!`	The new subitem's name.
parent_item_id `ID!`	The parent item's unique identifier. Can reference an item or subitem for multi-level boards.

🚧
For multi-level boards:

Subitems can be nested up to 5 levels deep.

parent_item_id can reference an item or subitem.

When you create the first subitem under a parent:

For rollup-eligible columns:

If no values are provided, the parent’s values are copied to the subitem and then cleared from the parent.

If values are provided, the parent’s values are not copied, but they are still cleared.

For any additional subitems, values are not copied; the parent instead shows a calculated rollup.