Create Environment Version
Author a declared variant of this environment.
version is assigned server-side as max+1; the caller names the variant
with label. The new version is NOT made default: a fresh variant must
never silently redirect the traffic of callers who pin nothing.
This is the CI operation of the lane (a deploy authors the variant it just
built), so it takes the standard Idempotency-Key header: a retried
pipeline step with the same key and body replays the original version (200
instead of 201) rather than minting label-2. The same key with a different
body is a 409 idempotency_conflict.
Authorizations
Workspace API key as a bearer token: Authorization: Bearer ish_sk_live_.... Keys are workspace-scoped machine principals minted in Settings > Developers (shown once at mint). Scopes: sessions:run (create a session, submit turns, close), sessions:read (read the session and its decision trace), environments:read and environments:write (manage the workspace's registered environments), tasks:read and tasks:write (manage the workspace's registered tasks), people:read and people:write (the people the workspace can run a session for), and usage:read (the workspace's own consumption, spend limits and rate-limit budgets). A key is minted with sessions:run, sessions:read, and tasks:read by default; every other scope must be requested, people:read and usage:read included. An ish user access token also works on the same header for personal scripts.
Headers
Path Parameters
Body
Author a new declared version of an environment.
version is assigned by the server as the next integer; you name the variant with label. is_default is absent on purpose: the default pointer moves only through the set-default operation, so authoring a variant never silently redirects the traffic of callers who pin nothing.
The human handle for this variant, unique per environment case-insensitively. Sessions pin to it by name.
1 - 120REPLACES the environment's config for runs pinned to this version (never merged). Omit to inherit the environment's config.
8000Replaces the environment's example actions for this variant. NON-AUTHORITATIVE: documentation and SDK scaffolding only, never read at turn time. Omit to inherit.
Response
Idempotent replay: the version created by a prior request with this Idempotency-Key and body, returned as is.
A declared variant as the caller sees it.
Set when the variant is archived. An archived version stays readable and comparable so its stored runs keep resolving, is hidden from the default list, refuses new sessions, and frees its label for reuse.
This variant's own config, or null when it inherits the environment's. Replaces (never merges with) the environment's.
The config a run pinned to this version operates under: this version's config when set, otherwise the environment's. Provided so callers never re-implement the replace rule.
Whether a session that names this environment WITHOUT pinning a version resolves here. At most one live default per environment; an environment with no default resolves unversioned.
Monotonic per environment, server-assigned, and never reused, even after the variant is archived.