Items
The behaviour of this query will change in version 2023-10
If you're getting items from a specific board, use use
items_page
instead of items. You can still use this query to retrieve specific items by their ID.
Items are core objects in the monday.com platform that hold the actual data within the board. To better illustrate the platform, imagine that each board is a table and an item is a single row in that table. Now take one row, fill it with whatever information you'd like, and you now have an item!
As a developer working with monday.com, it is important to familiarize yourself with the items
API so you know how to access item data. This document will walk you through the available queries and mutations to read and modify the items
object via the API.
Queries
Required scope: boards:read
Querying items
will return metadata about one or a collection of items. This method accepts various arguments and returns an array.
You can query items
directly at the root to return all items across an account or nest it within a boards
or groups
query to return items from a specific board or group.
Note for root items query
This query has a 100-item limit and is not as fast as querying on the board level, so you should only use it if you have no other option.
If you know the board IDs you're retrieving from, we recommend retrieving items from those boards directly using a query like this:
{ boards (ids:[12345, 23456]) { items (ids:[1234,2345]) { ... } }
You can learn more about this approach here!
Check out this query in action in our Postman library or follow along with these code samples!
query {
items (ids: [1234567890, 9876543210, 2345678901]) {
name
}
}
let query = "query { items (ids: [1234567890, 9876543210, 2345678901]) { 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)));
Arguments
You can use the following argument(s) to reduce the number of results returned in your items
query.
Argument | Description |
---|---|
exclude_nonactive Boolean | Excludes items that are inactive, deleted, or belong to deleted items. Please note that this argument will only work when used with the ids argument. |
ids [Int] | The IDs of the specific items to return. Please note that this argument's type is [ID!] in API versions 2023-10 and later. |
limit Int | The number of items returned. The default is 25. |
newest_first Boolean | Lists the most recently created items at the top. |
page Int | The page number to return. Starts at 1. |
Fields
You can use the following field(s) to specify what information your items
query will return. Please note that some fields will have their own arguments.
Field | Description | Supported arguments |
---|---|---|
account_id Int! | The unique identifier of the item's account. | |
assets [Asset] | The item's assets/files. | assets_source AssetsSource column_ids [String] |
board Board | The board that contains the item. | |
column_values [ColumnValue] | The item's column values. | ids [String] |
column_values_str String! | The item's string-formatted column values. | |
created_at Date | The item's creation date. | |
creator User | The item's creator. | |
creator_id String! | The unique identifier of the item's creator. Returns null if the item was created by default on the board. | |
email String! | The item's email. | |
group Group | The item's group. | |
id ID! | The item's unique identifier. | |
linked_items [Item!]! | The item's linked items. Available in API version 2023-10 only. | linked_board_id Int! link_to_item_column_id String! |
name String! | The item's name. | |
parent_item Item | A subitem's parent item. If used for a parent item, it will return null . | |
relative_link String | The item's relative path. | |
state State | The item's state: all, active, archived, or deleted. | |
subitems [Item] | The item's subitems. | |
subscribers [User]! | The item's subscribers. | |
updated_at Date | The date the item was last updated. | |
updates [Update] | The item's updates. | limit Int page Int |
Mutations
Required scope: boards:write
Create an item
The create_item
mutation allows you to create a new item via the API. You can also specify what fields to query back from the new item when you run the mutation.
Item data is stored in columns that hold particular information based on the column type. Each type expects 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 the requests to create an item and create an item using variables in our Postman library or follow along with these code samples!
mutation {
create_item (board_id: 1234567890, group_id: "group_one", item_name: "new item", column_values: "{\"date\":\"2023-05-25\"}") {
id
}
}
let query = "mutation { create_item (board_id: 1234567890, group_id: \"Group 1\", item_name: \"new item\", column_values: \"{\\\"date4\\\":\\\"2023-05-25\\\"}\") { 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 item's characteristics.
Argument | Description |
---|---|
board_id Int! | The board's unique identifier. Please note that this argument's type is ID! in API versions 2023-10 and later. |
column_values JSON | The column values of the new item. |
create_labels_if_missing Boolean | Creates status/dropdown labels if they are missing (requires permission to change the board structure). |
group_id String | The group's unique identifier. |
item_name String! | The new item's name. |
Changing an item's name
If you'd like to change an existing item's name, you need to use the
change_column_value
mutation with a JSON string value. Check out this doc for more info!
Duplicate an item
The duplicate_item
mutation allows you to duplicate a single item via the API. You can also specify what fields to query back from the duplicated item when you run the mutation.
mutation {
duplicate_item (board_id: 1234567890, item_id: 9876543210, with_updates: true) {
id
}
}
let query = "mutation { duplicate_item (board_id: 1234567890, item_id: 9876543210, 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)));
Arguments
You can use the following argument(s) to specify which item to duplicate.
Argument | Description |
---|---|
board_id Int! | The board's unique identifier. Please note that this argument's type is ID! in API versions 2023-10 and later. |
item_id Int | The item's unique identifier. Required. Please note that this argument's type is ID in API versions 2023-10 and later. |
with_updates Boolean | Duplicates the item with existing updates. |
Move item to group
The move_item_to_group
mutation allows you to move an item between groups on the same board via the API. You can also specify what fields to query back from the item when you run the mutation.
mutation {
move_item_to_group (item_id: 1234567890, group_id: "group_one") {
id
}
}
let query = "mutation { move_item_to_group (item_id: 1234567890, group_id: \"Group 1\") { 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 specify which item to move and to where.
Argument | Description |
---|---|
group_id String! | The group's unique identifier. |
item_id Int | The item's unique identifier. Please note that this argument's type is ID in API versions 2023-10 and later. |
Move item to board
The move_item_to_board
mutation allows you to move an item to a different board via the API. You can also specify what fields to query back from the item when you run the mutation. Please note that this mutation is only available in API version 2023-10
for now.
mutation {
move_item_to_board (board_id:1234567890, group_id: "new_group", item_id:9876543210, columns_mapping: [{source:"status", target:"status2"}, {source:"person", target:"person"}, {source:"date", target:"date4"}]) {
id
}
}
let query = "mutation { move_item_to_board (board_id: 1234567890, group_id: \"new_group\", item_id: 9876543210, columns_mapping: [{source:\"status\", target:\"status2\"}, {source:\"person\", target:\"person\"}, {source:\"date\", target:\"date4\"}]) { 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 specify which item to move and to where.
Argument | Description | Supported fields |
---|---|---|
board_id ID! | The unique identifier of the board to move the item to (target board) | |
group_id ID! | The unique identifier of the group to move the item to (target group). | |
item_id ID! | The unique identifier of the item to move. | |
columns_mapping [ColumnMappingInput!] | The object that defines the column mapping between the original and target board. If you omit this argument, the columns will be mapped based on the best match. Please note that you must specify the mapping for every column when using this argument. You can specify the target as null if you don't want to map a column, but doing so means that the column's data will be lost. | source ID! target ID |
subitems_column_mapping [ColumnMappingInput!] | The object that defines the subitems' column mapping between the original and target board. If you omit this argument, the columns will be mapped based on the best match. Please note that you must specify the mapping for every column when using this argument. You can specify the target as null if you don't want to map a column, but doing so means that the column's data will be lost. | source ID! target ID |
Archive an item
The archive_item
mutation allows you to archive a single item via the API. You can also specify what fields to query back from the archived item when you run the mutation.
mutation {
archive_item (item_id: 1234567890) {
id
}
}
let query = "mutation {archive_item (item_id: 1234567890) { 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 specify which item to archive.
Argument | Description |
---|---|
item_id Int | The item's unique identifier. Please note that this argument's type is ID in API versions 2023-10 and later. |
Delete an item
The delete_item
mutation allows you to delete a single item via the API. You can also specify what fields to query back from the deleted item when you run the mutation.
mutation {
delete_item (item_id: 1234567890) {
id
}
}
let query = "mutation { delete_item (item_id: 1234567890) { 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 specify which item to delete.
Argument | Description |
---|---|
item_id Int | The item's unique identifier. Please note that this argument's type is ID in API versions 2023-10 and later. |
Clear an item's updates
The clear_item_updates
mutation allows you to clear all updates on a specific item, including replies and likes. You can also specify what fields to query back from the item when you run the mutation.
mutation {
clear_item_updates (item_id: 1234567890) {
id
}
}
let query = "mutation { clear_item_updates (item_id: 1234567890) { 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 specify which item to clear updates from.
Arguments | Description |
---|---|
item_id Int! | The item's unique identifier. Please note that this argument's type is ID! in API versions 2023-10 and later. |
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! 😎
Updated 18 days ago