# builder

 2 routes, from the API’s own OpenAPI document.

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

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 |
|---|---|---|
| [[GET]] | [`/​v1/​workspaces/​{ws}/​builder`](#get-v1-workspaces-ws-builder) | The AI builder: its state, this month’s spend and the ledger (admins) |
| [[PUT]] | [`/​v1/​workspaces/​{ws}/​builder`](#put-v1-workspaces-ws-builder) | Pause the AI builder, or lower the workspace’s monthly budget (admins) |

## Reference

### [[GET]] `/v1/workspaces/{ws}/builder`

The AI builder: its state, this month’s spend and the ledger (admins).

- **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:** admin, a person in the console (a token is not on the allow-list)

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

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `state` | "on" · "paused" · "workspace_budget" · "platform_budget" · "kill_switch" · "profile" · "not_enabled" | yes |  |
| `month` | string | yes |  |
| `resetsAt` | string (date-time) | yes |  |
| `spentUsd` | number | yes | at least 0 |
| `capUsd` | number | yes | at least 0 |
| `defaultCapUsd` | number | yes | at least 0 |
| `perBuildCapUsd` | number | yes | at least 0 |
| `ownCap` | boolean | yes |  |
| `paused` | boolean | yes |  |
| `operations` | integer | yes | at least 0 |
| `ledger` | object[] | yes | up to 100 items |
| `ledger[].id` | string | yes |  |
| `ledger[].at` | string (date-time) | yes |  |
| `ledger[].kind` | "plan" · "build" · "edit-plan" · "edit" | yes |  |
| `ledger[].userId` | string or null | yes |  |
| `ledger[].userName` | string or null | yes |  |
| `ledger[].appId` | string or null | yes |  |
| `ledger[].appName` | string or null | yes |  |
| `ledger[].model` | string | yes |  |
| `ledger[].calls` | integer | yes | at least 1 |
| `ledger[].tokens` | object | yes |  |
| `ledger[].costUsd` | number | yes | at least 0 |
| `ledger[].capReached` | boolean | yes |  |
| `ledgerTruncated` | boolean | yes |  |

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

### [[PUT]] `/v1/workspaces/{ws}/builder`

Pause the AI builder, or lower the workspace’s monthly budget (admins).

- **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:** admin, a person in the console (a token is refused)

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

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

| Field | Type | Required | Notes |
|---|---|---|---|
| `paused` | boolean |  |  |
| `monthlyCapUsd` | number or null |  | 0 to 1000 |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `state` | "on" · "paused" · "workspace_budget" · "platform_budget" · "kill_switch" · "profile" · "not_enabled" | yes |  |
| `month` | string | yes |  |
| `resetsAt` | string (date-time) | yes |  |
| `spentUsd` | number | yes | at least 0 |
| `capUsd` | number | yes | at least 0 |
| `defaultCapUsd` | number | yes | at least 0 |
| `perBuildCapUsd` | number | yes | at least 0 |
| `ownCap` | boolean | yes |  |
| `paused` | boolean | yes |  |
| `operations` | integer | yes | at least 0 |
| `ledger` | object[] | yes | up to 100 items |
| `ledger[].id` | string | yes |  |
| `ledger[].at` | string (date-time) | yes |  |
| `ledger[].kind` | "plan" · "build" · "edit-plan" · "edit" | yes |  |
| `ledger[].userId` | string or null | yes |  |
| `ledger[].userName` | string or null | yes |  |
| `ledger[].appId` | string or null | yes |  |
| `ledger[].appName` | string or null | yes |  |
| `ledger[].model` | string | yes |  |
| `ledger[].calls` | integer | yes | at least 1 |
| `ledger[].tokens` | object | yes |  |
| `ledger[].costUsd` | number | yes | at least 0 |
| `ledger[].capReached` | boolean | yes |  |
| `ledgerTruncated` | boolean | yes |  |

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