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 the fields you want on the Query type, and Archive returns only those fields. This guide walks you through your first requests, from creating a token to fetching a page of content.

Before you start

You need an API token. You can create one yourself from the Integration tab in the Archive app. If your workspace belongs to an organization, the token works across every workspace in that organization; otherwise it is scoped to the workspace it was issued for. Creating a new token invalidates the previous one, so store it as you would any other secret. See Authentication for the full token model.

Step 1: List your workspaces

Start with the workspaces query. It’s the only operation that doesn’t require a WORKSPACE-ID header: it takes your token and returns the workspaces that token can access.

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 19 lines

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

Each node includes an id, the workspace UUID. Note the ID of the workspace you want to work with.

Step 2: Set the workspace header

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

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 8 lines

{
  "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 other captured media. The items query uses Relay-style pagination. Pass first to set the page size and read pageInfo to fetch subsequent pages.

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 OK 183 lines

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

Next steps

Core concepts — what items, creators, Collections, and views actually are.
Authentication — creating, 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.