# Apps

Read an app, run it, pause it, move it on the island. 4 routes, from the API’s own OpenAPI document.

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

4 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/​apps/​{id}`](#get-v1-apps-id) | One app: building, manifest, version, sharing, recent runs |
| [[POST]] | [`/​v1/​apps/​{id}/​move`](#post-v1-apps-id-move) | Move a building to another plot |
| [[POST]] | [`/​v1/​apps/​{id}/​pause`](#post-v1-apps-id-pause) | Pause or resume an app |
| [[POST]] | [`/​v1/​apps/​{id}/​runs`](#post-v1-apps-id-runs) | Run an app now |

## Reference

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

One app: building, manifest, version, sharing, recent runs.

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

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

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `building` | object | yes |  |
| `building.id` | string | yes | at least 1 characters |
| `building.slug` | string | yes | at least 1 characters |
| `building.name` | string | yes | at least 1 characters |
| `building.description` | string | yes |  |
| `building.archetype` | "kiosk" · "tower" · "warehouse" · "workshop" · "bank" · "townhall" · "clocktower" · "printhouse" · … | yes |  |
| `building.category` | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes |  |
| `building.status` | "draft" · "building" · "healthy" · "warning" · "failing" · "paused" | yes |  |
| `building.plot` | object or null | yes |  |
| `building.footprint` | object | yes |  |
| `building.level` | 1 or 2 or 3 | yes |  |
| `building.sharing` | "private" · "shared" · "workspace" · "public" | yes |  |
| `building.districtId` | string or null | yes |  |
| `building.trustScore` | integer or null | yes | 0 to 100 |
| `building.runsTotal` | integer | yes | at least 0 |
| `building.runsThisMonth` | integer | yes | at least 0 |
| `building.lastRunAt` | string (date-time) or null | yes |  |
| `building.nextRunAt` | string (date-time) or null | yes |  |
| `building.kpi` | object or null | yes |  |
| `building.rows` | integer or null | yes | at least 0 |
| `building.construction` | object or null | yes |  |
| `building.failure` | object or null | yes |  |
| `building.viewers` | integer | yes | at least 0 |
| `building.pendingApprovals` | integer | yes | at least 0 |
| `building.connectors` | "shop" · "stripe" · "gmail" · "telegram" · "sheets" · "slack" · "kaspi" · "1c" · …[] | yes |  |
| `building.manualMinutesPerRun` | number | yes | at least 0 |
| `building.createdBy` | string | yes | at least 1 characters |
| `building.currentVersionId` | string or null | yes |  |
| `manifest` | object | yes |  |
| `manifest.name` | string | yes | 2 to 60 characters |

…and 11 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)).

### [[POST]] `/v1/apps/{id}/move`

Move a building to another plot.

- **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`

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

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

| Field | Type | Required | Notes |
|---|---|---|---|
| `plot` | object | yes |  |
| `plot.x` | integer | yes | at least 0 |
| `plot.y` | integer | yes | at least 0 |

**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/apps/{id}/pause`

Pause or resume an app.

- **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`

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

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

| Field | Type | Required | Notes |
|---|---|---|---|
| `paused` | boolean | yes |  |

**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/apps/{id}/runs`

Run an app now.

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

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

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

An empty object: `{}`.

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `runId` | string | yes | at least 1 characters |
| `held` | boolean |  |  |

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