# Regions and scaling

Where apps run, what is live and what is planned, and each app’s scaling policy (Preview). 4 routes, from the API’s own OpenAPI document.

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

4 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}/​apps/​{appId}/​scaling`](#get-v1-workspaces-ws-apps-appid-scaling) | One app's scaling policy, the plan default and the limits (Preview) |
| [[PUT]] | [`/​v1/​workspaces/​{ws}/​apps/​{appId}/​scaling`](#put-v1-workspaces-ws-apps-appid-scaling) | Set an app's scaling policy (editors). Checked against the workspace's runs at once. Preview: saved, not applied yet |
| [[GET]] | [`/​v1/​workspaces/​{ws}/​infrastructure`](#get-v1-workspaces-ws-infrastructure) | Providers, regions, where this workspace sits and how its apps scale |
| [[GET]] | [`/​v1/​workspaces/​{ws}/​residency`](#get-v1-workspaces-ws-residency) | Where this workspace’s data lives: cell, providers, backups, Kazakhstan Planned |

## Reference

### [[GET]] `/v1/workspaces/{ws}/apps/{appId}/scaling`

One app's scaling policy, the plan default and the limits (Preview).

- **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:** can view the app

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

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `appId` | string | yes | at least 1 characters |
| `policy` | object | yes |  |
| `policy.minWarm` | 0 or 1 | yes |  |
| `policy.maxConcurrency` | integer | yes | 1 to 100000 |
| `policy.sleepAfterIdleMin` | 1 or 5 or 15 or 30 or 60 | yes |  |
| `policy.placement` | "auto" · "region-pin" | yes |  |
| `policy.burst` | boolean | yes |  |
| `source` | "default" · "custom" | yes |  |
| `defaults` | object | yes |  |
| `defaults.minWarm` | 0 or 1 | yes |  |
| `defaults.maxConcurrency` | integer | yes | 1 to 100000 |
| `defaults.sleepAfterIdleMin` | 1 or 5 or 15 or 30 or 60 | yes |  |
| `defaults.placement` | "auto" · "region-pin" | yes |  |
| `defaults.burst` | boolean | yes |  |
| `limits` | object | yes |  |
| `limits.maxConcurrency` | integer | yes | at least 1 |
| `limits.warmAllowed` | boolean | yes |  |
| `limits.placements` | "auto" · "region-pin"[] | yes |  |
| `plan` | "free" · "maker" · "team" · "business" · "sovereign" | yes |  |
| `canEdit` | boolean | yes |  |
| `enforcement` | "preview" | yes |  |
| `note` | string | yes | at least 1 characters |

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}/apps/{appId}/scaling`

Set an app's scaling policy (editors). Checked against the workspace's runs at once. Preview: saved, not applied 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:** editor of the app

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

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

