Update Environment Version
Partially update a variant. Omitted fields are untouched.
METADATA (label, description) is editable for the life of the row.
config and example_actions are FROZEN once any session has run
against this version: editing them then would retroactively relabel stored
runs, so the answer is a new version.
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.
Path Parameters
Body
Partial update: an omitted field is left alone.
config and example_actions are FROZEN once any session references
this version (409 environment_version_config_frozen); metadata stays
editable for the life of the row. is_default is not here; the
set-default operation moves it.
The per-kind configuration of an environment.
Every field is optional at the type level and required by KIND at validation time: a web environment needs url, and so on. Unknown keys are REJECTED on write, so a typo surfaces as a 422 instead of a target that was silently never set.
80001 - 120Response
Successful Response
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.