Management API

The Capa admin manages a project over these routes, and you can script them too. They run as a signed-in person, with that person's role in the project. Several are also mounted under /v2/agent/ for an API key.

They are older than /api/ and answer in their own shape: { "error": "<sentence>" }, usually with a code beside it, never the /api/ error envelope.

AuthenticationCopy Anchor Link

Send every request on this page to https://api.capacms.com, never to the CDN.

Sign in with an email and a password to get a session token:

curl -X POST https://api.capacms.com/v2/user/login \
  -H 'content-type: application/json' \
  -d '{"email":"maya@example.com","password":"…"}'
# {"accessToken":"eyJ…","refreshToken":"eyJ…"}

Then send the token as a bearer token:

curl https://api.capacms.com/v2/projects \
  -H "Authorization: Bearer $SESSION_TOKEN"

The access token lasts 24 hours. POST /v2/user/refresh-token with { "refreshToken": "…" } returns a new one, valid for 12 hours. Wrong credentials, and an account with no password, are 401 {"error":"Invalid credentials"}.

Which projectCopy Anchor Link

A request runs in the project you last opened. To choose one for a single request, send its id:

x-capa-project: 3f6c1a8e-2b4d-4c9a-9e21-7d5b0c8f4a12

The header only chooses. It never changes which project you last opened. API key requests ignore it: a key always acts in its own project.

With an API key insteadCopy Anchor Link

Scheduled publishing, publishing now, workspaces, entry layouts and field changes are mounted a second time under /v2/agent/, behind a legacy API key in x-api-key. The routes, bodies and answers are the same. What a key may do depends on its permission, and a refusal is 403 {"error":"Insufficient permissions"}. See Agent API.

Scheduled publishingCopy Anchor Link

Publish or unpublish entries at a time you choose.

curl -X POST https://api.capacms.com/v2/scheduled-actions \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "action": "publish",
    "targets": [{ "type": "instance", "id": "8b0a1f2e-7d34-4c55-9e51-0f9b1d225c3e" }],
    "wallTime": "2026-10-01T09:00",
    "timezone": "America/New_York"
  }'

• action is publish or unpublish. targets holds 1 to 500 entries or models. A model target also needs model:publish, which no API key holds.
• wallTime is a local clock time with no offset, and timezone is an IANA name. The server converts them and says what it decided in resolved. When daylight saving moved the time, resolved.note says so in a sentence you can show a person.
• The time must be at least 60 seconds ahead. Earlier is 400 with code: "in_the_past".
• A target has at most one active publish and one active unpublish. Scheduling another replaces the first, and replaced lists the ids it cancelled.
• With no versionId, an action publishes the latest draft at the time it runs.

The answer is 201 with a batchId, resolved, the actions and replaced. An action's status is pending, running, done, failed, dead or cancelled. Only a pending action can be rescheduled. A running one answers 409 with code: "already_running" to a cancel.

Publishing nowCopy Anchor Link

A bulk body names entries with instanceIds, or with modelId and a filter. Send "dryRun": true first to see what would happen, then send the count you were shown as expectedCount. If the selection changed in between, the answer is 409 with code: "selection_changed". Up to 50 entries publish inside the request. Above that the answer is 202 with a poll link to the batch.

WorkspacesCopy Anchor Link

A workspace is an arrangement of the admin's left rail: folders holding models, entries and media folders. Arranging one never changes a record.

A document is a list of nodes. A folder holds more nodes; a model is named by its namespace or id; an entry and a media folder by id:

curl -X PUT https://api.capacms.com/v2/workspaces/$WORKSPACE_ID/tree \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "mode": "merge",
    "tree": [
      { "folder": "Blog", "children": [{ "model": "blog_post" }, { "model": "author" }] },
      { "folder": "Media", "children": [{ "media_folder": "41a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8" }] }
    ]
  }'

merge adds what is missing and never removes. replace makes the workspace exactly the document. template on create is blank, website or catalog, and seeds top-level folders only.

A workspace is team, visible to everyone in the project, or private, visible to the person who made it. An API key can only create team workspaces.

Entry layoutsCopy Anchor Link

An entry layout arranges a model's fields in the entry editor, in cards across a main column and a side column. It is live as soon as it is saved: layouts are not versioned with the model.

:id is the model's id or its namespace.

curl -X PUT https://api.capacms.com/v2/models/blog_post/layout \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "layout": {
      "v": 1,
      "main": [{
        "t": "card", "id": "content", "title": "Content",
        "collapsible": false, "collapsed": false,
        "items": [{ "t": "field", "id": "f1", "fieldId": "41a2b3c4-d5e6-4f70-8192-a3b4c5d6e7f8", "width": "full" }]
      }],
      "aside": []
    }
  }'

A field item's width is full, two_thirds, half or third. A relation field may set display to picker, inline or embedded. A layout holds at most 50 cards and 500 fields, a card title at most 80 characters and a description at most 200. A body with no layout key is refused, so a typo never resets a layout. A refusal carries path, naming the part of the document to fix.

Field changesCopy Anchor Link

Changing a field's type, its array type, its relation or its namespace on a model that already has entries is a field change. You plan it, choose what happens to the values, then a background job converts them and moves the model to the new shape at the end.

The plan body holds the same editFields and removeIds you would send to update the model:

curl -X POST https://api.capacms.com/v2/models/$MODEL_ID/field-changes/plan \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ "editFields": [{ "id": "6d2e4f8a-0c91-4b11-8a77-5c3e0f9b1d22", "type": "number" }] }'

A plan returns a planHash, one op per field with the choices it allows, and counts of the values that convert, lose detail or fail. A model with many entries is counted in the background: the answer is 202 with a poll link instead.

Apply sends the same diff again with the planHash and one decision per op. A decision's choice is convert, clear, keep_both or delete. For convert, onFailure is clear (the default: values that fail are left empty and listed) or stop. If the model moved since the plan, the answer is 409 with code: "plan_stale": plan again.

Where field changes are not switched on, every route here answers 404 with code: "feature_disabled".

API keysCopy Anchor Link

These routes mint and manage your project's keys. Developers > Keys in the admin covers the same ground. See Keys and scopes for what each key can do.

Mint a scoped cap_ key by sending scopes:

curl -X POST https://api.capacms.com/v2/tenants/api-keys \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"name":"Website build","environment":"production","scopes":["instance:read","model:read"]}'

The answer is 201, with the secret in apiKey. It is the only time this key's secret is shown. A cap_ key cannot be read again: a lost one is rotated. You can only grant scopes you hold yourself.

Without scopes, the route mints a legacy key. Send permission, one of read, write, delete or agent, and it answers apiKey, environment and permission.

ProjectsCopy Anchor Link

A slug is 3 to 48 characters: lowercase letters and digits, with single hyphens between them. A slug another project holds is 409 {"error":"That URL is taken"}. The old slug stops working at once, with no redirect.

curl -X PATCH https://api.capacms.com/v2/projects/$PROJECT_ID \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"slug":"northwind-journal"}'