# Plan and spending cap

The workspace’s plan, its allowances and the hard spending cap. Billing is mock in the pilot. 2 routes, from the API’s own OpenAPI document.

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

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}/​plan`](#get-v1-workspaces-ws-plan) | The plan, what it includes, the headline meters and the spend cap (MOCK billing) |
| [[PUT]] | [`/​v1/​workspaces/​{ws}/​plan`](#put-v1-workspaces-ws-plan) | Change the plan and the spend cap settings (admins; the cap amount needs the owner) |

## Reference

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

The plan, what it includes, the headline meters and the spend cap (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).

| 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 |  |
| `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 |
| `entitlements` | object | yes |  |
| `entitlements.plan` | "free" · "maker" · "team" · "business" · "sovereign" | yes |  |
| `entitlements.name` | string | yes | at least 1 characters |
| `entitlements.apps` | integer or null | yes |  |
| `entitlements.builders` | integer or null | yes |  |
| `entitlements.contract` | boolean | yes |  |
| `entitlements.viewers` | "free" | yes |  |
| `entitlements.addOns` | object | yes |  |
| `entitlements.headline` | object[] | yes |  |
| `entitlements.units` | object[] | yes |  |
| `headline` | object[] | yes |  |
| `headline[].id` | "runs" · "requests" · "storage" · "ai" | yes |  |
| `headline[].kind` | "cpu_time" · "concurrency" · "runs" · "requests" · "egress_gb" · "storage_db_gb" · "storage_files_gb" · "ai_credits" · … | yes |  |
| `headline[].used` | number or null | yes | at least 0 |
| `headline[].allowance` | number | yes | at least 0 |
| `headline[].projected` | number or null | yes | at least 0 |
| `headline[].pct` | number or null | yes | 0 to 1000 |
| `headline[].band` | "ok" · "near" · "at" · null or null | yes |  |
| `headline[].source` | "runs_table" · "baas_log" · "row_estimate" · "ledger" · "mock" · "none" | yes |  |
| `headline[].estimate` | boolean | yes |  |

…and 6 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}/plan`

Change the plan and the spend cap settings (admins; the cap amount needs the owner).

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

| 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" |  |  |
| `spend` | object |  |  |
| `spend.hardCap` | boolean |  |  |
| `spend.alerts` | 50 or 75 or 90 or 100[] |  | up to 4 items |
| `spend.cap` | object or null |  |  |
| `spend.cap.currency` | "EUR" · "USD" · "KZT" | yes |  |
| `spend.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 |  |
| `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 |
| `entitlements` | object | yes |  |
| `entitlements.plan` | "free" · "maker" · "team" · "business" · "sovereign" | yes |  |
| `entitlements.name` | string | yes | at least 1 characters |
| `entitlements.apps` | integer or null | yes |  |
| `entitlements.builders` | integer or null | yes |  |
| `entitlements.contract` | boolean | yes |  |
| `entitlements.viewers` | "free" | yes |  |
| `entitlements.addOns` | object | yes |  |
| `entitlements.headline` | object[] | yes |  |
| `entitlements.units` | object[] | yes |  |
| `headline` | object[] | yes |  |
| `headline[].id` | "runs" · "requests" · "storage" · "ai" | yes |  |
| `headline[].kind` | "cpu_time" · "concurrency" · "runs" · "requests" · "egress_gb" · "storage_db_gb" · "storage_files_gb" · "ai_credits" · … | yes |  |
| `headline[].used` | number or null | yes | at least 0 |
| `headline[].allowance` | number | yes | at least 0 |
| `headline[].projected` | number or null | yes | at least 0 |
| `headline[].pct` | number or null | yes | 0 to 1000 |
| `headline[].band` | "ok" · "near" · "at" · null or null | yes |  |
| `headline[].source` | "runs_table" · "baas_log" · "row_estimate" · "ledger" · "mock" · "none" | yes |  |
| `headline[].estimate` | boolean | yes |  |

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