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. Take one row, fill it with whatever information you'd like, and you now have an item!

🚧

Want to read all items on a board?

The items object allows you to query specific items by their IDs. If you want to read all items on a board, use the items_page object instead!

Queries

You can use the items query to retrieve item data via the API.

• Required scope:boards:read
• Returns an array containing metadata about one or a collection of specific items
• Can only be queried directly at the root; can't be nested within another query

query {
  items(ids: [1234567890, 9876543210, 2345678901]) {
    name
  }
}

Arguments

You can use the following arguments to reduce the number of results returned in your items query.

Fields

You can use the following fields to specify what information your items query will return.

Mutations

The API allows you to create, update, and delete items using the following mutations. These operations let you programmatically control an item's full lifecycle.

Create item

Required scope:boards:write

The create_item mutation creates a new item via the API. You can specify which fields to return in the mutation response.

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 its 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
  }
}

Arguments

You can use the following arguments to define the new item's characteristics.

🚧

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 item

Required scope:boards:write

The duplicate_item mutation duplicates an item (or subitem) and its nested subitems via the API. You can specify which fields to return in the mutation response.

mutation {
  duplicate_item(
    board_id: 1234567890
    item_id: 9876543210 
    with_updates: true
	) {
    id
  }
}

Arguments

You can use the following arguments to specify which item to duplicate.

Change an item's position

Required scope:boards:write

The change_item_position mutation changes an item's position on the same board via the API. You can specify which fields to return in the mutation response.

mutation { 
 change_item_position(
  item_id: 1234567890
  relative_to: 9876543210
  position_relative_method: after_at
 ) {
  id
  group {
   id
  }
 }
}

Arguments

You can use the following arguments to define the item's new location.

Update assets on item

Required scope:boards:write

The update_assets_on_item mutation updates a file column's existing files via the API. You can specify which fields to return in the mutation response.

mutation {
  update_assets_on_item(
    board_id: 1234567890
    item_id: 9876543210
    column_id: "YOUR_COLUMN_ID"
    files: {
      fileType: asset
      name: "New asset"
      assetId: 12345
      linkToFile: "https://yourlink.com"
    }
  ) {
    assets {
      id
      name
      url
    }
  }
}

Arguments

You can use the following arguments to specify which item's file to update.

Move item to group

Required scope:boards:write

The move_item_to_group mutation moves an item (or subitem) and its nested subitems between groups on the same board via the API. You can specify which fields to return in the mutation response.

🚧

Multi-level board validations

The operation will be blocked if it would create a parent–child cycle (e.g., an item becoming an ancestor or descendant of itself) or if the resulting depth on the target board would exceed 5.

mutation {
  move_item_to_group(
    item_id: 1234567890, 
    group_id: "group_one"
	) {
    id
  }
}

Arguments

You can use the following arguments to specify which item to move and where.

Move item to board

Required scope:boards:write

The move_item_to_board mutation moves an item (or subitem) and its nested subitems to a different board via the API. You can specify which fields to return in the mutation response.

🚧

Multi-level board validations

The operation will be blocked if it would create a parent–child cycle (e.g., an item becoming an ancestor or descendant of itself) or if the resulting depth on the target board would exceed 5.

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
  }
}

Arguments

You can use the following arguments to specify which item to move and where.

Archive item

Required scope:boards:write

The archive_item mutation archives an item (or subitem) and its nested subitems via the API. You can specify which fields to return in the mutation response.

mutation {
  archive_item(
    item_id: 1234567890
	) {
    id
  }
}

Arguments

You can use the following argument to specify which item to archive.

Clear item updates

Required scope:boards:write

The clear_item_updates mutation clears all updates on a specific item, including replies and likes, via the API. You can specify which fields to return in the mutation response.

mutation {
  clear_item_updates(
    item_id: 1234567890
	) {
    id
  }
}

Arguments

You can use the following argument to specify which item to clear updates from.

Delete item

Required scope:boards:write

The delete_item mutation deletes an item (or subitem) and its nested subitems via the API. You can specify which fields to return in the mutation response.

mutation {
  delete_item(
    item_id: 1234567890
	) {
    id
  }
}

Arguments

You can use the following argument to specify which item to delete.