HTTP API

The HTTP API gives you full CRUD access to documents, assets, and schemas. All document and asset endpoints require authentication via session or API key.

Live API reference

Your running studio describes its own API. Two endpoints, both generated from the instance itself:

This page stays the prose explanation of how the API behaves. The generated reference is the authoritative list of what exists and what it takes, because it is built at request time from the same sources the server runs on:

• Endpoint shapes come from the zod contracts in packages/cms-core/src/lib/api/schemas/ — the very objects each handler validates with, so a parameter cannot drift from its documentation.
• Document shapes come from your own schemaTypes. A static file could only ever describe draftData as an untyped object; the generated spec emits a real PostData / PageData component per collection, with the same required fields the validator enforces.

That second half is the reason it's generated per instance rather than checked in — your content model is yours, so no shipped file could describe it.

curl -H "x-api-key: $APHEX_API_KEY" \
  https://your-app.com/api/openapi.json -o openapi.json

npx openapi-typescript openapi.json -o src/lib/aphex-api.d.ts

Both endpoints require authentication. /api/openapi.json enumerates your entire content model, which is not something to hand to anonymous callers even though it carries no content; /api/docs is a static shell that fetches that spec from the browser with your session, so signed out it would only render a failure anyway. Signed out, it redirects you to the login page rather than answering 401 — the response is HTML for a person.

The reference UI loads Scalar from a public CDN — the one thing it does that the JSON endpoint doesn't. On an instance that shouldn't pull third-party scripts, unmount it, after which it answers 404:

export default defineConfig({
	openapi: { docsUi: false }
});

That script is pinned to an exact version with a Subresource Integrity hash, because the page is same-origin with your admin — whatever runs there runs with the signed-in user's cookies. If the CDN ever serves different bytes, the browser refuses to execute them and the page renders empty rather than running something unreviewed.

/api/openapi.json is unaffected either way.

Base URL

All endpoints are relative to your app's origin:

https://your-app.com/api/...

Reserved URLs

