Workspaces

Most data in Archive is scoped to a workspace — typically a single brand or region. You choose which workspace a request reads from by sending its UUID in the WORKSPACE-ID header.

WORKSPACE-ID: <workspace-uuid>

Finding workspace IDs

A workspace ID is the id returned by the workspaces query, which lists every workspace your token can access. You can also copy it from the Archive app UI. The workspaces query is the one operation that does not require a WORKSPACE-ID header — it relies only on your token, since its purpose is to enumerate the workspaces you can reach.

query.graphql

query WorkspacesDefault($first: Int, $after: String) {
  workspaces(first: $first, after: $after) {
    totalCount
    edges {
      node {
        id
        name
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

variables.json

{
  "first": 10
}

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": "query WorkspacesDefault($first: Int, $after: String) {\n  workspaces(first: $first, after: $after) {\n    totalCount\n    edges {\n      node {\n        id\n        name\n      }\n    }\n    pageInfo {\n      hasNextPage\n      endCursor\n    }\n  }\n}",
  "variables": {
    "first": 10
  }
}'

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: `query WorkspacesDefault($first: Int, $after: String) {
  workspaces(first: $first, after: $after) {
    totalCount
    edges {
      node {
        id
        name
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}`,
    variables: {
      "first": 10
    }
  })
})
console.log(JSON.stringify(await response.json(), null, 2))

Request · Ruby

require "json"
require "net/http"

query = <<~'GRAPHQL'
  query WorkspacesDefault($first: Int, $after: String) {
    workspaces(first: $first, after: $after) {
      totalCount
      edges {
        node {
          id
          name
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
GRAPHQL

response = Net::HTTP.post(
  URI("https://app.archive.com/api/v2"),
  { query: query, variables: { "first" => 10 } }.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 = """
query WorkspacesDefault($first: Int, $after: String) {
  workspaces(first: $first, after: $after) {
    totalCount
    edges {
      node {
        id
        name
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
"""

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

200 OK

{
  "data": {
    "workspaces": {
      "totalCount": 1,
      "edges": [
        {
          "node": {
            "id": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
            "name": "Northwind Botanicals"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "Z2lkOi8vYXJjaGl2ZS9Xb3Jrc3BhY2UvOTkwMTAx"
      }
    }
  }
}

Which operations are workspace-scoped

Every operation is workspace-scoped except workspaces. Queries like workspace, items, creators, and transcriptions all read from the workspace named by the header, so they need it on every call. Pin the header once and reuse it across the whole session:

query.graphql

query WorkspaceDefault {
  workspace {
    id
    name
  }
}

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": "query WorkspaceDefault {\n  workspace {\n    id\n    name\n  }\n}"
}'

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: `query WorkspaceDefault {
  workspace {
    id
    name
  }
}`
  })
})
console.log(JSON.stringify(await response.json(), null, 2))

Request · Ruby

require "json"
require "net/http"

query = <<~'GRAPHQL'
  query WorkspaceDefault {
    workspace {
      id
      name
    }
  }
GRAPHQL

response = Net::HTTP.post(
  URI("https://app.archive.com/api/v2"),
  { query: query }.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 = """
query WorkspaceDefault {
  workspace {
    id
    name
  }
}
"""

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

200 OK

{
  "data": {
    "workspace": {
      "id": "6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
      "name": "Northwind Botanicals"
    }
  }
}

Missing or unknown workspaces

Two distinct failures can occur, and they mean different things:

No WORKSPACE-ID header on a workspace-scoped operation returns HTTP 400 with the body {"errors":"WORKSPACE-ID header is required"}.

400 Bad Request

{
  "errors": "WORKSPACE-ID header is required"
}

An unknown workspace, or one your token can’t reach, returns HTTP 404 with the body {"errors":"Shop not found"}.

404 Not Found

{
  "errors": "Shop not found"
}

Iterating across workspaces

With an agency-wide token you can work across every workspace in the org. List them once with workspaces, then loop: set WORKSPACE-ID to each workspace’s id in turn and issue your workspace-scoped queries against it. No re-authentication is needed between workspaces — only the header changes.

For the full error model, see the Errors guide.