Docs menu
Docs/Developer interfaces/REST API/Sites
View as Markdown

Sites

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

Method Operation Path
GET List sites /v0/sites
POST Create a site /v0/sites
GET Get a site /v0/sites/:siteId
POST 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

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

Response

{
  "sites": [{
  "id": "<site-id>",
  "name": "Docs",
  "subdomain": "docs-example",
  "access": "PUBLIC",
  "status": "ACTIVE",
  "bucketId": "<bucket-id>"
}],
  "pagination": { "hasMore": false, "nextOffset": null }
}
  • CLI: interfold sites list
  • MCP: list_sites

See Errors for the standard error envelope and 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

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

{
  "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.
  • CLI: interfold sites create --name "Docs" --access PUBLIC
  • MCP: create_site

See Errors for the standard error envelope and 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

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

Response

{
  "id": "<site-id>",
  "name": "Docs",
  "subdomain": "docs-example",
  "access": "PUBLIC",
  "status": "ACTIVE",
  "bucketId": "<bucket-id>"
}
  • CLI: interfold sites get <site-id>
  • MCP: get_site

See Errors for the standard error envelope and 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

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

{
  "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.
  • CLI: interfold sites update <site-id> --access PRIVATE
  • MCP: update_site

See Errors for the standard error envelope and Authentication for API key handling.

Shared behavior

All operations use the API authentication, error, and rate-limit contracts. List operations use standard pagination unless the operation says otherwise.

On this page