Sites

List and read

Call	What it does
`GET /v1/sites`	every site the account can act on
`GET /v1/sites/{id}`	one site, in full

The single-site read adds two things a list leaves out: a traffic summary, and the state of the source against what is live.

unpublished_edits is absent when Clave could not count it. It is never zero in that case. Zero is the reassuring answer, so it is the one that must not be guessed.

Make one

curl -X POST https://api.heyclave.com/v1/sites \
  -H "Authorization: Bearer $CLAVE_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-shop","title":"My Shop","template":"starter"}'

POST /v1/sites takes:

Field	Means
`name`	the vanity part of the address. Optional.
`title`	what the owner calls the site. With no `name` it also supplies the address.
`template`	`starter` seeds a source tree that builds. Absent leaves the repository empty.

An empty repository is the default on purpose. The skill builds the tree on the machine and pushes its own history, and a push into a repository that already has a commit is refused.

The answer carries git_url and posts_git_url, which are the two repositories. Read Site source.

Change one

PATCH /v1/sites/{id} changes the title, which is what the owner calls the site in Clave.

The site's own settings are in its clave.site.json: the payment_return_path, the badge and code_refunds. Read Site settings.

A site's address never changes. To give a site a better address, attach a domain.

Archive, unarchive, delete

Call	What it does
`POST /v1/sites/{id}/archive`	takes the site off its address and keeps everything
`POST /v1/sites/{id}/unarchive`	puts it back
`DELETE /v1/sites/{id}`	removes the site; Clave keeps it 30 days, then destroys it

Archiving is how an owner starts something new without destroying what they had, so archived sites are capped apart from running ones.

A delete takes the site offline and out of every list at once. Clave keeps it for 30 days, and can restore it in that time if the owner asks Clave. After 30 days Clave removes the site, both repositories and every byte it archived for it, and nobody can get it back. A restored site comes back archived, without its domain. The site's owner is the only account that can delete; a collaborator cannot.

Archive first if there is any doubt. An archived site keeps everything and goes back on its address with one call.

What it has spent

GET /v1/sites/{id}/usage gives each count the site spends today, beside its limit. See Limits.