Apps
Read an app, run it, pause it, move it on the island. 4 routes, from the API’s own OpenAPI document.
4 routes. Every path starts at https://cloud-api.qaldy.com. Sign-in, tokens, errors and limits are on the overview.
Routes#
| Method | Path | What it does |
|---|---|---|
| GET | /v1/apps/{id} | One app: building, manifest, version, sharing, recent runs |
| POST | /v1/apps/{id}/move | Move a building to another plot |
| POST | /v1/apps/{id}/pause | Pause or resume an app |
| 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
readscope. - 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.
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
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_onlyfor 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).
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_onlyfor 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).
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
writescope. - 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).