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.

As a developer working with monday.com, it is important to familiarize yourself with the subitems API so you know how to access subitem data. This document will walk you through the available queries and mutations to read and modify the subitems object via the API.

Queries

Required scope: boards:read

Querying subitems will return metadata about one or a collection of subitems. This method does not accept any arguments and returns an array.

You can only query subitems by nesting it within another query, so it can't be used at the root. Please note that nesting subitems inside an items query will increase its complexity. You can lower the complexity by limiting the number of items you retrieve.

query {
  items (ids: 1234567890) {
    subitems {
      id
      column_values {
        value
        text
      }
    }
  }
}
let query = "query {items (ids: 1234567890) { subitems  { id column_values { value text } } } } ";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     'query': query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Fields

You can use the following field(s) to specify what information your subitems query will return. Please note that some fields will have their own arguments.

FieldDescriptionSupported arguments
assets [Asset]The subitem's assets/files.assets_source AssetsSource
column_ids [String]
board BoardThe board that contains the subitem.
column_values [ColumnValue]The subitem's column values.ids [String]
created_at DateThe subitem's creation date.
creator UserThe 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 GroupThe subitem's group.
id ID!The subitem's unique identifier.
name String!The subitem's name.
parent_item ItemA subitem's parent item. If used for a parent item, it will return null.exclude_nonactive Boolean
ids [Int]
limit Int
newest_first Boolean
page Int
relative_link StringThe subitem's relative path.
state StateThe subitem's state: all, active, archived, or deleted.
subitems [Item]An item's subitems. If used for a subitem, it will return null.
subscribers [User]!The subitem's subscribers.
updated_at DateThe date the subitem was last updated.
updates [Update]The subitem's updates.limit Int
page Int

Mutations

Required scope: boards:write

Create a subitem

The create_subitem mutation allows you to create a new subitem via the API. You can also specify what fields to query back from the new subitem when you run the mutation.

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: 1234567, item_name: "new subitem") {
    id
    board {
      id
    }
  }
}
let query = "mutation{ create_subitem (parent_item_id: 1234567, item_name: \"new subitem\"){ id board { id }}}";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments

You can use the following argument(s) to define the new subitem's characteristics.

ArgumentDescription
column_values JSONThe column values of the new subitem.
create_labels_if_missing BooleanCreates 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.

πŸ“˜

Join our developer community!

We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