monday.com items are a core object in the platform. Items are the objects that hold the actual data within the board, to better illustrate this, you can think of a board as a table and an item as a single row in that table.

You can learn more about this object type here.

Items Queries

Required scope: boards:read

query {
    items (ids: [12345678, 23456789, 34567890]) {
        name
    }
}
let query = "query { items (ids: [12345678, 23456789, 34567890]) { name }}";

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)));
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretAPIkey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query { items (ids: [157244624, 201781760, 239164869]) { name } }"}'

Arguments

The following item arguments can reduce the number of items returned.

Argument

Description

limit Int

The number of items returned. Default is 25.

page Int

The page number returned, should you implement pagination. Starts at 1.

ids [Int]

A list of unique items identifier(s).

newest_first Boolean

Get the recently created items at the top of the list.

Fields

Items contain the actual data within the boards. Each item contains columns in which the different values are stored.

The following fields will determine what is returned from your items 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. This is for querying subitems. If used for a parent item, it will return null.

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

Items Mutations

Required scope: boards:write

Create an Item

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

The data of each item is stored in the board’s columns, 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_item (board_id: 1234567, group_id: "today", item_name: "new item") {
        id
    }
}
let query = "mutation { create_item (board_id: 1234567, group_id: \"today\", item_name: \"new item\") { 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)));
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretAPIkey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation { create_item (board_id: 1234567, group_id: \"today\", item_name: \"new item\") { id }}"'

Arguments for Create an Item

The following create_item() arguments define the new item's characteristics.

Argument

Description

item_name String

The new item's name.

board_id !Int

The board's unique identifier.

group_id String

The group's unique identifier.

column_values JSON

The column values of the new item.

create_labels_if_missing Boolean

Create Status/Dropdown labels if they're missing. (Requires permission to change board structure)

🚧

NOTE

To change the item name of an existing item, check out the Item Name (First Column) article. It will require you to utilize the change_column_value() mutation with a JSON string value.

Create a Subitem

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

Subitems are technically created under a different board, which is NOT the same board as the parent item's board. You can query the identifier of this board through the regular board resolver of the subitem. Using this board ID and subitem ID you can apply any action to the subitem as you would to a regular item (i.e. archive it, delete, change column_values, etc).

📘

NOTE

For creating subitems via the API, the board should already have a subitems column, or at least one subitem created, otherwise you will receive an error.

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)));
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 subitem'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.

Clear an Item's Updates

This mutation allows one to clear all updates on a specific item, including replies and likes. After the mutation runs you can query back the item data as shown in the querying items section above.

mutation {
    clear_item_updates (item_id: 20178755) {
        id
    }
}
let query = "mutation { clear_item_updates (item_id: 20178755) { 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)));
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretAPIkey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation { clear_item_updates (item_id: 20178755) { id }}"'

Arguments for Clear an Item's Updates

The following clear_item_updates() argument determines which item's updates are cleared.

Arguments

Description

item_id !Int

The item's unique identifier.

Move Item to Group

This mutation allows one to move an item between groups in the same board. After the mutation runs you can query back the item data as shown in the querying items section above.

mutation {
    move_item_to_group (item_id: 1234567, group_id: "today") {
        id
    }
}
let query = "mutation { move_item_to_group (item_id: 1234567, group_id: \"today\") { 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)));
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretAPIkey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation { move_item_to_group (item_id: 1234567, group_id: \"today\") { id }}"'

Arguments for Move Item to Group

The following move_item_to_group() arguments determine which item is moved to which group.

Argument

Description

item_id Int

The item's unique identifier.

group_id !String

The group's unique identifier.

Archive an Item

This mutation allows you to archive a single item. After the mutation runs you can query back the item data as shown in the Querying items section.

mutation {
    archive_item (item_id: 12345678) {
        id
    }
}
let query = "mutation {archive_item (item_id: 12345678) { 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)));
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretAPIkey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation {archive_item (item_id: 12345678) { id }}"'

Arguments for Archive an Item

The following archive_item() argument determines which item is archived.

Argument

Description

item_id Int

The item's unique identifier.

Delete an Item

This mutation allows you to delete a single item. After the mutation runs you can query back the remaining items data as shown in the querying items section above.

mutation {
    delete_item (item_id: 12345678) {
        id
    }
}
let query = "mutation { delete_item (item_id: 12345678) { 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)));
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretAPIkey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation { delete_item (item_id: 12345678) { id }}"'

Arguments for Delete an Item

The following delete_item() argument determines which item will be deleted.

Argument

Description

item_id Int

The item's unique identifier.

Duplicate an Item

This mutation allows you to duplicate a single item. After the mutation runs you can query back the remaining items data as shown in the querying items section above.

mutation {
    duplicate_item (board_id: 1234567, item_id: 12345678, with_updates: true){
        id
    }
}
let query = "mutation { duplicate_item (board_id: 1234567, item_id: 12345678, with_updates: true) { 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)));
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretAPIkey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation { duplicate_item (board_id: 1234567, item_id: 12345678, with_updates: true) { id }}"'

Arguments for Duplicate an Item

The following duplicate_item() arguments determine which item and how it will be duplicated.

Argument

Description

board_id !Int

The board's unique identifier.

with_updates Boolean

Duplicate with the item's updates.

item_id Int

The item's unique identifier. Required.


Did this page help you?