generated: '2026-08-13'
method: searched
source: https://api-docs.archive.com
description: >-
  Cross-cutting request/response conventions for the Archive GraphQL API that apply to every
  operation: transport, authentication, workspace scoping, pagination, error envelopes, rate
  limiting, versioning, and agent-specific handling notes. Captured from the Archive API
  documentation (api-docs.archive.com) and the "For Coding Agents" guide.
base_url: https://app.archive.com/api/v2
api_style: GraphQL over HTTPS. Single POST endpoint; JSON request/response.
authentication:
  scheme: Bearer token (Authorization header) + WORKSPACE-ID header
  token_prefix: arch_live_
  detail: authentication/archive-technologies-authentication.yml
workspace_scoping:
  header: WORKSPACE-ID
  value: workspace UUID
  note: Must be sent as a header, never in the request body. Scopes the query to one workspace/agency.
idempotency:
  supported: false
  note: >-
    No idempotency-key mechanism is documented for the GraphQL API. Reads are naturally
    idempotent; mutations are not deduplicated by a client-supplied key. Idempotency keys are
    announced only for the not-yet-shipped outbound-webhooks feature (docs Roadmap, "Coming
    soon"), which is a delivery guarantee on Archive's side rather than a request-dedup
    contract for callers. No Idempotency pointer is emitted in apis.yml for this reason.
  partial_update_semantics: >-
    View updates are partial — omitted fields keep their values (update*View mutations).
  natural_keys:
    addItemToCollections: >-
      collectionNames + autoCreate:true is name-addressed rather than id-addressed, so
      re-running the same call converges on the same Collection instead of creating duplicates.
pagination:
  style: cursor
  request_params:
    first: results per page, maximum 100
    after: cursor from the previous page's pageInfo.endCursor
  response_fields:
    nodes: array of results
    totalCount: total results across all pages
    pageInfo:
      hasNextPage: more pages exist
      hasPreviousPage: previous pages exist
      endCursor: bookmark for the next request
      startCursor: bookmark for the first item on the current page
  paginated_queries: [items, creators, engagementHistory, workspaces, socialProfiles]
  docs: https://api-docs.archive.com/concepts/pagination
data_typing:
  bigint_fields_as_strings: >-
    BigInt engagement fields (likes, views, comments, shares, EMV) arrive as strings and
    require explicit numeric casting client-side.
error_envelope:
  detail: errors/archive-technologies-problem-types.yml
  query_errors: top-level `errors` array (HTTP 200)
  mutation_errors: >-
    `userErrors` field within the mutation result (HTTP 200); must be handled even on 200.
  rate_limit_errors: HTTP 429 with extensions.code RATE_LIMIT_EXCEEDED
rate_limiting:
  detail: rate-limits/archive-technologies-rate-limits.yml
  limits:
    flat_ceiling: 5 requests per second per workspace
    credit_budget: per-plan burst + per-second refill; 1 credit = 1 ms of backend compute
  binds: whichever of the two is reached first
  response_headers:
    ratelimit-policy: '"<plan>";q=<burst>;w=<window seconds>  e.g. "growth";q=15000;w=60'
    ratelimit: '"<plan>";r=<credits remaining>;t=<unix time when full>'
    Retry-After: seconds to wait, returned on 429
  breach_status: 429
  breach_code: RATE_LIMIT_EXCEEDED
  guidance: >-
    Every response carries the IETF ratelimit / ratelimit-policy headers, so a client never
    has to discover a limit through an error: read `r` (credits remaining) and self-throttle
    against it. The quoted plan name in the header also tells a caller which plan tier it is
    on. Retry-After is honoured on 429. Docs recommend a client-side token bucket set to the
    plan's refill rate and shared across processes hitting the same workspace.
  shared_budget_note: >-
    The hosted MCP server draws on the SAME per-workspace budget — an agent working a long
    task competes for credits with the workspace's own integrations.
versioning:
  scheme: uri-path
  current: v2
  detail: lifecycle/archive-technologies-lifecycle.yml
query_constraints:
  max_query_depth: 10
  max_page_size: 100
  introspection: disabled in production (no __schema queries)
  schema_of_record: graphql/archive-technologies.graphql
date_handling:
  format: RFC 3339 UTC only — must end with Z, +00:00 or -00:00
  note: >-
    A real offset such as -03:00 is rejected; convert to UTC first. The rejection arrives
    under extensions.code INTERNAL_SERVER_ERROR even though the input is at fault.
agent_notes:
  source: https://api-docs.archive.com/guides/for-coding-agents
  guidance:
  - Do not extrapolate parameter names from other GraphQL APIs; only what api-docs.archive.com documents exists.
  - Always pass WORKSPACE-ID as a header, not in the body.
  - Handle userErrors on mutations even when the HTTP status is 200.
  - Cast BigInt engagement fields (returned as strings) explicitly.
  - Respect the hard 5 RPS per-workspace cap; treat 429 as a client throttling failure.