The delivery API

One public API, two protocols, same tokens and same rules:

GET  /api/v1/content/:type    REST
POST /api/v1/graphql          GraphQL

GraphQL is an adapter over the REST internals, not a second API. The two always agree.

First request

curl 'https://cms.example.com/api/v1/content/article?pageSize=2&fields=title,slug' \
-H 'Authorization: Bearer orthacms_…'

const response = await fetch(
  'https://cms.example.com/api/v1/content/article?pageSize=2&fields=title,slug',
  { headers: { Authorization: 'Bearer ' + process.env.ORTHACMS_TOKEN } }
);
if (!response.ok) throw new Error('Ortha answered ' + response.status);
const { items, total } = await response.json();

# POST /api/v1/graphql
query {
  articles(pageSize: 2) {
      total
      items {
          id
          title
          slug
      }
  }
}

{
    "items": [
        {
            "id": "9c4b1e77-…",
            "createdAt": "2026-02-11T09:14:03.221Z",
            "updatedAt": "2026-03-02T16:40:55.010Z",
            "values": { "title": "Hello, Postgres", "slug": "hello-postgres" },
            "status": "published",
            "publishedAt": "2026-02-12T08:00:00.000Z",
            "locale": "en",
            "localeGroupId": "b2d1…"
        }
    ],
    "total": 128,
    "page": 1,
    "pageSize": 2
}

• Envelope — id, createdAt, updatedAt; status and publishedAt on publishable types; locale and localeGroupId on localized types. Always returned, not selectable.
• values — the type’s own fields. Relation and media fields are not in it; expand them.

Request headers

The headers the REST and GraphQL endpoints read. There is no other request header to know about.

There is no locale header. Pick the language with ?locale=de on REST, or the locale: argument in GraphQL. See localized reads.

All of them together:

curl 'https://cms.example.com/api/v1/content/article?locale=de' \
-H 'Authorization: Bearer orthacms_…' \
-H 'X-Workspace-Id: 3f7a0c2e-5b1d-4e8a-9f3c-7d2e1a6b4c90' \
-H 'X-Reader-Tags: premium, eu'

// Server-side only — this code holds the token.
const response = await fetch(
  'https://cms.example.com/api/v1/content/article?locale=de',
  {
      headers: {
          Authorization: 'Bearer ' + process.env.ORTHACMS_TOKEN,
          'X-Workspace-Id': process.env.ORTHACMS_WORKSPACE_ID,
          'X-Reader-Tags': ['premium', 'eu'].join(',')
      }
  }
);

// Same headers on the GraphQL endpoint.
const response = await fetch('https://cms.example.com/api/v1/graphql', {
  method: 'POST',
  headers: {
      Authorization: 'Bearer ' + process.env.ORTHACMS_TOKEN,
      'X-Workspace-Id': process.env.ORTHACMS_WORKSPACE_ID,
      'X-Reader-Tags': 'premium, eu',
      'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      query: 'query($locale: String) { articles(locale: $locale) { total items { id title } } }',
      variables: { locale: 'de' }
  })
});

X-Reader-Tags

The default reader resolver since 0.7.0. It applies to REST, GraphQL and MCP reads alike, relations included.

• Each tag is matched against the tags of your segments. A reader carrying any one tag of a segment is in it.
• No header, or no segment exists yet: the anonymous reader. Unrestricted entries serve; restricted ones are a 404 (or missing from lists).
• Rename it with SEGMENTS_READER_TAGS_HEADER:

# .env
SEGMENTS_READER_TAGS_HEADER=x-plan-tags

A different source (a JWT claim, a billing lookup) is a resolver of your own in apps/server/config/segments.ts:

// apps/server/config/segments.ts
import type { SegmentsPluginConfig } from '@orthacms/segments-server';

export function segmentsConfig(): SegmentsPluginConfig {
    return {
        resolver: {
            // Receives the Express request. Return [] for the anonymous reader.
            resolve: async (request) => readTagsFrom(request)
        }
    };
}

What a read returns

• Published entries only, by default. A read token can never see drafts.
• A modified entry serves its published version (since 0.7.0). Editing a live entry does not take it off the API: reads keep returning the last published values and links, with status: "published", until the edit is published. Filters, search and sort match that version, never the unpublished edit.
• Only granted types. A type the workspace was not granted is a 404, is not listed, and is absent from the GraphQL schema.
• Shared workspaces (0.7.0). A workspace holding a shared grant also reads the published entries of the source workspace. They appear in lists like its own. A type reachable only through a shared grant is read-only: writing it is a 403.
• Shallow. Relations and media come back only when you expand them.

Endpoints

• Every :id route has a group/:groupId twin that takes ?locale=.
• The two access routes exist only when the segments plugin is registered.

Not the admin API

Routes under /api/ without v1 (/api/content, /api/users, …) are the admin app’s own API. Session cookie, per-user RBAC, unversioned. A bearer token does not reach them. Build against /api/v1.

The generated reference

A running server serves its OpenAPI document. On by default outside production; API_DOCS=true turns it on in a deployed instance.

http://localhost:3000/reference               # Scalar UI
http://localhost:3000/reference/json          # raw OpenAPI
http://localhost:3000/api/v1/graphql/playground   # GraphiQL, same switch

It is exhaustive and generated from the code — the place to check an exact parameter or response shape.

Hearing about changes

The API is pull. The webhooks plugin pushes: a signed POST on every entry create, update, publish, unpublish, delete, restore and purge. The body names the record; you read it back through this API. See reacting to changes.