# 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.

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

2 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 |
|---|---|---|
| [[POST]] | [`/​v1/​workspaces/​{ws}/​roads`](#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`](#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_only` for a token).
- **Who:** builder or above, and `can_edit` on 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](https://docs.qaldy.com/reference/api/#errors)).

### [[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 `read` scope.
- **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](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)).