# Sites

Create hosted identities, attach buckets, and control public or private access.

| Method | Operation | Path |
| --- | --- | --- |
| **`GET`** | [List sites](#list-sites) | `/v0/sites` |
| **`POST`** | [Create a site](#create-a-site) | `/v0/sites` |
| **`GET`** | [Get a site](#get-a-site) | `/v0/sites/:siteId` |
| **`POST`** | [Update a site](#update-a-site) | `/v0/sites/:siteId` |

## List sites

List sites in an account, newest updates first.

**`GET`** `/v0/sites`

- **API key permission:** Read-only or Read/write

### Parameters

- `accountId` — required account UUID.
- `bucketId` — optional exact bucket UUID.
- `subdomain` — optional exact subdomain.
- `status` — optional `ACTIVE` or `ARCHIVED`.
- `limit` and `offset` — standard pagination fields.

### Request

~~~sh
curl \
  "https://api.interfold.dev/v0/sites" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~json
{
  "sites": [{
  "id": "<site-id>",
  "name": "Docs",
  "subdomain": "docs-example",
  "access": "PUBLIC",
  "status": "ACTIVE",
  "bucketId": "<bucket-id>"
}],
  "pagination": { "hasMore": false, "nextOffset": null }
}
~~~

### Related interfaces

- **CLI:** `interfold sites list`
- **MCP:** `list_sites`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Create a site

Create a site and attach new or existing storage.

**`POST`** `/v0/sites`

- **API key permission:** Read/write

### Parameters

- `accountId` — required account UUID.
- `name` — required string, 1–100 characters after trimming.
- `subdomain` — optional lowercase subdomain, 3–63 characters.
- `access` — optional `PUBLIC` or `PRIVATE`.
- `bucketId` — optional existing bucket UUID. Omit it to create storage automatically.

### Request

~~~sh
curl -X POST \
  "https://api.interfold.dev/v0/sites" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{  "accountId": "<account-id>",  "name": "Docs",  "subdomain": "docs-example",  "access": "PUBLIC"}'
~~~

### Response

~~~json
{
  "id": "<site-id>",
  "name": "Docs",
  "subdomain": "docs-example",
  "access": "PUBLIC",
  "status": "ACTIVE",
  "bucketId": "<bucket-id>"
}
~~~

### Behavior and errors

- A requested subdomain can return `409 Conflict` when it is reserved or already taken.
- Site limits return `422 Unprocessable Entity`.

### Related interfaces

- **CLI:** `interfold sites create --name "Docs" --access PUBLIC`
- **MCP:** `create_site`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Get a site

Read site metadata, its attached bucket, and runtime reconciliation status.

**`GET`** `/v0/sites/:siteId`

- **API key permission:** Read-only or Read/write

### Parameters

- `siteId` — site UUID.

### Request

~~~sh
curl \
  "https://api.interfold.dev/v0/sites/<site-id>" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"
~~~

### Response

~~~json
{
  "id": "<site-id>",
  "name": "Docs",
  "subdomain": "docs-example",
  "access": "PUBLIC",
  "status": "ACTIVE",
  "bucketId": "<bucket-id>"
}
~~~

### Related interfaces

- **CLI:** `interfold sites get <site-id>`
- **MCP:** `get_site`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

---

## Update a site

Change site metadata or retry runtime reconciliation.

**`POST`** `/v0/sites/:siteId`

- **API key permission:** Read/write

### Parameters

- `siteId` — site UUID.
- `name` — optional string, 1–100 characters.
- `access` — optional `PUBLIC` or `PRIVATE`.
- `status` — optional `ACTIVE` or `ARCHIVED`.
- `reconcile` — optional literal `true` to retry runtime reconciliation.

### Request

~~~sh
curl -X POST \
  "https://api.interfold.dev/v0/sites/<site-id>" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{  "access": "PRIVATE"}'
~~~

### Response

~~~json
{
  "id": "<site-id>",
  "name": "Docs",
  "subdomain": "docs-example",
  "access": "PUBLIC",
  "status": "ACTIVE",
  "bucketId": "<bucket-id>"
}
~~~

### Behavior and errors

- At least one update field is required.
- An archived site must be activated before its runtime sources can be reconciled.

### Related interfaces

- **CLI:** `interfold sites update <site-id> --access PRIVATE`
- **MCP:** `update_site`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

## Shared behavior

All operations use the [API authentication](/api-reference/authentication),
[error](/api-reference/errors), and [rate-limit](/api-reference/rate-limits)
contracts. List operations use [standard pagination](/api-reference/pagination)
unless the operation says otherwise.