# Capacity and plan changes

The resource pool, previewing and applying a change, the monthly budget and autoscale settings. 6 routes, from the API’s own OpenAPI document.

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

6 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}/​capacity`](#get-v1-workspaces-ws-capacity) | Plan, allocations, usage, tips and list prices (MOCK billing) |
| [[POST]] | [`/​v1/​workspaces/​{ws}/​capacity`](#post-v1-workspaces-ws-capacity) | Apply a capacity change (admins; the plan needs the owner). MOCK billing |
| [[PUT]] | [`/​v1/​workspaces/​{ws}/​capacity/​autoscale`](#put-v1-workspaces-ws-capacity-autoscale) | Save autopilot settings (admins). Planned: nothing acts on them yet |
| [[PUT]] | [`/​v1/​workspaces/​{ws}/​capacity/​budget`](#put-v1-workspaces-ws-capacity-budget) | Set the monthly add-on budget cap (owner). Nothing is bought above it |
| [[POST]] | [`/​v1/​workspaces/​{ws}/​capacity/​preview`](#post-v1-workspaces-ws-capacity-preview) | Price, land and problems of a capacity change; writes nothing |
| [[GET]] | [`/​v1/​workspaces/​{ws}/​usage`](#get-v1-workspaces-ws-usage) | Daily usage per resource (measured or labelled estimate) |

## Reference

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

Plan, allocations, usage, tips and list prices (MOCK billing).

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

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

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `workspaceId` | string | yes | at least 1 characters |
| `version` | integer | yes | at least 0 |
| `plan` | "free" · "maker" · "team" · "business" · "sovereign" | yes |  |
| `planSource` | "default" · "set" | yes |  |
| `currency` | "EUR" · "USD" · "KZT" | yes |  |
| `timezone` | string | yes | at least 1 characters |
| `period` | object | yes |  |
| `period.start` | string (date-time) | yes |  |
| `period.end` | string (date-time) | yes |  |
| `period.daysInPeriod` | integer | yes | 28 to 31 |
| `period.day` | integer | yes | 1 to 31 |
| `allocations` | object[] | yes |  |
| `allocations[].kind` | "cpu_time" · "concurrency" · "runs" · "requests" · "egress_gb" · "storage_db_gb" · "storage_files_gb" · "ai_credits" · … | yes |  |
| `allocations[].status` | "available" · "planned" | yes |  |
| `allocations[].gaugeKind` | "period" · "instant" · "stock" | yes |  |
| `allocations[].included` | number | yes | at least 0 |
| `allocations[].addOnSteps` | integer | yes | at least 0 |
| `allocations[].stepSize` | number | yes | at least 0 |
| `allocations[].total` | number | yes | at least 0 |
| `allocations[].periodTotal` | number | yes | at least 0 |
| `usage` | object[] | yes |  |
| `usage[].kind` | "cpu_time" · "concurrency" · "runs" · "requests" · "egress_gb" · "storage_db_gb" · "storage_files_gb" · "ai_credits" · … | yes |  |
| `usage[].used` | number or null | yes | at least 0 |
| `usage[].source` | "runs_table" · "baas_log" · "row_estimate" · "ledger" · "mock" · "none" | yes |  |
| `usage[].estimate` | boolean | yes |  |
| `usage[].note` | string or null | yes |  |
| `usage[].measuredAt` | string (date-time) or null | yes |  |
| `quotas` | object[] | yes |  |
| `quotas[].kind` | "cpu_time" · "concurrency" · "runs" · "requests" · "egress_gb" · "storage_db_gb" · "storage_files_gb" · "ai_credits" · … | yes |  |
| `quotas[].used` | number or null | yes | at least 0 |

…and 18 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)).

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

Apply a capacity change (admins; the plan needs the owner). MOCK billing.

- **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 (plan: owner); signed-in person only, never a token

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

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

| Field | Type | Required | Notes |
|---|---|---|---|
| `basedOnVersion` | integer | yes | at least 0 |
| `idempotencyKey` | string |  | 8 to 128 characters |
| `plan` | "free" · "maker" · "team" · "business" · "sovereign" |  |  |
| `lines` | object[] | yes | up to 17 items |
| `lines[].kind` | "cpu_time" · "concurrency" · "runs" · "requests" · "egress_gb" · "storage_db_gb" · "storage_files_gb" · "ai_credits" · … | yes |  |
| `lines[].addOnSteps` | integer | yes | 0 to 100000 |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `change` | object | yes |  |
| `change.id` | string | yes | at least 1 characters |
| `change.workspaceId` | string | yes | at least 1 characters |
| `change.version` | integer | yes | at least 1 |
| `change.actor` | object | yes |  |
| `change.plan` | object | yes |  |
| `change.lines` | object[] | yes |  |
| `change.monthlyDelta` | object | yes |  |
| `change.today` | object | yes |  |
| `change.island` | object | yes |  |
| `change.billing` | object | yes |  |
| `change.createdAt` | string (date-time) | yes |  |
| `state` | object | yes |  |
| `state.workspaceId` | string | yes | at least 1 characters |
| `state.version` | integer | yes | at least 0 |
| `state.plan` | "free" · "maker" · "team" · "business" · "sovereign" | yes |  |
| `state.planSource` | "default" · "set" | yes |  |
| `state.currency` | "EUR" · "USD" · "KZT" | yes |  |
| `state.timezone` | string | yes | at least 1 characters |
| `state.period` | object | yes |  |
| `state.allocations` | object[] | yes |  |
| `state.usage` | object[] | yes |  |
| `state.quotas` | object[] | yes |  |
| `state.land` | object | yes |  |
| `state.monthly` | object or null | yes |  |
| `state.budget` | object or null | yes |  |
| `state.canChange` | boolean | yes |  |
| `state.canChangePlan` | boolean | yes |  |
| `state.autoscale` | object | yes |  |
| `state.recommendations` | object[] | yes |  |

…and 4 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)).

### [[PUT]] `/v1/workspaces/{ws}/capacity/autoscale`

Save autopilot settings (admins). Planned: nothing acts on them yet.

- **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

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

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

| Field | Type | Required | Notes |
|---|---|---|---|
| `enabled` | boolean | yes |  |
| `units` | object[] | yes | up to 17 items |
| `units[].kind` | "cpu_time" · "concurrency" · "runs" · "requests" · "egress_gb" · "storage_db_gb" · "storage_files_gb" · "ai_credits" · … | yes |  |
| `units[].minSteps` | integer | yes | 0 to 1000 |
| `units[].maxSteps` | integer | yes | 0 to 1000 |
| `schedules` | object[] | yes | up to 8 items |
| `schedules[].kind` | "cpu_time" · "concurrency" · "runs" · "requests" · "egress_gb" · "storage_db_gb" · "storage_files_gb" · "ai_credits" · … | yes |  |
| `schedules[].days` | integer[] | yes | up to 7 items |
| `schedules[].from` | string | yes |  |
| `schedules[].to` | string | yes |  |
| `schedules[].addOnSteps` | integer | yes | 0 to 1000 |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `workspaceId` | string | yes | at least 1 characters |
| `version` | integer | yes | at least 0 |
| `plan` | "free" · "maker" · "team" · "business" · "sovereign" | yes |  |
| `planSource` | "default" · "set" | yes |  |
| `currency` | "EUR" · "USD" · "KZT" | yes |  |
| `timezone` | string | yes | at least 1 characters |
| `period` | object | yes |  |
| `period.start` | string (date-time) | yes |  |
| `period.end` | string (date-time) | yes |  |
| `period.daysInPeriod` | integer | yes | 28 to 31 |
| `period.day` | integer | yes | 1 to 31 |
| `allocations` | object[] | yes |  |
| `allocations[].kind` | "cpu_time" · "concurrency" · "runs" · "requests" · "egress_gb" · "storage_db_gb" · "storage_files_gb" · "ai_credits" · … | yes |  |
| `allocations[].status` | "available" · "planned" | yes |  |
| `allocations[].gaugeKind` | "period" · "instant" · "stock" | yes |  |
| `allocations[].included` | number | yes | at least 0 |
| `allocations[].addOnSteps` | integer | yes | at least 0 |
| `allocations[].stepSize` | number | yes | at least 0 |
| `allocations[].total` | number | yes | at least 0 |
| `allocations[].periodTotal` | number | yes | at least 0 |
| `usage` | object[] | yes |  |
| `usage[].kind` | "cpu_time" · "concurrency" · "runs" · "requests" · "egress_gb" · "storage_db_gb" · "storage_files_gb" · "ai_credits" · … | yes |  |
| `usage[].used` | number or null | yes | at least 0 |
| `usage[].source` | "runs_table" · "baas_log" · "row_estimate" · "ledger" · "mock" · "none" | yes |  |
| `usage[].estimate` | boolean | yes |  |
| `usage[].note` | string or null | yes |  |
| `usage[].measuredAt` | string (date-time) or null | yes |  |
| `quotas` | object[] | yes |  |
| `quotas[].kind` | "cpu_time" · "concurrency" · "runs" · "requests" · "egress_gb" · "storage_db_gb" · "storage_files_gb" · "ai_credits" · … | yes |  |
| `quotas[].used` | number or null | yes | at least 0 |

…and 18 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)).

### [[PUT]] `/v1/workspaces/{ws}/capacity/budget`

Set the monthly add-on budget cap (owner). Nothing is bought above it.

- **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:** owner

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

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

| Field | Type | Required | Notes |
|---|---|---|---|
| `cap` | object or null | yes |  |
| `cap.currency` | "EUR" · "USD" · "KZT" | yes |  |
| `cap.minor` | integer | yes |  |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `workspaceId` | string | yes | at least 1 characters |
| `version` | integer | yes | at least 0 |
| `plan` | "free" · "maker" · "team" · "business" · "sovereign" | yes |  |
| `planSource` | "default" · "set" | yes |  |
| `currency` | "EUR" · "USD" · "KZT" | yes |  |
| `timezone` | string | yes | at least 1 characters |
| `period` | object | yes |  |
| `period.start` | string (date-time) | yes |  |
| `period.end` | string (date-time) | yes |  |
| `period.daysInPeriod` | integer | yes | 28 to 31 |
| `period.day` | integer | yes | 1 to 31 |
| `allocations` | object[] | yes |  |
| `allocations[].kind` | "cpu_time" · "concurrency" · "runs" · "requests" · "egress_gb" · "storage_db_gb" · "storage_files_gb" · "ai_credits" · … | yes |  |
| `allocations[].status` | "available" · "planned" | yes |  |
| `allocations[].gaugeKind` | "period" · "instant" · "stock" | yes |  |
| `allocations[].included` | number | yes | at least 0 |
| `allocations[].addOnSteps` | integer | yes | at least 0 |
| `allocations[].stepSize` | number | yes | at least 0 |
| `allocations[].total` | number | yes | at least 0 |
| `allocations[].periodTotal` | number | yes | at least 0 |
| `usage` | object[] | yes |  |
| `usage[].kind` | "cpu_time" · "concurrency" · "runs" · "requests" · "egress_gb" · "storage_db_gb" · "storage_files_gb" · "ai_credits" · … | yes |  |
| `usage[].used` | number or null | yes | at least 0 |
| `usage[].source` | "runs_table" · "baas_log" · "row_estimate" · "ledger" · "mock" · "none" | yes |  |
| `usage[].estimate` | boolean | yes |  |
| `usage[].note` | string or null | yes |  |
| `usage[].measuredAt` | string (date-time) or null | yes |  |
| `quotas` | object[] | yes |  |
| `quotas[].kind` | "cpu_time" · "concurrency" · "runs" · "requests" · "egress_gb" · "storage_db_gb" · "storage_files_gb" · "ai_credits" · … | yes |  |
| `quotas[].used` | number or null | yes | at least 0 |

…and 18 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)).

### [[POST]] `/v1/workspaces/{ws}/capacity/preview`

Price, land and problems of a capacity change; writes nothing.

- **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:** member

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

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

| Field | Type | Required | Notes |
|---|---|---|---|
| `basedOnVersion` | integer | yes | at least 0 |
| `idempotencyKey` | string |  | 8 to 128 characters |
| `plan` | "free" · "maker" · "team" · "business" · "sovereign" |  |  |
| `lines` | object[] | yes | up to 17 items |
| `lines[].kind` | "cpu_time" · "concurrency" · "runs" · "requests" · "egress_gb" · "storage_db_gb" · "storage_files_gb" · "ai_credits" · … | yes |  |
| `lines[].addOnSteps` | integer | yes | 0 to 100000 |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `basedOnVersion` | integer | yes | at least 0 |
| `plan` | object | yes |  |
| `plan.from` | "free" · "maker" · "team" · "business" · "sovereign" | yes |  |
| `plan.to` | "free" · "maker" · "team" · "business" · "sovereign" | yes |  |
| `lines` | object[] | yes |  |
| `lines[].kind` | "cpu_time" · "concurrency" · "runs" · "requests" · "egress_gb" · "storage_db_gb" · "storage_files_gb" · "ai_credits" · … | yes |  |
| `lines[].fromSteps` | integer | yes | at least 0 |
| `lines[].toSteps` | integer | yes | at least 0 |
| `lines[].fromTotal` | number | yes | at least 0 |
| `lines[].toTotal` | number | yes | at least 0 |
| `lines[].monthlyDelta` | object | yes |  |
| `lines[].today` | object | yes |  |
| `lines[].effective` | "now" | yes |  |
| `lines[].periodFromTotal` | number |  | at least 0 |
| `lines[].periodToTotal` | number |  | at least 0 |
| `monthly` | object or null | yes |  |
| `monthly.from` | object | yes |  |
| `monthly.to` | object | yes |  |
| `monthly.delta` | object | yes |  |
| `today` | object or null | yes |  |
| `today.currency` | "EUR" · "USD" · "KZT" | yes |  |
| `today.minor` | integer | yes |  |
| `proration` | object | yes |  |
| `proration.daysCharged` | integer | yes | at least 0 |
| `proration.daysCredited` | integer | yes | at least 0 |
| `proration.daysInPeriod` | integer | yes |  |
| `land` | object | yes |  |
| `land.from` | object | yes |  |
| `land.to` | object | yes |  |
| `land.entitledFrom` | integer | yes | at least 0 |

…and 7 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)).

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

Daily usage per resource (measured or labelled estimate).

- **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:** member

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `ws` | path | string | yes | 1 to 128 characters |
| `range` | query | "7d" · "30d" · "90d" |  | default "30d" |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `range` | "7d" · "30d" · "90d" | yes |  |
| `from` | string (date) | yes |  |
| `to` | string (date) | yes |  |
| `timezone` | string | yes | at least 1 characters |
| `units` | object[] | yes |  |
| `units[].kind` | "cpu_time" · "concurrency" · "runs" · "requests" · "egress_gb" · "storage_db_gb" · "storage_files_gb" · "ai_credits" · … | yes |  |
| `units[].source` | "runs_table" · "baas_log" · "row_estimate" · "ledger" · "mock" · "none" | yes |  |
| `units[].estimate` | boolean | yes |  |
| `units[].note` | string or null | yes |  |
| `units[].points` | object[] | yes | up to 93 items |

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