API reference

This is the reference for /api/, the dated Capa API. It is written for a developer wiring another system into Capa: a storefront, an internal tool, a sync job, an agent.

What is here todayCopy Anchor Link

Nine routes exist:

The entry routes are the whole of Entries, the three page routes are in Pages, and GraphQL is in GraphQL. Schema, types, search, media, nested collections and writes are not built yet. A GET that matches no route answers 404 route_not_found. A POST, PUT, PATCH or DELETE answers 405 mutations_not_enabled, on every host, whatever the path and whether or not you send a key. The one exception is POST /api/graphql, which reads. Both are the error envelope below, so an integration written today already parses what the write phases will send.

Your existing integration does not change. /v2/api, /v3/api, /v2/schema, /v2/seo and /files keep serving the bytes they serve today, with the key they serve them with today. The exceptions are privacy and tenant-isolation fixes. Those on /v2/api and /v3/api are listed in What changed in October 2026. /api/ is a second surface you move to when you want to, route by route. The reference for /v2/api and /v3/api is Legacy API: /v2/api and /v3/api.

A requestCopy Anchor Link

export CAPA_KEY=...          # your key, from your secret store. Never in a script.
curl https://cdn.capacms.com/api/me \
  -H "x-api-key: $CAPA_KEY" \
  -H 'Capa-Version: 2026-10-01'

A responseCopy Anchor Link

Every successful body has a data key and a meta key, in that order. The exception is /api/graphql, which answers in GraphQL's own shape: data, then extensions, with the request id in the X-Request-Id header (see GraphQL).

This is GET /api/versions?from=2026-10-01, which takes no key:

{ "data": { "current": "2026-10-01", "versions": [] },
  "meta": { "version": "2026-10-01", "requestId": "req_0f3c…" } }

meta.requestId identifies one request. Quote it when you report a problem. GET /api/versions is cacheable for five minutes, so a cached answer carries the id of the request that filled the cache.

One case skips the envelope: a URL the server cannot parse at all, such as /api/%zz, is refused by the HTTP layer with a plain 400 before any route runs.

Response headers you can rely on:

Origin leads every Vary because CORS reflects the calling origin back in Access-Control-Allow-Origin. GET /api/versions is the one cacheable response here, and a cache that ignored Origin on it could hand one site's Access-Control-Allow-Origin to another for five minutes.

On /api/, the key itself is never echoed in a response header, a log line or an error body. The legacy /v2/api and /v3/api routes still send it back in an API-Key response header.

ErrorsCopy Anchor Link

One envelope, on every /api/ route but /api/graphql, whose errors are GraphQL errors: an errors list, each with the same code, type, hint and docs inside its extensions (see GraphQL).

{ "error": { "type": "authentication",
             "code": "invalid_key",
             "message": "This API key is not valid.",
             "docs": "https://docs.capacms.com/errors/invalid_key" },
  "meta": { "version": "2026-10-01", "contract": 1, "requestId": "req_0f3c…" } }

There is never a data key beside error. A 500 never carries details.

Codes any /api/ route can answer:

The entry routes add eight more 400 codes for the query grammar, 404 model_not_found, 404 entry_not_found and 504 query_timeout. They are all in Entries with what each hint tells you.

401 invalid_key is deliberately the same answer for an unknown key, a revoked key and an expired key. It does not tell an attacker which one it was. If a key that worked yesterday stops working, check its expiry and its active flag under Developers > Keys rather than reading the body.

Who am ICopy Anchor Link

GET /api/me answers what the key in your hand can actually do. It is the fastest way to check a key before you debug anything else.

{ "data": { "keyId": "…00a7", "name": "Shopify sync", "keyPrefix": "cap_live_EXAM",
            "environment": "production", "bundle": "scoped",
            "surfaces": ["/api/"],
            "scopes": ["instance:read", "model:read"],
            "models": [ { "namespace": "articles", "id": "…0003", "can": ["read"] } ],
            "version": "2026-10-01", "contract": 1,
            "legacy": { "contract": null, "legacyRefused": true, "reason": "surface" },
            "expiresAt": null, "lastUsedAt": null, "rotatedFrom": null,
            "writes": { "enabled": false },
            "tenant": { "id": "…d49a1", "name": "Acme" } },
  "meta": { "version": "2026-10-01", "contract": 1, "environment": "production",
            "requestId": "req_0f3c…" } }

Every field is always present.

EnvironmentsCopy Anchor Link

A key carries an environment. production sees published entries only. Anything else also sees drafts.

It is a read-visibility dial, not a sandbox. There is one database. A cap_test_ key that holds instance:publish publishes to your live site. If you want somewhere safe to break things, duplicate the project.