Preview, publish and restore

Three different milestones

1. Saved draft: content or design changes have been persisted. preview_site creates a private, read-only link to the exact saved revision. Open it without account login; it expires in 10 minutes and on draft changes or connection revocation.
2. Publication accepted: an immutable release has been created and queued for delivery.
3. Live and verified: get_delivery_status confirms the exact requested publication is active.

Do not describe a draft or an accepted publication as live.

Publish

Publishing requires the connection's publish scope and a current publisher/owner role. It must be requested by the user.

{
  "revision": 5,
  "idempotencyKey": "publish-alumni-001",
  "includeDrafts": false
}

Send to publish_changes using the current revision. With includeDrafts: false, only already-approved entries are included. With includeDrafts: true, all current draft entries are approved and included; confirm that this matches the user's intent. Archived entries are excluded.

Read the accepted ID from response.publication.id (not a top-level publicationId). Persist the response before further processing. Retry a lost response with the same key and original revision. If a native imported archive requires verification, publication returns the existing archive-verification error; complete that site's normal publisher workflow rather than bypassing verification.

Verify delivery

Call get_delivery_status with {"publicationId":"ID_FROM_PUBLISH"}. A response with ready: true means that exact release is live. If a previous release is still active, ready is false. Wait a few seconds between checks and use bounded backoff. Leave the user with an accurate status if delivery is still preparing.

Publication readiness does not prove that every physical display has downloaded the new release or is offline-ready.

Restore

Call list_publications, identify the intended prior release, and read the current revision. restore_release takes revision, publicationId and a new idempotencyKey.

Restoring replaces the current saved draft with the selected snapshot and creates a new publication. It overwrites unpublished edits. Use only when the user requests this outcome, then verify delivery of the new publication ID returned by the restore—not the old source ID.