# Writing content from outside

URL: https://kywi-docs-production.up.railway.app/integrating/writing-content-from-outside
Type: docPage

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.

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 site goes on the URL, never in the payload

## the same call with "siteId" moved into the body → 400

`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](/authoring/slugs-paths-and-moving-a-page/).

## The write routes

Create. Strict schema; `201` with the row.

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.

The same partial update without the lock checks.

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.

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

## 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](/integrating/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 payload

## A field your role cannot write refuses the whole request

When a content type puts an `access.write` predicate on a field, sending a *new* value for it as a role that fails the predicate returns `403 FORBIDDEN_FIELD` with `details: { fields: [...] }` and nothing is saved — not a partial write. The one thing forgiven is re-sending a value identical to the stored one, so a client that round-trips a whole row is not punished for fields it never touched.
