# Build

Describe an app, read the plan and its permissions, approve it, and the templates to start from. 3 routes, from the API’s own OpenAPI document.

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

3 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/​builds/​{buildId}/​approve`](#post-v1-builds-buildid-approve) | Approve the manifest: the building rises as the build progresses (events) |
| [[GET]] | [`/​v1/​templates`](#get-v1-templates) | Gallery templates (hours per month are estimates) |
| [[POST]] | [`/​v1/​workspaces/​{ws}/​builds`](#post-v1-workspaces-ws-builds) | Plan a build: permission manifest + steps, nothing runs yet |

## Reference

### [[POST]] `/v1/builds/{buildId}/approve`

Approve the manifest: the building rises as the build progresses (events).

- **Authentication:** the console’s session cookie.
- **Token:** a personal access token or an MCP sign-in with the `write` scope.
- **Who:** build owner; a manifest that uses a connector or declares AI needs an admin: a member gets `403 admin_approval_required` and an audit row `build.approval_refused`

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

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

| Field | Type | Required | Notes |
|---|---|---|---|
| `manifest` | object | yes |  |
| `manifest.name` | string | yes | 2 to 60 characters |
| `manifest.description` | string | yes | 4 to 280 characters |
| `manifest.archetype` | "kiosk" · "tower" · "warehouse" · "workshop" · "bank" · "townhall" · "clocktower" · "printhouse" · … | yes |  |
| `manifest.category` | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes |  |
| `manifest.permissions` | object | yes |  |
| `manifest.permissions.data` | object[] | yes |  |
| `manifest.permissions.connectors` | object[] | yes |  |
| `manifest.permissions.egress` | object[] | yes |  |
| `manifest.permissions.ai` | object or null | yes |  |
| `manifest.triggers` | object[] | yes |  |
| `manifest.sharing` | object | yes |  |
| `manifest.sharing.default` | "private" · "team" · "workspace" | yes |  |
| `manifest.roi` | object | yes |  |
| `manifest.roi.manualMinutesPerRun` | number | yes | 0 to 1440 |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `appId` | 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/templates`

Gallery templates (hours per month are estimates).

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

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `id` | string | yes |  |
| `name` | string | yes | at least 2 characters |
| `tagline` | string | yes | 4 to 120 characters |
| `archetype` | "kiosk" · "tower" · "warehouse" · "workshop" · "bank" · "townhall" · "clocktower" · "printhouse" · … | yes |  |
| `category` | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes |  |
| `connectors` | "shop" · "stripe" · "gmail" · "telegram" · "sheets" · "slack" · "kaspi" · "1c" · …[] | yes |  |
| `manualMinutesPerRun` | number | yes | at least 0 |
| `estRunsPerMonth` | number | yes | at least 0 |
| `samplePrompt` | string | yes | at least 8 characters |
| `manifest` | object | yes |  |
| `manifest.name` | string | yes | 2 to 60 characters |
| `manifest.description` | string | yes | 4 to 280 characters |
| `manifest.archetype` | "kiosk" · "tower" · "warehouse" · "workshop" · "bank" · "townhall" · "clocktower" · "printhouse" · … | yes |  |
| `manifest.category` | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes |  |
| `manifest.permissions` | object | yes |  |
| `manifest.triggers` | object[] | yes |  |
| `manifest.sharing` | object | yes |  |
| `manifest.roi` | object | yes |  |
| `regions` | "global" · "kz"[] | yes |  |
| `previewServices` | string[] |  | up to 4 items |

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

### [[POST]] `/v1/workspaces/{ws}/builds`

Plan a build: permission manifest + steps, nothing runs yet.

- **Authentication:** the console’s session cookie.
- **Token:** a personal access token or an MCP sign-in with the `write` scope.
- **Who:** builder, admin or owner (a member or viewer gets 403 `builder_only`)

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

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

| Field | Type | Required | Notes |
|---|---|---|---|
| `prompt` | string | yes | 4 to 2000 characters |
| `templateId` | string |  |  |
| `plot` | object |  |  |
| `plot.x` | integer | yes | at least 0 |
| `plot.y` | integer | yes | at least 0 |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `buildId` | string | yes | at least 1 characters |
| `appId` | string | yes | at least 1 characters |
| `prompt` | string | yes |  |
| `manifest` | object | yes |  |
| `manifest.name` | string | yes | 2 to 60 characters |
| `manifest.description` | string | yes | 4 to 280 characters |
| `manifest.archetype` | "kiosk" · "tower" · "warehouse" · "workshop" · "bank" · "townhall" · "clocktower" · "printhouse" · … | yes |  |
| `manifest.category` | "interface" · "data" · "messaging" · "money" · "ai" · "time" · "people" · "growth" | yes |  |
| `manifest.permissions` | object | yes |  |
| `manifest.triggers` | object[] | yes |  |
| `manifest.sharing` | object | yes |  |
| `manifest.roi` | object | yes |  |
| `steps` | string[] | yes |  |
| `builder` | "claude" · "offline" | yes |  |
| `model` | string or null | yes |  |
| `templateId` | string or null | yes |  |

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