HTTP endpoints

Build integrations against /api/v1. The admin API is not versioned.

A token’s scope decides which permissions it carries: read → content:read, media:read, segments:read; full adds content:create, content:update, content:publish, content:delete, media:create, segments:manage. See permissions.

Example calls

curl 'https://cms.example.com/api/v1/content/article?locale=en&pageSize=10&sort=-publishedAt' \
-H 'Authorization: Bearer orthacms_…' \
-H 'X-Workspace-Id: 7d0c…' \
-H 'X-Reader-Tags: premium, eu'

curl -X POST https://cms.example.com/api/v1/content/article \
-H 'Authorization: Bearer orthacms_…' \
-H 'Content-Type: application/json' \
-d '{ "locale": "en", "values": { "title": "Hello world", "slug": "hello-world" } }'
# 201 → the draft entry; then POST /api/v1/content/article/:id/publish

# Sign in — stores the orthacms_session cookie
curl -c cookies.txt -X POST https://cms.example.com/api/auth/login \
-H 'Content-Type: application/json' \
-d '{ "email": "admin@example.com", "password": "…" }'
# { "ok": true }

# Who am I, and what may I do
curl -b cookies.txt https://cms.example.com/api/auth/me
# { "id": "…", "email": "admin@example.com", …, "permissions": ["workspaces:create", …] }

# A workspace-scoped admin read
curl -b cookies.txt 'https://cms.example.com/api/content/article?source=all' \
-H 'X-Workspace-Id: 7d0c…'

X-Reader-Tags names the reader for segments; send it from your backend, never a browser. Without it the reader is anonymous.

Common errors:

Public API

Content

• Reads serve published entries — for a Modified entry, its published version. ?status=draft|any needs a full token (403 otherwise).
• A type’s list includes published records from shared workspaces the workspace takes the type from.
• Public PATCH merges over stored values.

Media, access, GraphQL and MCP

MCP is off unless MCP_ENABLED=true. A multi-workspace token names the workspace with X-Workspace-Id or ?workspaceId= on the URL.

curl -X POST https://cms.example.com/api/v1/mcp \
  -H 'Authorization: Bearer orthacms_…' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
        "params": { "name": "content_list", "arguments": { "typeName": "article", "pageSize": 5 } } }'

Admin API

Authentication and account

Single sign-on

All public and rate-limited. See single sign-on.

Content, revisions and schema

The create, the update and the two version routes take askBeforeSiblingSync and allowInvalidSiblings (the create also skipReferrers): the way the admin asks before a write that changes other languages or records. See errors.

Saved views

See saved views. Sharing a view with the workspace additionally needs views:share, checked per write.

Export and import

See export and import.

Media

Users, tokens and activity

Workspaces

shared-sources is new in 0.7.0: the shared workspaces this one can take a shared grant from, each with the types it offers.

Alarms

See alarms.

Segments

See segments.

The admin itself sends audiences in the entry save’s extensions, so access commits with the save and lands in its revision.

Publication protection

See publication protection.

A blocked publish is 409 (protection.insufficient_approvals, protection.token_refused), never 403. { "bypass": true } on the publish body without protection:manage is 403 protection.bypass_refused.

Webhooks

Global, not workspace-scoped. See webhooks.

A refused URL is 422, not 400. A delivery id from another endpoint is 404.

Schema builder

Global, not workspace-scoped. See the schema builder.

Plan and apply answer 403 schema-builder.disabled in production, with SCHEMA_BUILDER off, or without the source tree — whatever the caller’s role. A stale draft or a second apply is 409 (schema-builder.stale, schema-builder.busy).

Localization, insights and copilot

API reference document

• Outside the /api prefix; both paths are configurable in the host’s docs options.
• On by default outside production; in production only with API_DOCS=true.
• MCP is not in the document — JSON-RPC over one route is not REST.