Archive API docs
esc
    Jump to
    Getting started Token, first query, response Explorer Run queries in the browser items The connection most integrations start with Changelog Additions and deprecations

    Narrow by kind with a prefix — q: queries, m: mutations, t: types, g: guides, f: fields and arguments.

    MCP overview

    Archive runs a Model Context Protocol server so AI agents can work with your data directly: searching content, reading creator profiles, and managing saved views, without a custom GraphQL client.

    The MCP server exposes the same product surface as /api/v2. Every tool wraps exactly one public GraphQL root field and executes it directly, with the same resolvers, the same validation, the same workspace scoping, and the same weighted rate-limit charge. There is no second data path and no second permission model.

    Endpoint 
    POST https://app.archive.com/api/v2/mcp

    The transport is Streamable HTTP carrying JSON-RPC 2.0 request bodies. The endpoint is stateless: it issues no session ID, so every request must carry its own credentials.

    The tool surface

    There are 33 read tools and 31 write tools. The mapping between tools and GraphQL is one-to-one in both directions: every public query and mutation has exactly one tool, and every tool points at exactly one public field. Anything you can do on /api/v2, you can do over MCP, and each operation’s reference page links to the tool that wraps it.

    Tool names follow the GraphQL field in camelCase, except where a different name is clearer for agents: items is exposed as searchItems and creators as searchCreators. Everything else is get* for a read and the mutation’s own name for a write.

    Authentication

    The endpoint accepts two credential types, tried in this order:

    CredentialHow you get itWrite access
    Bearer tokenThe same API token you use for /api/v2, created in the Integration tabYes — parity with /api/v2, where any valid token can call every public mutation
    OAuth 2.1Your MCP client registers with Archive; the person authorizes it in-appOnly if they granted the optional write scope at consent time

    Archive is its own authorization server. Tokens are opaque, Archive-issued, and validated in process; there is no JWT to decode and no introspection endpoint to call. The server publishes RFC 9728 protected-resource metadata and RFC 8414 authorization-server metadata, and supports RFC 7591 Dynamic Client Registration, so a compliant client can discover and register on its own. See Connect a client.

    An unauthenticated initialize, tools/list, or tools/call returns HTTP 401 with a WWW-Authenticate challenge — the signal MCP clients use to begin the OAuth flow.

    Workspaces

    A credential is not bound to one workspace. The server resolves a workspace per tool call, in this order:

    1. The workspaceId argument on the call — a workspace UUID, or the numeric ID shown in the app.
    2. The WORKSPACE-ID header.
    3. The credential’s sole workspace, when it can access exactly one.

    Call getWorkspaces first. It’s the only tool that doesn’t need a workspace, and it returns every workspace the credential can access.

    A valid credential that can’t resolve the requested workspace doesn’t get a 401. It gets HTTP 200 with isError: true and a uniform message, identical for an unknown UUID, a workspace you’re not a member of, and one outside your grant, so the response can’t be used to discover which workspaces exist.

    Rate limits

    MCP calls spend from the same weighted per-workspace bucket as /api/v2, at the same prices: a read tool costs what its root field costs, and every write charges the flat mutation cost. Everything in the Rate limits guide applies here unchanged.

    What is not listed here