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.
3 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/builds/{buildId}/approve | Approve the manifest: the building rises as the build progresses (events) |
| GET | /v1/templates | Gallery templates (hours per month are estimates) |
| 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
writescope. - Who: build owner; a manifest that uses a connector or declares AI needs an admin: a member gets
403 admin_approval_requiredand an audit rowbuild.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).
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
readscope. - 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).
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
writescope. - 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).