Three different layers handle requests under /api/*, and they're picked in this order:

1. SvelteKit handle hook       → Better Auth (/api/auth/*)
2. SvelteKit filesystem router → specific +server.ts files
3. Catch-all (/api/[...slug])  → forwards into Hono → CMS routes

SvelteKit's filesystem router prefers more-specific paths over rest parameters. Hono only sees what falls through the catch-all — it does not take precedence over a sibling +server.ts. That means if you create apps/studio/src/routes/api/documents/+server.ts, your file silently shadows the CMS's /api/documents handler and the CMS code never runs.

To wrap or replace a CMS route safely, use the api(app) config hook — it registers your handler inside Hono itself, where you can call await next() to chain to the built-in handler.

The full list of URLs the CMS owns. (/api/docs renders this same list from the live route table, so if the two ever disagree, believe the generated one.)

Documents

Assets

Organizations

Roles

Schemas

User account

Jobs and events

Read-only observability over the event, queue and job spine, plus the two operator actions that make a dead letter recoverable. ?scope=all widens a read from the active organization to the whole instance and is super-admin only.

Plugin settings

Session only — these reject API keys. Secret values are returned redacted and encrypted at rest.

Meta

Outside Hono

Picking a safe path for custom endpoints

When you mount your own +server.ts under /api/*, avoid these prefixes: /api/auth, /api/documents, /api/assets, /api/organizations, /api/roles, /api/schemas, /api/user, /api/graphql, /api/instance-settings. The convention some teams adopt to be future-proof:

• Namespace custom routes under a stable prefix, e.g. /api/app/* or /api/v1/*.
• For one-off webhooks: /api/webhooks/<provider> (Stripe, Slack, GitHub).
• For internal tooling: /api/admin/* or /api/internal/*.

If you ever need to claim a URL the CMS already owns — to wrap, replace, or extend a built-in handler — use the api(app) config hook. That's the only safe path to do so without forking cms-core.

Authentication

Include an API key in the x-api-key header:

curl -H "x-api-key: your_key_here" \
  https://your-app.com/api/documents?type=post

If no x-api-key header is present, the API falls back to session authentication (cookies). When both are available, the API key takes precedence.

Each API key is scoped to the organization that was active when the key was created. All requests made with that key only see and modify data within that organization. See API Keys for details on organization scoping and parent–child hierarchy access.

Write protection

Mutating requests (POST, PUT, PATCH, DELETE) require write permission. API keys with only read permission receive a 403 response on mutations.

The one exception is POST /api/documents/query, which is treated as a read operation (it uses POST only because the filter payload can be complex).

Response format

Successful responses share a consistent envelope:

{
  "success": true,
  "data": { ... },
  "pagination": { ... }
}

Errors come in two shapes depending on which layer rejected the request:

// Validation / business errors (most 400s, 404s)
{
  "success": false,
  "error": "Bad Request",
  "message": "Detailed error message",
  "issues": [ ... ]   // present when zod validation failed
}

// Auth / permission middleware (401, 403)
{
	"error": "Unauthorized"
}

The middleware path is intentionally minimal — it short-circuits before the route handler, so it doesn't carry success or message. Treat both shapes as errors when the HTTP status is ≥ 400.

Documents

List documents

GET /api/documents?type={type}

curl -H "x-api-key: your_key" \
  "https://your-app.com/api/documents?type=post&perspective=published&pageSize=10&sort=-publishedAt"

Response:

{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "total": 42,
    "page": 1,
    "pageSize": 10,
    "totalPages": 5,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Get document by ID

GET /api/documents/{id}

curl -H "x-api-key: your_key" \
  "https://your-app.com/api/documents/doc_123?perspective=published&depth=1"

Create document

POST /api/documents

{
	"type": "post",
	"data": {
		"title": "My New Post",
		"slug": "my-new-post",
		"body": "Hello world."
	},
	"publish": false
}

Returns 201 with the created document and validation results:

{
  "success": true,
  "data": { ... },
  "validation": { "isValid": true, "errors": [] }
}

Set "publish": true to publish immediately. This validates before publishing and returns 400 if validation fails.

Update document

PUT /api/documents/{id}

{
	"data": {
		"title": "Updated Title"
	},
	"publish": false,
	"expectedRevision": 7
}

expectedRevision is optional — see Concurrency below.

Delete document

DELETE /api/documents/{id}

Publish document

POST /api/documents/{id}/publish

Validates the draft and copies it to published data. Returns 400 if validation fails.

Unpublish document

DELETE /api/documents/{id}/publish

Reverts the document to draft-only state.

Concurrency

Every document carries a monotonic revision, returned as _meta.revision and incremented on every draft write. Echo it back as expectedRevision on your next write and the request only lands if nobody changed the document in between:

{
	"data": { "title": "Updated Title" },
	"expectedRevision": 7
}

If the stored revision has moved on, the request is rejected with 409 rather than overwriting:

{
	"success": false,
	"error": "Conflict",
	"message": "Document was modified by another write (expected revision 7, current 9)",
	"currentRevision": 9
}

Re-read the document and decide what to do — merge, discard, or ask the user. Accepted by update, publish, unpublish, and version restore.

Versions

Every draft save and publish writes an entry to the document's version history. See Version History for the full guide.

List versions

GET /api/documents/{id}/versions?limit=25&offset=0

Returns versions newest-first with the author resolved to a friendly createdByName.

Get a specific version

GET /api/documents/{id}/versions/{versionNumber}

Restore a version

POST /api/documents/{id}/versions/{versionNumber}/restore

Replaces the document's draft with the snapshot data and writes a new draft-event version recording the restore. Published data is untouched until the editor publishes again.

Accepts an optional expectedRevision in the body — see Concurrency.

Singletons

Singleton schemas are reachable through the same endpoints, with two differences:

• The list endpoint (GET /api/documents?type=siteNavigation) always returns a one-element array — singletons ignore filters, pagination, and status parameters because there is at most one row.
• DELETE /api/documents/{id} returns 400 when called against the canonical singleton row.

Singletons are lazy-created on first read, so consumers never have to handle a 404.

Advanced querying

For complex filters that don't fit in query parameters, use the query endpoint:

POST /api/documents/query

This is a read operation — API keys with read permission can use it.

{
	"type": "post",
	"where": {
		"status": { "equals": "published" },
		"title": { "contains": "tutorial" }
	},
	"limit": 20,
	"page": 1,
	"sort": ["-publishedAt", "title"],
	"depth": 1,
	"perspective": "published",
	"includeChildOrganizations": true
}

The where clause

where is a map of field name to { operator: value }. Multiple fields are ANDed together; and and or take arrays of nested where objects; dot-notation reaches into nested fields.

{
	"type": "post",
	"where": {
		"title": { "contains": "incident" },
		"or": [{ "slug": { "starts_with": "2026-" } }, { "featured": { "equals": true } }]
	},
	"sort": "-publishedAt",
	"limit": 20
}

The same operators back the Local API — see filtering. The canonical list lives in packages/cms-core/src/lib/types/filters.ts.

Assets

List assets

GET /api/assets

Response:

{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "total": 85,
    "page": 1,
    "pageSize": 20,
    "totalPages": 5,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Upload asset

POST /api/assets
Content-Type: multipart/form-data

curl -H "x-api-key: your_key" \
  -F "[email protected]" \
  -F "title=Hero Image" \
  -F "alt=A sunset over the ocean" \
  https://your-app.com/api/assets

Get asset

GET /api/assets/{id}

Update asset metadata

PATCH /api/assets/{id}

{
	"title": "Updated Title",
	"alt": "New alt text"
}

Delete asset

DELETE /api/assets/{id}

Returns 409 if the asset is still referenced by documents.

Bulk delete assets

DELETE /api/assets/bulk

{
	"ids": ["asset_id_1", "asset_id_2", "asset_id_3"]
}

Response:

{
	"success": true,
	"data": {
		"deleted": 2,
		"failed": 0
	}
}

Returns 409 if any assets are still referenced, with the list of blocked IDs:

{
	"success": false,
	"error": "Cannot delete 1 asset because it is still referenced by documents",
	"referencedIds": ["asset_id_2"]
}

Find asset references

GET /api/assets/{id}/references

Returns which documents reference a given asset:

{
  "success": true,
  "data": {
    "references": [ ... ],
    "total": 3
  }
}

Batch reference counts

POST /api/assets/references/counts

Get reference counts for multiple assets in one request. Useful for checking which assets are safe to delete.

{
	"ids": ["asset_id_1", "asset_id_2", "asset_id_3"]
}

Response:

{
	"success": true,
	"data": {
		"asset_id_1": 2,
		"asset_id_2": 0,
		"asset_id_3": 1
	}
}

Schemas

List all schemas

GET /api/schemas

Get schema by type

GET /api/schemas/{type}

Roles

Roles let an organization map names (owner, admin, custom roles like Publisher) to sets of capabilities. All role endpoints require a session — API keys cannot manage roles.

List roles

GET /api/roles

Returns every role defined for the active organization, including the four built-ins.

{
	"success": true,
	"data": [
		{
			"id": "role_abc",
			"organizationId": "org_123",
			"name": "owner",
			"description": "Full access including organization deletion.",
			"capabilities": ["document.read", "document.create", "…"],
			"isBuiltIn": true,
			"createdAt": "2025-01-10T00:00:00Z",
			"updatedAt": "2025-01-10T00:00:00Z"
		}
	]
}

Create a custom role

POST /api/roles

Requires the role.manage capability. Built-in names (owner, admin, editor, viewer) are reserved.

{
	"name": "Publisher",
	"description": "Can edit and publish but not delete.",
	"capabilities": [
		"document.read",
		"document.create",
		"document.update",
		"document.publish",
		"document.unpublish",
		"asset.read",
		"asset.upload"
	]
}

Write capabilities auto-include their matching read cap, so you don't need to list document.read alongside document.create manually (it's inserted on intake).

Update a role

PATCH /api/roles/{name}

Requires role.manage. Both built-in and custom roles can be edited — at least one of description or capabilities must be provided.

{
	"capabilities": ["document.read", "asset.read", "member.invite"]
}

Delete a custom role

DELETE /api/roles/{name}

Requires role.manage. Returns 403 for built-in names and 409 if the role is still assigned to any member or pending invitation.

Status codes