Previews
A preview is a draft on its own address. Read Drafts and slots for what a slot is and how approval works.
Make and list
| Call | What it does |
|---|---|
POST /v1/sites/{id}/previews |
builds a draft into a slot |
GET /v1/sites/{id}/previews |
the site's slots |
GET /v1/previews/{id} |
one preview, in full |
POST takes a slot, a summary for the owner, and a scope, which is
site or posts exactly as a publish is.
A preview reports expires_at. A draft address does not live for ever.
What it says about where it stands
| Field | Means |
|---|---|
branch |
the branch this slot owns, if it started one |
behind |
how far the slot is behind the live source |
posts_behind |
the same, for the posts |
slot_ahead |
how far the slot is ahead |
next_action |
what to do now, in plain language |
See what changed
GET /v1/previews/{id}/changes lists what this draft changes against the
live site.
When approval cannot fast-forward
The owner approves a draft in the browser. If the live site moved on since the draft was built, Clave refuses to move the branch, and you answer with one of two calls.
| Call | What it does |
|---|---|
POST /v1/previews/{id}/publish |
merges and builds a page nobody has seen |
POST /v1/previews/{id}/catch-up |
brings the site into the slot, so the owner looks again |
Prefer catch-up when the owner is there to look. The owner should approve bytes they saw.
Discard
DELETE /v1/previews/{id} frees the slot.
It removes the draft's address and does not touch git, so the branch
outlives it. A slot that holds work asks for a confirmation: send
?confirm=true.