Skip to content

Writing content from outside

Creates take `?siteId=` on the query string: the create schema is strict and rejects an in-body `siteId`, and layouts are written one page at a time.

The create and update schemas are strict. A key that is neither a writable base field nor a field the content type declares is a 400, not a key quietly dropped — and the first thing most integrations get wrong is putting siteId in the body. It belongs on the query string.

the site goes on the URL, never in the payloadbash
curl -X POST "$BASE/api/v1/content/article?siteId=docs" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{ "title": "Rate limits", "slug": "rate-limits", "status": "draft" }'
the same call with "siteId" moved into the body → 400json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [ { "path": "", "message": "Unrecognized key(s) in object: 'siteId'" } ]
  }
}

path is empty because the failure is on the object, not on a field. A success answers 201 with the row in the single-object envelope.

Selecting a site is not permission to write to it

The site is resolved as it is for a read — explicit ?siteId=, then the Host header, then the first configured site — and then checked against the caller's memberships, so naming a site you cannot reach is a 403 rather than a row in the wrong place. Send ?siteId= anyway: without it a request whose Host matches nothing lands on the first configured site.

The slug is derived once, and never again

Supply slug and it is stored as given, trimmed. Omit it and it is derived from the title by lowercasing, turning whitespace into hyphens, and deleting — not replacing — every remaining character outside [a-z0-9-]. path and depth are materialized in the same insert. Nothing re-derives them afterwards: a later title change moves nothing. See Slugs, paths, and moving a page.

The write routes

POST/api/v1/content/{type}?siteId={site}Bearer token

Create. Strict schema; 201 with the row.

201
{ "data": { "id": "…", "slug": "…", "path": "…", "status": "draft" } }
PUT/api/v1/content/{type}/{id}?siteId={site}Bearer token

Update. Despite the verb this is a partial update — every field is optional, exactly as on PATCH. What PUT adds is two different lock checks, both 423 LOCKED but not the same shape: the explicit content lock answers with no details at all, and is bypassed for siteAdmin and above; the time-based edit lock — someone else actively editing — answers only for a genuinely different user and carries details: { lockedBy, expiresAt }. Check details for presence before reading it.

200
{ "data": { "id": "…", "title": "…", "status": "draft" } }
PATCH/api/v1/content/{type}/{id}?siteId={site}Bearer token

The same partial update without the lock checks.

200
{ "data": { "id": "…" } }
DELETE/api/v1/content/{type}/{id}?siteId={site}Bearer token

Soft delete into the trash. The delete content action requires the siteAdmin role, so a key scoped only read, write, publish ceilings below it and 403s here.

200
{ "data": { "deleted": true } }
POST/api/v1/content/{type}/{id}/publish?siteId={site}Bearer token

Publish, with /unpublish as its counterpart. Both check the status ladder as well as the role gate, and both snapshot a version.

200
{ "data": { "id": "…", "status": "published" } }

Layouts are a separate write

A page's body is a layout document, and it is not written through the content routes' ordinary fields. PUT /content/{type}/{id}/layout replaces the whole document; PATCH /content/{type}/{id}/layout/regions/{region} merges one region into what is stored. Both validate the document and both refuse to introduce a module the caller's role may not place — a differential check, so an existing admin-only module survives a write by a lesser role but a new one does not. Validation also normalises: unknown keys are stripped, and both routes return the stored document, so persist what comes back rather than what you sent.

Two asymmetries to code around. Reading a layout requires authentication, unlike every other content read, because the stored document exposes drafts and modules that never reach a rendered page. And a layout validation failure returns VALIDATION_ERROR with no details key, where the content routes always send the [{ path, message }] array — see The response envelope, pagination and errors.

Status moves up a ladder

status is an ordinary key on the update schema, which makes every save a potential workflow transition — so every door checks the same ladder. An author may move a row from draft to pending and nowhere else; an editor may reach approved or published from draft or pending; siteAdmin and above may make any transition. Re-sending the status a row already has is a no-op and always allowed, which is what lets a client round-trip a whole row.

an author asking for "published" in a save payloadjson
{
  "error": {
    "code": "TRANSITION_DENIED",
    "message": "Role 'author' may not change content status from 'draft' to 'published'. That transition requires role 'editor' or higher.",
    "details": { "role": "author", "from": "draft", "to": "published", "requiredRole": "editor" }
  }
}