# The publish contract

This page is the flow a client follows when it already holds the built
files. An agent with a source tree uses `POST /v1/sites/{id}/publish`
instead, which builds and activates in one call.

## Four steps

1. **Send a manifest.** `POST /v1/sites/{id}/deployments` with a map of
   path to the file's full sha-256 and its size.
2. **Read `missing`.** The answer lists the hashes Clave does not have.
3. **Upload each one.** `PUT /v1/deployments/{id}/files/{hash}`.
4. **Activate.** `POST /v1/deployments/{id}/activate`.

```sh
curl -X POST https://api.heyclave.party/v1/sites/<site id>/deployments \
  -H "Authorization: Bearer $CLAVE_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"manifest":{"index.html":{"sha256":"<hash>","size":1234}}}'
```

## `missing` is what Clave lacks

It is not what the hosting provider lacks. The archive is the source of
truth, so creating a deployment makes no call to the provider at all.

That is why a second publish of a site that barely changed uploads almost
nothing.

## There is no staging area

Upload **is** archive. A file you send is kept the moment it arrives.

Activation opens a fresh upload session at the provider and satisfies it
from Clave's own archive. Nothing is uploaded twice.

## One live deployment

A site has at most one live deployment. Activating supersedes the last
one, and the last one stays restorable.

## The fields of a deployment

| Field | Means |
|---|---|
| `id` | the deployment |
| `status` | where it is |
| `missing` | hashes still to upload |
| `next_action` | what to do now, in plain language |
| `url` | where it is live, once it is |
| `scope` | `site` or `posts` |
| `source_commit` | the source commit it was built from |
| `content_commit` | the posts commit it was built from |
| `error` | why it failed |

Read [Deployments](/api/deployments) for the calls that read them back.

---

## Where this page sits

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

- Previous: [Pagination](https://docs.heyclave.party/api/pagination.md)
- Next: [Account and platform](https://docs.heyclave.party/api/account.md)
- Index: [Overview](https://docs.heyclave.party/index.md)