# Previews

A preview is a draft on its own address. Read
[Drafts and slots](/concepts/drafts) 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`.

---

## Where this page sits

This is one page of the Clave documentation.
Read it as a web page at https://docs.heyclave.party/api/previews.
Every page has a `.md` address, and https://docs.heyclave.party/llms.txt lists them all.

- Previous: [Deployments](https://docs.heyclave.party/api/deployments.md)
- Next: [Comments](https://docs.heyclave.party/api/comments.md)
- Index: [Overview](https://docs.heyclave.party/index.md)