# addItemToCollections

Mutation

Add an item to one or more collections.

Available to agents as MCP tool `addItemToCollections` — see [Write tools](/api/v2/docs/mcp/write-tools#add-item-to-collections).

## Arguments

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `autoCreate` | `Boolean` | No | `false` | Automatically create collections by name if they do not exist. |
| `collectionIds` | `[ID!]` | No | `[]` | IDs of existing collections, as returned by the `collections` query for this workspace. Several id forms are accepted depending on how the workspace stores Collections. An id from another workspace, or one this workspace cannot write through this API, rejects the WHOLE call with a userErrors entry naming the offending id under `collectionIds`. |
| `collectionNames` | `[String!]` | No | `[]` | Names of collections to add the item to. |
| `itemId` | `ID!` | Yes | — | ID of the item to add to collections. |

## Returns

| Name | Type | Description |
| --- | --- | --- |
| `item` | [`Item`](/api/v2/docs/types/item) | The updated item. |
| `userErrors` | [`[UserError!]!`](/api/v2/docs/types/user-error) | List of errors that occurred. |

## Examples

### Add an item to collections

Tag an item into one or more existing collections.

```graphql
mutation AddItemToCollectionsDefault($itemId: ID!, $collectionIds: [ID!]) {
  addItemToCollections(itemId: $itemId, collectionIds: $collectionIds) {
    item {
      id
      customAttributes
    }
    userErrors {
      field
      message
    }
  }
}
```

Variables:

```json
{
  "itemId": "63c311c4-32f0-5d8c-ac02-78b160f2290a",
  "collectionIds": [
    "122321ce-843e-5b07-9f56-94323c0ae39e"
  ]
}
```

Response — HTTP 200:

```json
{
  "data": {
    "addItemToCollections": {
      "item": {
        "id": "63c311c4-32f0-5d8c-ac02-78b160f2290a",
        "customAttributes": {
          "sentiment": "positive",
          "collections": [
            "6e485f10-8ffc-52be-8efa-962eef90a674"
          ]
        }
      },
      "userErrors": []
    }
  }
}
```