Skip to main content

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​

Responses​

the page settings were written