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.

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.

Check out these mutations to create a subitem and create a subitem using variables in action in our Postman collection or follow along with these code samples!

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.

📘

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! 😎