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 and a summary for the owner. A draft builds the
slot's line of the site and of the posts. It does not use scope.
A draft does not expire. Its address lives as long as the site.
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 the site needs approval
If the owner turned on Publishing needs approval, a preview carries
review_url, and POST /v1/previews/{id}/publish answers
needs_approval (409). Send the owner the review_url. They publish the
draft there. See Drafts and slots.
When approval cannot fast-forward
When a draft is published, and 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 |
POST /v1/previews/{id}/address |
gives the draft a new address; the old one stops answering |
POST /v1/previews/{id}/reset-store |
empties the draft's store and runs its migrations and draft seeds again |
Prefer catch-up when the owner is there to look. The owner should approve a page they saw.
A new address
A draft's address is unlisted, not private: anyone with the link can open
it. When a link reached somebody it should not have, POST /v1/previews/{id}/address gives the draft a new address. The draft stays
as it was. The old address stops answering, and so do links to it in mail
and in payment returns.
Discard
DELETE /v1/previews/{id} takes the draft offline and removes the slot's
branch. The slot keeps its address and its store, and the next draft on it
starts from the site again. A slot that holds work asks for a
confirmation: send ?confirm=true.