CommunityApps FrameworkAPI Playground

Subitems

Suggest Edits

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 either from the columns center, or by right-clicking an item to expose its dropdown menu.

All subitems are stored on an entirely separate board from their parent items. The subitems column on the parent board contains the IDs of the subitems linked to a given item. As such, in order to find your subitem board ID, you will first need to query the column_values() of the parent board's subitem column. This will return your subitem IDs which you can then use to query the boards field to find your subitem board ID.

You can learn more about subitems here.

Subitems Queries

Required scope: boards:read

πŸ‘

New feature alert!

You can now query Subitems directly as part of querying the parent item. Find more info below.

You can now query subitems directly when querying the parent item. The subitems object will include all of the Item fields. You can find an example query below:

{
  boards(ids: yourBoardId) {
    id
    name
    items (limit: 10) {
      id
      name
      column_values {
        id
        value
        text
      }
      subitems {
        id
        name
        column_values {
          id
          value
          text
        }
      }
    }
  }
}

let query = "{ boards(ids: yourBoardId) { id name items (limit: 10) { id name column_values { id value text } subitems { id name column_values { id value text } } } } } ";

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


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

🚧

Querying sub-items and complexity

When making a query for subitems as part of items, your subitems query becomes nested. This may lead to an increase in your query's complexity rating. To have more control over the complexity rating of those queries, we currently recommend limiting the number of items you retrieve.

You can find more about complexity rate limits here.

Arguments

If you query subitems as part of a Parent item, using the approach shown above, no arguments are currently supported.

Fields

Subitems, like Items, store data within their columns.

The following fields will determine what is returned from your subitems query. Some fields will have their own arguments.

Field

Field Description

Supported Arguments

assets [Asset]

The item's assets/files.

column_ids [String]

board Board

The board that contains this item.

column_values [ColumnValue]

The item's column values.

ids [String]

created_at Date

The item's create date.

creator User

The item's creator.

creator_id !String

The unique identifier of the item creator.

group Group

The group that contains this item.

id !ID

The item's unique identifier.

name !String

The item's name.

parent_item !Item

The relevant parent item for the subitem.

assets [Asset]
board Board
column_values [ColumnValue]
created_at Date
creator User
creator_id !String
group Group
id [String]
name !String
state State
subscribers ![User]
updated_at Date
updates [Update]

state State

The item's state (all / active / archived / deleted).

subscribers ![User]

The pulses's subscribers.

updated_at Date

The item's last update date.

updates [Update]

The item's updates.

limit Int
page Int

There is a different method of querying for sub-item data as well. Here's an example of the method, which involves using multiple queries. In the first, you query the parent item's subitems column in order to get the associated sub-item IDs, and then query those for their values.

// This query will return the value of your subitem column, which will include your subitem IDs
query {
    boards (ids: 1234567) {
        items {
            column_values (ids: "subitems2"){
        value
        }
    }
}
  
// This query will return the board ID using your subitem ID
query {
  items(ids: "VALUE_RETURNED"){
    board {
      id
    }
  }
}

let query = "query { boards(ids: 1234567) { items { column_values { id }}}}";
let query2 = "query { items(ids: "VALUE_RETURNED"){ board { id }}}";


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


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

curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretApiKey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query {   boards (ids: 1234567) { items { column_values { id }}}}"}'


curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretApiKey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query {   items(ids: "VALUE_RETURNED") { board { id }}}"}'

Subitems Mutations

Required scope: boards:write

Create a Subitem

This method allows you to create a new subitem. After the mutation runs you can query back all the subitem data as shown in the querying subitems section above.

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 certain 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).

πŸ“˜

NOTE

You can also use simple values in this mutation combined with regular values, or just simple values.

To check how to send the data for each column please see the Column Types Reference.

mutation {
    create_subitem (parent_item_id: 1234567, item_name: "new subitem") {
        id
        board {
            id
        }
    }
}

const fetch = require('node-fetch')

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' : 'YourSuperSecretAPIkey'
   },
   body: JSON.stringify({
     'query' : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretAPIkey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation{ create_subitem( parent_item_id: 1234567, item_name: \"new subitem\"){ id board { id }}}"}

Arguments for Create a Subitem

The following create_subitem() arguments define the new column's characteristics.

Argument

Description

parent_item_id Int

The parent item's unique identifier.

item_name String

The new item's name.

column_values JSON

The column values of the new item.

create_labels_if_missing Boolean

Creates status/dropdown labels if they're missing. Requires permission to change board structure.

πŸ“˜

Subitem Webhooks

Want to be notified when a new subitem is created or an existing one is updated? You can use Webhooks for this. Check out our Webhooks documentation to learn more.

Updated about 2 months ago

Did this page help you?