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

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

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