| Field | Type | Required | Notes |
|---|---|---|---|
| `minWarm` | 0 or 1 | yes |  |
| `maxConcurrency` | integer | yes | 1 to 100000 |
| `sleepAfterIdleMin` | 1 or 5 or 15 or 30 or 60 | yes |  |
| `placement` | "auto" · "region-pin" | yes |  |
| `burst` | boolean | yes |  |

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `appId` | string | yes | at least 1 characters |
| `policy` | object | yes |  |
| `policy.minWarm` | 0 or 1 | yes |  |
| `policy.maxConcurrency` | integer | yes | 1 to 100000 |
| `policy.sleepAfterIdleMin` | 1 or 5 or 15 or 30 or 60 | yes |  |
| `policy.placement` | "auto" · "region-pin" | yes |  |
| `policy.burst` | boolean | yes |  |
| `source` | "default" · "custom" | yes |  |
| `defaults` | object | yes |  |
| `defaults.minWarm` | 0 or 1 | yes |  |
| `defaults.maxConcurrency` | integer | yes | 1 to 100000 |
| `defaults.sleepAfterIdleMin` | 1 or 5 or 15 or 30 or 60 | yes |  |
| `defaults.placement` | "auto" · "region-pin" | yes |  |
| `defaults.burst` | boolean | yes |  |
| `limits` | object | yes |  |
| `limits.maxConcurrency` | integer | yes | at least 1 |
| `limits.warmAllowed` | boolean | yes |  |
| `limits.placements` | "auto" · "region-pin"[] | yes |  |
| `plan` | "free" · "maker" · "team" · "business" · "sovereign" | yes |  |
| `canEdit` | boolean | yes |  |
| `enforcement` | "preview" | yes |  |
| `note` | string | yes | at least 1 characters |

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}/infrastructure`

Providers, regions, where this workspace sits and how its apps scale.

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

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `providers` | object[] | yes |  |
| `providers[].id` | "cloudflare" · "aws" · "gcp" · "azure" · "alem-ai" | yes |  |
| `providers[].name` | string | yes | at least 1 characters |
| `providers[].status` | "live" · "deploy-ready" · "planned" | yes |  |
| `providers[].role` | "edge-runtime" · "control-plane" · "cloud" · "ai-cloud" | yes |  |
| `providers[].summary` | string | yes | 1 to 200 characters |
| `regions` | object[] | yes |  |
| `regions[].id` | string | yes |  |
| `regions[].city` | string | yes | at least 1 characters |
| `regions[].country` | string | yes |  |
| `regions[].lat` | number | yes | -90 to 90 |
| `regions[].lon` | number | yes | -180 to 180 |
| `regions[].precision` | "city" · "country" | yes |  |
| `regions[].provider` | "cloudflare" · "aws" · "gcp" · "azure" · "alem-ai" · null or null | yes |  |
| `regions[].role` | "edge" · "control-plane" · "residency-cell" | yes |  |
| `regions[].status` | "live" · "deploy-ready" · "planned" | yes |  |
| `regions[].residency` | string | yes | 1 to 260 characters |
| `placement` | object | yes |  |
| `placement.cell` | "global" · "eu" · "kz" | yes |  |
| `placement.profile` | "global" · "eu" · "kz-standard" · "kz-strict" | yes |  |
| `placement.controlPlaneRegionId` | string | yes |  |
| `placement.runsAt` | "edge" | yes |  |
| `placement.residency` | "planned" | yes |  |
| `scaling` | object | yes |  |
| `scaling.plan` | "free" · "maker" · "team" · "business" · "sovereign" | yes |  |
| `scaling.concurrencyCap` | integer | yes | at least 1 |
| `scaling.defaults` | object | yes |  |
| `scaling.limits` | object | yes |  |
| `scaling.spendCap` | object or null | yes |  |
| `scaling.apps` | object[] | yes |  |

…and 3 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}/residency`

Where this workspace’s data lives: cell, providers, backups, Kazakhstan Planned.

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

**Response 200**

| Field | Type | Required | Notes |
|---|---|---|---|
| `schema` | "qaldy.residency-statement/1" | yes |  |
| `generatedAt` | string (date-time) | yes |  |
| `checkedAt` | string (date) | yes |  |
| `workspace` | object | yes |  |
| `workspace.id` | string | yes | at least 1 characters |
| `workspace.name` | string | yes | at least 1 characters |
| `workspace.cell` | "global" · "eu" · "kz" | yes |  |
| `workspace.profile` | "global" · "eu" · "kz-standard" · "kz-strict" | yes |  |
| `holdsToday` | object | yes |  |
| `holdsToday.regionId` | string | yes |  |
| `holdsToday.city` | string | yes |  |
| `holdsToday.country` | string | yes |  |
| `holdsToday.provider` | string | yes |  |
| `requested` | object | yes |  |
| `requested.cell` | "global" · "eu" · "kz" | yes |  |
| `requested.regionId` | string | yes |  |
| `requested.available` | boolean | yes |  |
| `residency` | object | yes |  |
| `residency.status` | "planned" | yes |  |
| `residency.line` | string | yes | at least 1 characters |
| `data` | object[] | yes |  |
| `data[].id` | "accounts" · "workspace" · "app_code" · "app_data" · "secrets" · "audit" · "runs" · "billing" · … | yes |  |
| `data[].what` | string | yes | 1 to 200 characters |
| `data[].subprocessorId` | "cloudflare" · "aws" · "anthropic" · "resend" · "google" | yes |  |
| `data[].regionId` | string or null | yes |  |
| `data[].personal` | "yes" · "possible" · "no" | yes |  |
| `data[].active` | boolean | yes |  |
| `subprocessors` | object[] | yes |  |
| `subprocessors[].id` | "cloudflare" · "aws" · "anthropic" · "resend" · "google" | yes |  |
| `subprocessors[].name` | string | yes | at least 1 characters |

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