/api/v1/environments
Create an environment
Accepts a create spec and answers 202 once the create-intent transaction commits
(resource row + idempotency record + initial event + budget reserve in one transaction).
Location points at the status URL; readiness is observed by polling that URL (or via
the events stream), never inferred from 202 itself.
Idempotency: same tenant/actor/method/path/key with the same body replays the stored
result; same key with a different body returns 409 idempotency_conflict. After a
timeout, retry with the same key to recover the intent — do not blind re-create.
startup.onWarmMiss may only tighten the project policy (cold→fail allowed,
fail→cold rejected with 400). A warm miss under fail returns 503
warm_capacity_unavailable; cold is the default fallback. template may carry a
name@sha256:... pin; a digest mismatch is 422 template_unavailable. Operator face:
a principal session is denied 403 (same tenant) / 404 not_owned (cross tenant).
Parameters
| Field | Type | Req | Default | Description |
|---|---|---|---|---|
| string | N | — |
Request Body
| Field | Type | Req | Default | Description |
|---|---|---|---|---|
| projectId | string | Y | — | |
| template | string | Y | — | Official template name, or an immutable `name@sha256:...` pin (mismatch → 422). |
| profile | string (2c4g) | Y | — | Gate A supports the `2c4g` profile only. |
| ttlSeconds | integer | N | 3600 | |
| metadata | object | N | — | |
| env | object | N | — | Secret values are injected only after the environment is bound to the caller's identity; they never enter events or warm templates. |
| startup | object | N | — | |
| └ onWarmMiss | string (cold | fail) | N | — | May only tighten the project policy (cold→fail); loosening is rejected. |