/api/v1/projects/{id}/warm-pool
Apply (or dry-run) a warm-pool policy
If-Match (bare integer revision) and Idempotency-Key are both required. With
dryRun:true the request only validates pricing/quota/budget/limits and returns 200
with an estimate — no write, no reservation, no charge, and no guarantee that a later
apply succeeds. An apply returns 202 with the same status projection; the actual apply
re-runs atomic admission.
Errors: 400 invalid_policy, 402 budget_exhausted, 412 revision_conflict,
429 quota_exceeded, 503 pricing_unavailable (no price configured — retryable,
always with Retry-After) and 503 warm_capacity_unavailable. Shrinking below the
current inventory enters reconciling; only unclaimed inventory is reclaimed, active
environments are never scaled down. Create requests may tighten the project policy
(cold→fail) but never loosen it. The body is REPLACE semantics: policy is the
full WarmPoolPolicy and omitted fields fall back to the server defaults (0 /
cold) — clients must read-merge-write (the SDK type is deliberately NOT widened to
Partial; the CLI patch command merges for you). Operator face: project-kind machine
keys carry no warm-pool:write scope (403); principal sessions are denied.
Parameters
| Field | Type | Req | Default | Description |
|---|---|---|---|---|
| string | N | — | ||
| string | N | — | ||
| string | N | — |
Request Body
| Field | Type | Req | Default | Description |
|---|---|---|---|---|
| policy | object | Y | — | |
| └ minReady | integer | Y | 0 | Target claimable inventory — not total environment concurrency. |
| └ maxReady | integer | Y | 0 | Warm ceiling including provisioning; active environments are separate quota. |
| └ idleRetentionSeconds | integer | Y | 0 | Retention for unclaimed inventory above minReady, from last successful claim. |
| └ dailyBudgetCredits | string | Y | 0 | Non-negative decimal fixed-point UTC-day warm budget. Zero budget forbids warm inventory. |
| └ onMiss | string (cold | fail) | Y | cold | `fail` turns an empty pool into 503 `warm_capacity_unavailable`. |
| dryRun | boolean | N | false | true → 200 estimate only (no write, no reservation, no charge). |