addItemToCollections

Add an item to one or more collections.

MCP: addItemToCollections

Arguments

autoCreate Boolean default: false: Automatically create collections by name if they do not exist.
collectionIds [ID!] default: []: 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!] default: []: Names of collections to add the item to.
itemId ID! required: ID of the item to add to collections.

Returns

item Item: The updated item.
userErrors [UserError!]!: List of errors that occurred.

Open in explorer ↗

Values are sampled from a demo workspace — substitute your own token and workspace id.

Tag an item into one or more existing collections.

query.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"
  ]
}

Headers

Authorization: Bearer docs_demo_token_0000000000000000000000
WORKSPACE-ID: 6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a

Request · cURL

curl https://app.archive.com/api/v2 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer docs_demo_token_0000000000000000000000' \
  -H 'WORKSPACE-ID: 6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a' \
  -d '{
  "query": "mutation AddItemToCollectionsDefault($itemId: ID!, $collectionIds: [ID!]) {\n  addItemToCollections(itemId: $itemId, collectionIds: $collectionIds) {\n    item {\n      id\n      customAttributes\n    }\n    userErrors {\n      field\n      message\n    }\n  }\n}",
  "variables": {
    "itemId": "63c311c4-32f0-5d8c-ac02-78b160f2290a",
    "collectionIds": [
      "122321ce-843e-5b07-9f56-94323c0ae39e"
    ]
  }
}'

Request · Node.js

const response = await fetch("https://app.archive.com/api/v2", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer docs_demo_token_0000000000000000000000",
    "WORKSPACE-ID": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a"
  },
  body: JSON.stringify({
    query: `mutation AddItemToCollectionsDefault($itemId: ID!, $collectionIds: [ID!]) {
  addItemToCollections(itemId: $itemId, collectionIds: $collectionIds) {
    item {
      id
      customAttributes
    }
    userErrors {
      field
      message
    }
  }
}`,
    variables: {
      "itemId": "63c311c4-32f0-5d8c-ac02-78b160f2290a",
      "collectionIds": [
        "122321ce-843e-5b07-9f56-94323c0ae39e"
      ]
    }
  })
})
console.log(JSON.stringify(await response.json(), null, 2))

Request · Ruby

require "json"
require "net/http"

query = <<~'GRAPHQL'
  mutation AddItemToCollectionsDefault($itemId: ID!, $collectionIds: [ID!]) {
    addItemToCollections(itemId: $itemId, collectionIds: $collectionIds) {
      item {
        id
        customAttributes
      }
      userErrors {
        field
        message
      }
    }
  }
GRAPHQL

response = Net::HTTP.post(
  URI("https://app.archive.com/api/v2"),
  { query: query, variables: { "itemId" => "63c311c4-32f0-5d8c-ac02-78b160f2290a", "collectionIds" => ["122321ce-843e-5b07-9f56-94323c0ae39e"] } }.to_json,
  "Content-Type" => "application/json",
  "Authorization" => "Bearer docs_demo_token_0000000000000000000000",
  "WORKSPACE-ID" => "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a"
)
puts response.body

Request · Python

import json
import requests

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

response = requests.post(
    "https://app.archive.com/api/v2",
    json={"query": query, "variables": {"itemId": "63c311c4-32f0-5d8c-ac02-78b160f2290a", "collectionIds": ["122321ce-843e-5b07-9f56-94323c0ae39e"]}},
    headers={
        "Authorization": "Bearer docs_demo_token_0000000000000000000000",
        "WORKSPACE-ID": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
    },
)
print(json.dumps(response.json(), indent=2))

200 OK

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