Getting started

The Archive API is a single GraphQL endpoint. Every request is a POST to /api/v2 — in production, https://app.archive.com/api/v2. You select exactly the fields you want on the Query type, and Archive returns just those. This guide takes you from a token to your first page of content.

Before you start

You need an API token. Provision one yourself from the Integration tab in the Archive app — no support ticket required. If your workspace belongs to an organization, the token is agency-wide and reaches every workspace in the org; otherwise it is scoped to the single workspace. Re-provisioning rotates the token and immediately disables the previous one, so treat it like any other secret. See the Authentication guide for the full token model.

Step 1 — List your workspaces

Start with the workspaces query. It is the one operation that needs only your token: no WORKSPACE-ID header is required, because its whole job is to tell you which workspaces your token 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"
      }
    }
  }
}

Each node carries an id — a workspace UUID. Pick the one you want to work in.

Step 2 — Pin a workspace

Now set the WORKSPACE-ID header to that UUID and confirm you can read the workspace. From here on, every workspace-scoped operation reads from whichever workspace this header names.

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

Step 3 — Fetch your first page of items

Items are the social content in a workspace — posts, Reels, Stories, and more. The items query is Relay-style: pass first for the page size and read pageInfo to page forward.

query.graphql

query ItemsDefault($first: Int, $after: String) {
  items(first: $first, after: $after) {
    totalCount
    edges {
      node {
        id
        provider
        type
        caption
        takenAt
        originalUrl
        archivePublicUrl
        currentEngagement {
          likes
          comments
          views
          earnedMediaValue
        }
      }
    }
    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 ItemsDefault($first: Int, $after: String) {\n  items(first: $first, after: $after) {\n    totalCount\n    edges {\n      node {\n        id\n        provider\n        type\n        caption\n        takenAt\n        originalUrl\n        archivePublicUrl\n        currentEngagement {\n          likes\n          comments\n          views\n          earnedMediaValue\n        }\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 ItemsDefault($first: Int, $after: String) {
  items(first: $first, after: $after) {
    totalCount
    edges {
      node {
        id
        provider
        type
        caption
        takenAt
        originalUrl
        archivePublicUrl
        currentEngagement {
          likes
          comments
          views
          earnedMediaValue
        }
      }
    }
    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 ItemsDefault($first: Int, $after: String) {
    items(first: $first, after: $after) {
      totalCount
      edges {
        node {
          id
          provider
          type
          caption
          takenAt
          originalUrl
          archivePublicUrl
          currentEngagement {
            likes
            comments
            views
            earnedMediaValue
          }
        }
      }
      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 ItemsDefault($first: Int, $after: String) {
  items(first: $first, after: $after) {
    totalCount
    edges {
      node {
        id
        provider
        type
        caption
        takenAt
        originalUrl
        archivePublicUrl
        currentEngagement {
          likes
          comments
          views
          earnedMediaValue
        }
      }
    }
    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 OK183 lines · expand

{
  "data": {
    "items": {
      "totalCount": 30,
      "edges": [
        {
          "node": {
            "id": "452a119f-393e-5edf-a7f7-f563294f3885",
            "provider": "INSTAGRAM",
            "type": "REEL",
            "caption": "Reel #29 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-30T00:00:00Z",
            "originalUrl": "https://instagram.com/p/docs-item-29",
            "archivePublicUrl": "https://example.com/m/s/45c2aca7-5351-5774-8196-b9346e58a099/6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
            "currentEngagement": {
              "likes": "390",
              "comments": "39",
              "views": "0",
              "earnedMediaValue": "780"
            }
          }
        },
        {
          "node": {
            "id": "d8a538a5-8857-5c0c-b3fb-a2b83c8d2a0b",
            "provider": "YOUTUBE",
            "type": "POST",
            "caption": "Post #28 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-29T00:00:00Z",
            "originalUrl": "https://www.youtube.com/watch?v=docs-item-28",
            "archivePublicUrl": "https://example.com/m/s/037514fd-8da6-5fc4-ab1f-57074132ad11/6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
            "currentEngagement": {
              "likes": "380",
              "comments": "38",
              "views": "0",
              "earnedMediaValue": "760"
            }
          }
        },
        {
          "node": {
            "id": "330cce49-6139-5672-9c61-33fb35bc73e2",
            "provider": "TIKTOK",
            "type": "SHORT",
            "caption": "Short #27 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-28T00:00:00Z",
            "originalUrl": "https://www.tiktok.com/@/video/docs-item-27",
            "archivePublicUrl": "https://example.com/m/s/35e07388-1dc7-5548-b990-0fa5200dd19e/6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
            "currentEngagement": {
              "likes": "370",
              "comments": "37",
              "views": "0",
              "earnedMediaValue": "740"
            }
          }
        },
        {
          "node": {
            "id": "a61d036b-fe79-538c-bbbb-1f97162cab3c",
            "provider": "INSTAGRAM",
            "type": "STORY",
            "caption": "Story #26 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-27T00:00:00Z",
            "originalUrl": null,
            "archivePublicUrl": "https://example.com/m/s/e0d46669-65b0-5b97-ba72-7d6f6a8b3099/6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
            "currentEngagement": {
              "likes": "360",
              "comments": "36",
              "views": "0",
              "earnedMediaValue": "720"
            }
          }
        },
        {
          "node": {
            "id": "de1860a7-2d98-5eda-8977-116583725c74",
            "provider": "YOUTUBE",
            "type": "REEL",
            "caption": "Reel #25 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-26T00:00:00Z",
            "originalUrl": "https://www.youtube.com/watch?v=docs-item-25",
            "archivePublicUrl": "https://example.com/m/s/bd465566-b4a2-508a-a66d-f0ad5b740aed/6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
            "currentEngagement": {
              "likes": "350",
              "comments": "35",
              "views": "0",
              "earnedMediaValue": "700"
            }
          }
        },
        {
          "node": {
            "id": "3870b3f7-2066-56c1-b82e-f7c606c863fa",
            "provider": "TIKTOK",
            "type": "POST",
            "caption": "Post #24 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-25T00:00:00Z",
            "originalUrl": "https://www.tiktok.com/@/video/docs-item-24",
            "archivePublicUrl": "https://example.com/m/s/284c38ea-a14f-51a9-adc4-ec3a2779c5de/6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
            "currentEngagement": {
              "likes": "340",
              "comments": "34",
              "views": "0",
              "earnedMediaValue": "680"
            }
          }
        },
        {
          "node": {
            "id": "2adb5caf-5619-5fc5-b738-ba264cb394a7",
            "provider": "INSTAGRAM",
            "type": "SHORT",
            "caption": "Short #23 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-24T00:00:00Z",
            "originalUrl": null,
            "archivePublicUrl": "https://example.com/m/s/f803ccf8-ebd1-5c7a-8ba4-fc18c1a4d914/6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
            "currentEngagement": {
              "likes": "330",
              "comments": "33",
              "views": "0",
              "earnedMediaValue": "660"
            }
          }
        },
        {
          "node": {
            "id": "5b570218-bf6a-5e05-9389-2f9bfe7f73ce",
            "provider": "YOUTUBE",
            "type": "STORY",
            "caption": "Story #22 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-23T00:00:00Z",
            "originalUrl": "https://www.youtube.com/watch?v=docs-item-22",
            "archivePublicUrl": "https://example.com/m/s/dfdb3836-77f2-5dbc-8ea7-5110924d16c0/6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
            "currentEngagement": {
              "likes": "320",
              "comments": "32",
              "views": "0",
              "earnedMediaValue": "640"
            }
          }
        },
        {
          "node": {
            "id": "24bd35e7-4ae8-546b-bc76-b9cee5e1107f",
            "provider": "TIKTOK",
            "type": "REEL",
            "caption": "Reel #21 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-22T00:00:00Z",
            "originalUrl": "https://www.tiktok.com/@/video/docs-item-21",
            "archivePublicUrl": "https://example.com/m/s/4b328433-86dc-593d-918a-d435836c868d/6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
            "currentEngagement": {
              "likes": "310",
              "comments": "31",
              "views": "0",
              "earnedMediaValue": "620"
            }
          }
        },
        {
          "node": {
            "id": "5503f877-fd11-5373-b372-ce4738980780",
            "provider": "INSTAGRAM",
            "type": "POST",
            "caption": "Post #20 from Northwind Botanicals #northwindbotanicals #plantcare #growwithnorthwind @northwindbotanicals",
            "takenAt": "2024-11-21T00:00:00Z",
            "originalUrl": "https://instagram.com/p/docs-item-20",
            "archivePublicUrl": "https://example.com/m/s/90f4b06d-bdca-5b74-871a-7c879309c9b9/6ccefa76-e8ba-5ab0-9c60-e48a9e235a4a",
            "currentEngagement": {
              "likes": "300",
              "comments": "30",
              "views": "0",
              "earnedMediaValue": "600"
            }
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "Z2lkOi8vYXJjaGl2ZS9JdGVtLzU1MDNmODc3LWZkMTEtNTM3My1iMzcyLWNlNDczODk4MDc4MA=="
      }
    }
  }
}

Where to go next

Authentication — obtaining, rotating, and securing tokens.
Workspaces — the WORKSPACE-ID model and which operations need it.
Pagination — cursor loops, page bounds, and cost.
Filtering & search — narrow items by date, engagement, and semantic search.
API reference — every query, mutation, and type.