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 specific items. This method accepts various arguments and returns an array.

You can only query items at the root, so it can't be nested within another query (like boards). You can return up to 100 items at a time using the ids argument. To return all items on a board, use the items_page object instead.

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 `[ID!]`	The IDs of the specific items to return. You can only return up to 100 IDs at a time.
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.	linked_board_id `ID!` 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`
url `String!`	The item's URL. Please note that this is only available in API versions `2024-04` and later.

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.

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	Accepted values
board_id `ID!`	The board's unique identifier.
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.
position_relative_method `PositionRelative`	The desired position of the new item. Please note that this argument is only available in API versions `2024-04` and later.	You can use this argument in conjunction with `relative_to` to specify which item you want to create the new item above or below. - `before_at`: This enum value creates the new item above the `relative_to` value. If you don't use the `relative_to` argument, the new item will be created at the bottom of the first active group (unless you specify a group using `group_id`). - `after_at`: This enum value creates the new item below the `relative_to` value. If you don't use the `relative_to` argument, the new item will be created at the top of the first active group (unless you specify a group using `group_id`).
relative_to `ID`	The unique identifier of the item you want to create the new one in relation to. You can also use this argument in conjunction with `position_relative_method` to specify if you want to create the new item above or below the item in question. Please note that this argument is only available in API versions `2024-04` and later.

🚧
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 `ID!`	The board's unique identifier.
item_id `ID`	The item's unique identifier. Required.
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 `ID`	The item's unique identifier.

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.

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. All column types can be mapped. 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_columns_mapping `[ColumnMappingInput!]`	The object that defines the subitems' column mapping between the original and target board. All column types can be mapped. 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 `ID`	The item's unique identifier.

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 `ID`	The item's unique identifier.

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 `ID!`	The 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! 😎

Items

Queries

Arguments

Fields

Mutations

Create an item

Arguments

🚧
Changing an item's name

Duplicate an item

Arguments

Move item to group

Arguments

Move item to board

Arguments

Archive an item

Arguments

Delete an item

Arguments

Clear an item's updates

Arguments

📘
Join our developer community!

Queries

Arguments

Fields

Mutations

Create an item

Arguments

🚧Changing an item's name

Duplicate an item

Arguments

Move item to group

Arguments

Move item to board

Arguments

Archive an item

Arguments

Delete an item

Arguments

Clear an item's updates

Arguments

📘Join our developer community!

🚧
Changing an item's name

📘
Join our developer community!