Workspace snapshot
Everything the City draws for a workspace: apps, automations, gates, runs and people, and the version of that snapshot. 2 routes, from the API’s own OpenAPI document.
2 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 |
|---|---|---|
| POST | /v1/workspaces/{ws}/roads | Draw a road (automation): from a gate or app, through apps (via), to a gate or app, with its trigger settings |
| GET | /v1/workspaces/{ws}/world | The City: WorldSnapshot of a workspace, filtered to apps you can view |
Reference#
POST /v1/workspaces/{ws}/roads#
Draw a road (automation): from a gate or app, through apps (via), to a gate or app, with its trigger settings.
- 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: builder or above, and
can_editon every app it stops at
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
ws | path | string | yes | 1 to 128 characters |
Request body (application/json)
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | yes | 1 to 60 characters |
from | object | yes | |
from.kind | "gate" · "building" | yes | |
from.id | string | yes | at least 1 characters |
to | object | yes | |
to.kind | "gate" · "building" | yes | |
to.id | string | yes | at least 1 characters |
trigger | "schedule" · "webhook" · "form" · "manual" · "event" | yes | |
via | object[] | up to 6 items | |
via[].kind | "gate" · "building" | yes | |
via[].id | string | yes | at least 1 characters |
triggerConfig | object |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
id | string | yes | at least 1 characters |
name | string | yes | at least 1 characters |
from | object | yes | |
from.kind | "gate" · "building" | yes | |
from.id | string | yes | at least 1 characters |
to | object | yes | |
to.kind | "gate" · "building" | yes | |
to.id | string | yes | at least 1 characters |
via | object[] | yes | |
via[].kind | "gate" · "building" | yes | |
via[].id | string | yes | at least 1 characters |
category | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes | |
trigger | "schedule" · "webhook" · "form" · "manual" · "event" | yes | |
status | "active" · "paused" · "failing" | yes | |
path | object[] or null | yes | |
path[].x | integer | yes | at least 0 |
path[].y | integer | yes | at least 0 |
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).
GET /v1/workspaces/{ws}/world#
The City: WorldSnapshot of a workspace, filtered to apps you can view.
- Authentication: the console’s session cookie.
- Token: a personal access token or an MCP sign-in with the
readscope. - Who: workspace member
| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
ws | path | string | yes | 1 to 128 characters |
Response 200
| Field | Type | Required | Notes |
|---|---|---|---|
version | 1 | yes | |
seq | integer | yes | at least 0 |
generatedAt | string (date-time) | yes | |
demo | boolean | yes | |
workspace | object | yes | |
workspace.id | string | yes | at least 1 characters |
workspace.slug | string | yes | at least 1 characters |
workspace.name | string | yes | at least 1 characters |
workspace.profile | "global" · "eu" · "kz-standard" · "kz-strict" | yes | |
workspace.cell | "global" · "eu" · "kz" | yes | |
workspace.locale | "en" · "ru" · "kk" | yes | |
workspace.timezone | string | yes | at least 1 characters |
workspace.hourlyCostMinor | integer | yes | at least 0 |
workspace.currency | "EUR" · "USD" · "KZT" | yes | |
workspace.memberCount | integer | yes | at least 0 |
island | object | yes | |
island.width | integer | yes | 6 to 64 |
island.height | integer | yes | 6 to 64 |
districts | object[] | yes | |
districts[].id | string | yes | at least 1 characters |
districts[].name | string | yes | at least 1 characters |
districts[].kind | "team" · "purpose" | yes | |
gates | object[] | yes | |
gates[].id | string | yes | at least 1 characters |
gates[].connectorId | "shop" · "stripe" · "gmail" · "telegram" · "sheets" · "slack" · "kaspi" · "1c" · … | yes | |
gates[].displayName | string | yes | at least 1 characters |
gates[].status | "connected" · "expired" · "error" · "disconnected" | yes | |
gates[].side | "north" · "east" · "south" · "west" | yes | |
gates[].plot | object or null | yes | |
buildings | object[] | yes |
…and 34 more fields. The full schema is in openapi.json.
Errors: 400, 401, 403, 404, 409, 429 (the error format is on the overview).