Update a page (partial)

Create-style merge on an existing page (PUT, PATCH, and POST /pages/{id} share this route). Only sent top-level keys change. Item write shape is documented on PageUpsert.items.

Query parameters

content_locale — write translated content in that locale (must be a site locale, else 422; default = site default)
dry_run=1 — 200 {dry_run: true, valid: true} or the same 422s; nothing is saved or archived
replace=1 — each sent canvas array is the full canvas (unlisted ids deleted, positions reassigned from array order)

Optimistic concurrency

Send the ETag from GET /pages/{page_id} as If-Match to make the write conditional. It is compared inside the page write lock: a stale value → 412 precondition_failed with top-level current_etag. Without If-Match the write is unconditional. Another write holding the lock → 409 concurrent_modification.

File editables

FileRef / File sit under the item's source key — not as the item value:

{"Attachment":{"source":{"__type":"FileRef","source":"nimbu://<site>/uploads/<id>"}}}

Batch set differs: the FileRef object is the operation value.

Responses

Unknown editable → 422 editable_not_in_theme (invalid editable <Slug>). Unknown repeatable slug → 422 repeatable_not_in_theme.

Authorization

AuthorizationBearer <token>

Personal access token tied to a user account. Requires the X-Nimbu-Site header to scope requests.

In: header

X-Nimbu-Site<token>

Identifier of the site context when authenticating with a personal access token.

In: header

Path Parameters

page_id*string

Page identifier or fullpath

Query Parameters

replace?boolean

When true, each sent canvas array becomes the full canvas (unlisted ids deleted, positions reassigned).

dry_run?boolean

When true, validate only. 200 {dry_run: true, valid: true} or the same 422s. Nothing saved/archived.

content_locale?string

Locale to write translated content in. Must be one of the site locales (default = site default).

Header Parameters

If-Match?string

Optional ETag precondition: the quoted ETag from GET /pages/{page_id}. Checked inside the page write lock; stale → 412 with current_etag. Omit for an unconditional write. Only a single strong ETag is supported; W/"..." and multi-value If-Match are treated as stale.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

title?string

slug?string

homepage?boolean

published?boolean

template?string

channel?string

parent?string

filter?string

seo_title?string

seo_description?string

seo_keywords?string

locales?array<string>

fixed_locale?string

position?integer

security_mechanism?string

Value in"none" | "humans" | "customers"

security_password?string

security_access_groups?array<string>

caching_strategy?|

Value in"none" | "auto"

items?

Hash keyed by editable slug (case-sensitive).

Editable types

Simple (field, text, switch, select, reference): scalar or {content: ...}
Canvas: an array of repeatables, or {repeatables: [...]}
Repeatable: {id: <existing 24-hex>, slug: <block slug>, items: {...}, _destroy: true}
File: wrap FileRef / File under the item's source key — a bare FileRef as the item value is ignored:
```
{"Attachment":{"source":{"__type":"FileRef","source":"nimbu://<site>/uploads/<id>"}}}
```
Inline upload:
```
{"Attachment":{"source":{"__type":"File","filename":"doc.pdf","content_type":"application/pdf","attachment":"<base64>"}}}
```
nimbu:// forms: <site>/uploads/<id>, <site>/pages/<page_id>/<field>[/<embedded_id>], <site>/entries/<entry_id>/<field>[/<embedded_id>], <site>/products/<id>/images|attachments/<embedded_id>. nimbu://<site>/tmp/<id>/<filename> is rejected on pages (temporary uploads are only accepted on the Uploads resource). CDN https:// URLs are not accepted as FileRef (Invalid FileRef URI: expected nimbu:// format).

Batch set differs: the FileRef object is the operation value (value: {"__type":"FileRef","source":"nimbu://..."}).

Merge vs replace

Default merge:

known id updates in place
no id appends (after existing, array order)
_destroy: true (with id) deletes
unmentioned repeatables are kept

?replace=1: the array is the full canvas — ids not listed are deleted and positions are reassigned from array order.

Theme errors

Unknown editable → 422 editable_not_in_theme {message: "invalid editable <Slug>", data: {editables, canvas?, repeatable?}}
Unknown repeatable slug → 422 repeatable_not_in_theme {data: {canvas, slugs}}

[key: string]?any

Response Body

`application/json`

curl -X PATCH "https://example.com/pages/string" \  -H "Content-Type: application/json" \  -d '{}'

{
  "id": "66f1a2b3c4d5e6f7a8b9c0d0",
  "title": "Updated Home"
}

{
  "message": "string",
  "errors": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

{
  "message": "string",
  "code": "string",
  "current_etag": "string"
}

{
  "message": "string",
  "code": "editable_not_in_theme",
  "data": {
    "editables": [
      "string"
    ],
    "canvas": "string",
    "repeatable": "string",
    "slugs": [
      "string"
    ]
  }
}

Query parameters

Optimistic concurrency

File editables

Responses

Authorization

Path Parameters

Query Parameters

Header Parameters

Request Body

Editable types

Merge vs replace

Theme errors

Response Body

200application/json

409application/json

412application/json

422application/json

Conditional update

PATCH ?dry_run=1

Editable types

Merge vs replace

Theme errors

`application/json`

`application/json`

`application/json`

`application/json`