# Sites

Static sites and single-page apps at their own address: versions, going live, rolling back, and the files in a version. 6 routes, from the API’s own OpenAPI document.

URL: https://docs.qaldy.com/reference/api/sites/

6 routes. Every path starts at `https://cloud-api.qaldy.com`. Sign-in, tokens, errors and limits are on the [overview](https://docs.qaldy.com/reference/api/).

## Routes

| Method | Path | What it does |
|---|---|---|
| [[GET]] | [`/​v1/​sites/​{id}`](#get-v1-sites-id) | One site: versions, traffic and storage |
| [[DELETE]] | [`/​v1/​sites/​{id}`](#delete-v1-sites-id) | Delete a site, all its versions and the files only it used (owner; type its name) |
| [[POST]] | [`/​v1/​sites/​{id}/​activate`](#post-v1-sites-id-activate) | Make a version live: the newest, or an older one to roll back |
| [[DELETE]] | [`/​v1/​sites/​{id}/​versions/​{versionId}`](#delete-v1-sites-id-versions-versionid) | Delete a version that is not live, and the files only it used |
| [[GET]] | [`/​v1/​sites/​{id}/​versions/​{versionId}/​files`](#get-v1-sites-id-versions-versionid-files) | The files of one version: path, size and type |
| [[GET]] | [`/​v1/​workspaces/​{ws}/​sites`](#get-v1-workspaces-ws-sites) | Sites you can open: status, live version and page views for 14 days |

## Reference

### [[GET]] `/v1/sites/{id}`

One site: versions, traffic and storage.

- **Authentication:** the console’s session cookie.
- **Token:** a personal access token or an MCP sign-in with the `read` scope.
- **Who:** `can_view`. Tokens: `read`

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `id` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes |  |
| `workspaceId` | string | yes |  |
| `name` | string | yes |  |
| `slug` | string | yes |  |
| `url` | string or null | yes |  |
| `status` | "live" · "paused" · "empty" | yes |  |
| `sharing` | "private" · "shared" · "workspace" · "public" | yes |  |
| `current` | object or null | yes |  |
| `current.id` | string | yes |  |
| `current.number` | integer | yes | at least 1 |
| `current.createdAt` | string (date-time) | yes |  |
| `current.createdBy` | object or null | yes |  |
| `current.bundleHash` | string | yes |  |
| `current.fileCount` | integer | yes | at least 0 |
| `current.totalBytes` | integer | yes | at least 0 |
| `current.spa` | boolean | yes |  |
| `current.hasIndex` | boolean | yes |  |
| `current.note` | string or null | yes |  |
| `current.source` | "console" · "api" | yes |  |
| `current.current` | boolean | yes |  |
| `versionCount` | integer | yes | at least 0 |
| `createdAt` | string (date-time) | yes |  |
| `updatedAt` | string (date-time) | yes |  |
| `spark` | integer[] | yes |  |
| `pages14d` | integer | yes | at least 0 |
| `canEdit` | boolean | yes |  |
| `description` | string | yes |  |
| `canDelete` | boolean | yes |  |
| `versions` | object[] | yes |  |
| `versions[].id` | string | yes |  |

…and 13 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[DELETE]] `/v1/sites/{id}`

Delete a site, all its versions and the files only it used (owner; type its name).

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** owner (`owner` relation); signed-in person only

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `id` | path | string | yes | 1 to 128 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `confirm` | string | yes | 1 to 200 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `ok` | true | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[POST]] `/v1/sites/{id}/activate`

Make a version live: the newest, or an older one to roll back.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** `can_edit`; signed-in person only

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `id` | path | string | yes | 1 to 128 characters |

**Request body** (`application/json`)

| Field | Type | Required | Notes |
|---|---|---|---|
| `versionId` | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes |  |
| `workspaceId` | string | yes |  |
| `name` | string | yes |  |
| `slug` | string | yes |  |
| `url` | string or null | yes |  |
| `status` | "live" · "paused" · "empty" | yes |  |
| `sharing` | "private" · "shared" · "workspace" · "public" | yes |  |
| `current` | object or null | yes |  |
| `current.id` | string | yes |  |
| `current.number` | integer | yes | at least 1 |
| `current.createdAt` | string (date-time) | yes |  |
| `current.createdBy` | object or null | yes |  |
| `current.bundleHash` | string | yes |  |
| `current.fileCount` | integer | yes | at least 0 |
| `current.totalBytes` | integer | yes | at least 0 |
| `current.spa` | boolean | yes |  |
| `current.hasIndex` | boolean | yes |  |
| `current.note` | string or null | yes |  |
| `current.source` | "console" · "api" | yes |  |
| `current.current` | boolean | yes |  |
| `versionCount` | integer | yes | at least 0 |
| `createdAt` | string (date-time) | yes |  |
| `updatedAt` | string (date-time) | yes |  |
| `spark` | integer[] | yes |  |
| `pages14d` | integer | yes | at least 0 |
| `canEdit` | boolean | yes |  |
| `description` | string | yes |  |
| `canDelete` | boolean | yes |  |
| `versions` | object[] | yes |  |
| `versions[].id` | string | yes |  |

…and 13 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[DELETE]] `/v1/sites/{id}/versions/{versionId}`

Delete a version that is not live, and the files only it used.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** `can_edit`; signed-in person only

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `id` | path | string | yes | 1 to 128 characters |
| `versionId` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes |  |
| `workspaceId` | string | yes |  |
| `name` | string | yes |  |
| `slug` | string | yes |  |
| `url` | string or null | yes |  |
| `status` | "live" · "paused" · "empty" | yes |  |
| `sharing` | "private" · "shared" · "workspace" · "public" | yes |  |
| `current` | object or null | yes |  |
| `current.id` | string | yes |  |
| `current.number` | integer | yes | at least 1 |
| `current.createdAt` | string (date-time) | yes |  |
| `current.createdBy` | object or null | yes |  |
| `current.bundleHash` | string | yes |  |
| `current.fileCount` | integer | yes | at least 0 |
| `current.totalBytes` | integer | yes | at least 0 |
| `current.spa` | boolean | yes |  |
| `current.hasIndex` | boolean | yes |  |
| `current.note` | string or null | yes |  |
| `current.source` | "console" · "api" | yes |  |
| `current.current` | boolean | yes |  |
| `versionCount` | integer | yes | at least 0 |
| `createdAt` | string (date-time) | yes |  |
| `updatedAt` | string (date-time) | yes |  |
| `spark` | integer[] | yes |  |
| `pages14d` | integer | yes | at least 0 |
| `canEdit` | boolean | yes |  |
| `description` | string | yes |  |
| `canDelete` | boolean | yes |  |
| `versions` | object[] | yes |  |
| `versions[].id` | string | yes |  |

…and 13 more fields. The full schema is in [openapi.json](https://docs.qaldy.com/openapi.json).

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/sites/{id}/versions/{versionId}/files`

The files of one version: path, size and type.

- **Authentication:** the console’s session cookie.
- **Token:** not available. This route is for a signed-in person in the console (`403 console_only` for a token).
- **Who:** `can_view`

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `id` | path | string | yes | 1 to 128 characters |
| `versionId` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `versionId` | string | yes |  |
| `spa` | boolean | yes |  |
| `files` | object[] | yes |  |
| `files[].path` | string | yes |  |
| `files[].size` | integer | yes | at least 0 |
| `files[].type` | string | yes |  |
| `files[].sha256` | string | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).

### [[GET]] `/v1/workspaces/{ws}/sites`

Sites you can open: status, live version and page views for 14 days.

- **Authentication:** the console’s session cookie.
- **Token:** a personal access token or an MCP sign-in with the `read` scope.
- **Who:** member, filtered to `can_view`. Tokens: `read`

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes |  |
| `workspaceId` | string | yes |  |
| `name` | string | yes |  |
| `slug` | string | yes |  |
| `url` | string or null | yes |  |
| `status` | "live" · "paused" · "empty" | yes |  |
| `sharing` | "private" · "shared" · "workspace" · "public" | yes |  |
| `current` | object or null | yes |  |
| `current.id` | string | yes |  |
| `current.number` | integer | yes | at least 1 |
| `current.createdAt` | string (date-time) | yes |  |
| `current.createdBy` | object or null | yes |  |
| `current.bundleHash` | string | yes |  |
| `current.fileCount` | integer | yes | at least 0 |
| `current.totalBytes` | integer | yes | at least 0 |
| `current.spa` | boolean | yes |  |
| `current.hasIndex` | boolean | yes |  |
| `current.note` | string or null | yes |  |
| `current.source` | "console" · "api" | yes |  |
| `current.current` | boolean | yes |  |
| `versionCount` | integer | yes | at least 0 |
| `createdAt` | string (date-time) | yes |  |
| `updatedAt` | string (date-time) | yes |  |
| `spark` | integer[] | yes |  |
| `pages14d` | integer | yes | at least 0 |
| `canEdit` | boolean | yes |  |

Errors: `400`, `401`, `403`, `404`, `409`, `429` (the error format is on the [overview](https://docs.qaldy.com/reference/api/#errors)).