# Update Published Page Settings

```
PATCH 
/v1/:slug/boards/:token/page_layout
```

Changes the page's **own** design properties — its background colour and its typography. These are properties of the page itself, not of anything inside it: nothing in `slots` is read or written, and a page whose document has never been stored still reports `"slots": null` afterwards.

Send the ones you mean to change under `settings`, using the camelCase names (`backgroundColor`, `typography`) that `subboards_settings` entries already store. The legal values are published by `GET /v1/page_layout_elements` as `background_colors` and `typographies` — a value outside those sets is `422 invalid_page_setting`, and so is a property name outside the two.

**This is a partial patch**, unlike `PATCH .../page_layout/elements/{element_id}`. A property you do not name is left exactly as it was. A property you send as `null` is **cleared**, and the page then inherits a value again — which is a real state, not a deletion, and is how you put a page back the way it was.

**What a clear falls back to depends on which document you cleared.** On the page, both properties reach the template. Background colour has one extra step — the published link stores a colour of its own, above the template, and publishing always writes one — so clearing `backgroundColor` on the page clears that stored colour too, in the same transaction. Nothing else about the link is touched, and the response is unchanged by it.

Send `subboard_token` to change the settings of a nested board's **section** of this page instead of the page itself. Omit it, or send `null`, for the page. A section has no published link of its own, so clearing one of its settings never reaches a link — and a section inherits from the **page** before anything else, so a cleared section setting shows the page's value and reaches the template only when the page sets none either.

Requires the `write` scope, `modify` on the board, and the page-layout API write flag on the workspace (otherwise `403 page_layout_api_disabled`).

`modify` is checked on the board that **governs** the design, which is usually the board in the path but not always: one design document can be bound to more than one published page, and the oldest binding governs all of them — a settings change recolours every page it serves. A caller who may modify the board it addressed but not the governing one gets `403 board_not_authorized`. A read-only board gets `403 board_read_only`, and so does a read-only subboard whose section you address with `subboard_token`.

**Freshness.** This API is immediately current: a follow-up `GET .../page_layout` reflects this write straight away. The **public** page at `/s/<slug>` is only eventually current — the write purges the cached render, but edge points of presence can keep serving a recent copy for up to an hour. Do not tell a user to reload and expect to see the change.

**Concurrency.** You are not the only writer: a person can be editing the same page in the Publish editor while you write. Send the `version_token` from `GET .../page_layout` back as `expected_version_token` and this call becomes a compare-and-swap — if the document moved in between you get `409 stale_document` and **nothing is applied**. Omit it and the write simply applies.

**Did it actually do anything?** Re-sending the colour a page already has is a success that writes nothing, which is what makes retries safe. `converged: true` says so, and it is the only difference between that answer and a real write. It is **absent when false**, never `false`, and a write where one property moved and another did not is a real write and omits it.

**This write detaches the board from a workspace template.** If the board was following one, changing its page settings stops it following, exactly as editing an element does — otherwise the next template roll-out would silently revert your colour. A converged write does not detach, because it changed nothing.

## Request[​](#request "Direct link to request")

## Responses[​](#responses "Direct link to Responses")

* 200
* 403
* 404
* 409
* 422

the page settings were written

page layout API writes are not enabled for this workspace

the board has no published page layout yet

Conflict: the request was well formed and disagrees with the current state. Key on `extensions.code`, never on the status and never on `retryable` alone:

* `stale_document` — the stored document changed since the `version_token` you echoed as `expected_version_token`, so **nothing was applied**. Read the page again, re-decide, and re-send. `retryable: false`, because an identical re-send carries the same now-stale token.
* `lock_wait_timeout` — another writer held this page's row for too long. Re-sending the identical call is correct here. `retryable: true`.
* `page_layout_library_locked` — this workspace's published-links library is being set up by another request. Nothing was changed. `retryable: true`.

a value outside the published set, or a property that is not a page setting