Jump to examples ↓

Mutation

createLabels

Create labels in the workspace creator label taxonomy; a name already present (ignoring case and surrounding whitespace) is returned unchanged.

MCP: createLabels

Arguments

labelNames [String!]! required: Label names to create. At least 1 and at most 50, each at most 100 characters. Matching ignores case and surrounding whitespace, so a name that already exists is returned with its stored spelling and nothing is created.

Returns

Object, input and enum types open in place — use + to reveal their fields. A type that is already open above the row stops at a ↻ circular marker, and anything nested past the depth limit links out to its own page instead.

labels [Label!]!: The stored spelling of every submitted name, in submission order. Names that differ only by case or surrounding whitespace collapse to one entry. Empty when userErrors is non-empty.
deleting Boolean!: True while a workspace-wide deletion of this label is in progress. The label leaves this list once the deletion finishes; do not assign it, and do not recreate it until it disappears from this list.
name String!: The label as stored for this workspace (the spelling a customer typed). Pass this spelling back as-is; matching ignores case and surrounding whitespace.
userErrors [UserError!]!: Errors that refused the whole request: an empty or oversized list, a blank or over-long name, or a label being deleted. Empty on success.
field [String!]: Path to the input field that caused the error.
message String!: The error message.

Open in explorer ↗

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

Create labels by name; a name the workspace already carries is returned with its stored spelling.

query.graphql

mutation CreateLabelsDefault($labelNames: [String!]!) {
  createLabels(labelNames: $labelNames) {
    labels {
      name
      deleting
    }
    userErrors {
      field
      message
    }
  }
}

variables.json

{
  "labelNames": [
    "Holiday 2025",
    "vip"
  ]
}

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 CreateLabelsDefault($labelNames: [String!]!) {\n  createLabels(labelNames: $labelNames) {\n    labels {\n      name\n      deleting\n    }\n    userErrors {\n      field\n      message\n    }\n  }\n}",
  "variables": {
    "labelNames": [
      "Holiday 2025",
      "vip"
    ]
  }
}'

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 CreateLabelsDefault($labelNames: [String!]!) {
  createLabels(labelNames: $labelNames) {
    labels {
      name
      deleting
    }
    userErrors {
      field
      message
    }
  }
}`,
    variables: {
      "labelNames": [
        "Holiday 2025",
        "vip"
      ]
    }
  })
})
console.log(JSON.stringify(await response.json(), null, 2))

Request · Ruby

require "json"
require "net/http"

query = <<~'GRAPHQL'
  mutation CreateLabelsDefault($labelNames: [String!]!) {
    createLabels(labelNames: $labelNames) {
      labels {
        name
        deleting
      }
      userErrors {
        field
        message
      }
    }
  }
GRAPHQL

response = Net::HTTP.post(
  URI("https://app.archive.com/api/v2"),
  { query: query, variables: { "labelNames" => ["Holiday 2025", "vip"] } }.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 CreateLabelsDefault($labelNames: [String!]!) {
  createLabels(labelNames: $labelNames) {
    labels {
      name
      deleting
    }
    userErrors {
      field
      message
    }
  }
}
"""

response = requests.post(
    "https://app.archive.com/api/v2",
    json={"query": query, "variables": {"labelNames": ["Holiday 2025", "vip"]}},
    headers={
        "Authorization": "Bearer docs_demo_token_0000000000000000000000",
        "WORKSPACE-ID": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
    },
)
print(json.dumps(response.json(), indent=2))

200 OK 17 lines

{
  "data": {
    "createLabels": {
      "labels": [
        {
          "name": "Holiday 2025",
          "deleting": false
        },
        {
          "name": "VIP",
          "deleting": false
        }
      ],
      "userErrors": []
    }
  }
}