# 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.

The list reports `open_comments`, which is how an agent learns that the
owner left a comment.

## Make one

```sh
curl -X POST https://api.heyclave.party/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](/concepts/source).

## Change one

`PATCH /v1/sites/{id}` changes the `title` and the `payment_return_path`.

A site's address never changes. To give a site a better address, attach a
[domain](/api/domains).

## 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}` | destroys the site, its source and its archive |

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

A delete is final. It removes the site, both repositories and every byte
Clave archived for it. The site's owner is the only account that can do
it; a collaborator cannot.

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

---

## Where this page sits

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

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