Schema

Deploy a schema authored as files

Replaces the project's schema with the one in the body (what `cairn schema deploy` sends). Fields are matched to the published schema by name, or by a `renamedFrom` hint for a rename, and existing documents are migrated before the new schema goes live. Requires a credential with settings access.

POST/projects/{projectSlug}/schema/deploy

Requires an active preview session — either the cairn_preview cookie set by createPreviewHandler, or a preview session token sent as Authorization: Bearer <token>.

Path parameters

projectSlug*stringThe project's slug

Request body

documentTypes*array
blockTypesarray
structurearrayNav structure; omit for one flat link per document type
dryRunbooleanReport changes and impact without deploying
allowDataLossbooleanDeploy even if stored values would be dropped or documents orphaned

Responses

200Deployed, unchanged, or (with `dryRun`) the report of what would change
202Accepted - documents are being migrated in the background; the new schema goes live when that finishes
400The schema is invalid
401Authentication required
403Origin not allowed, or not a member of this project
404Unknown project
409The change would lose data - retry with `allowDataLoss` after reviewing `impact`
423A previous deploy is still migrating documents

Request

curl -X POST "https://api.cairn.press/projects/my-project/schema/deploy" \
  -H "Authorization: Bearer $CAIRN_PREVIEW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"documentTypes":[{}]}'

Response · 200

{
  "status": "unchanged",
  "changes": {},
  "impact": {},
  "warnings": [
    "string"
  ]
}