Design API

The Design API lets API clients read, validate, draft, publish, and restore
Sutra-rendered page designs for a space's Tiptap view.

Endpoints

GET /design/capabilities returns the renderer capability manifest. It
includes a website section documenting website-mode header/footer
(share-block) and navbar style shapes, allowed values, and the link object —
see the Website Mode section of the overview for how to author them.
Content layout attrs include flexLayout, flexGap, flexItemSizing
(equal or fit), and flexRowAlign (left, center, right) for
row-style layouts such as side-by-side badge pills.
GET /spaces/{space_id}/design returns current nodes, digest, circle
summaries, interactive-block summaries, and the published URL.
POST /spaces/{space_id}/design/validate validates proposed nodes and
returns diagnostics (errors, warnings, repairs). Warnings are advisory — for
example, setting min-height in a box/container/grid styles object (the
renderer clears it; set the node's minHeight attr instead, which accepts
vh/calc for full-viewport sections).
POST /spaces/{space_id}/design_drafts creates or updates the caller's
open draft for a client_draft_key.
GET /spaces/{space_id}/design_drafts/{draft_id} returns the draft content
for authorized preview clients.
PATCH /spaces/{space_id}/design_drafts/{draft_id} updates a draft.
POST /spaces/{space_id}/design_drafts/{draft_id}/publish publishes a
draft if its base_digest is still current.
POST /spaces/{space_id}/design_drafts/{draft_id}/restore restores the
pre-publish backup created by a draft publish.
POST /spaces/{space_id}/design_drafts/{draft_id}/preview_link (or the bare
POST /design_drafts/{draft_id}/preview_link) mints a short-lived, signed,
read-only preview link for the draft. Requires design:read.
POST /design/assets/import fetches, validates, and re-hosts an external
image URL for use in design JSON.

Use base_digest from GET /spaces/{space_id}/design when creating or
updating drafts. If live content changes before publish, the API returns
409 conflict with the current digest so the client can re-read and rebase.

Publishing rejects destructive omissions of circle nodes or response-bearing
interactive nodes unless the caller includes the confirmation values returned
in the conflict response.

Draft create/update responses include a preview_url under the space's
published URL, ending in /preview/{draft_id}. That bare URL uses the
logged-in web session and only returns draft content to users who can already
edit the space.

To share a preview with someone who is not logged in, call
POST /design_drafts/{draft_id}/preview_link (or the space-scoped
POST /spaces/{space_id}/design_drafts/{draft_id}/preview_link). It returns a
preview_url carrying a short-lived (~15 minute), signed pt token, plus an
expires_at timestamp. The token grants read-only preview of that one draft
and renders for an unauthenticated browser — no Sutra login is required and
no Admin API token is exposed in the browser. Requires the design:read scope.

Asset import only accepts public http/https image URLs, blocks private
network targets, enforces byte and image dimension caps, sanitizes SVG, and
stores the result on Sutra-controlled S3/CDN infrastructure.