Update Environment
Partially update an environment. Omitted fields are untouched.
Sessions already opened here are unaffected: they carry a frozen snapshot of the name/kind, exactly so a rename cannot rewrite history.
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
A partial update: an omitted field is left alone.
null is a real value on the nullable fields (slug, operating_notes) where it CLEARS them, so omitting a field and sending it as null mean different things. kind can be changed, but the config is re-validated against the NEW kind, so a switch that leaves the wrong keys behind is a 422 rather than a broken environment.
example_actions cannot be cleared with null; send [] instead. name, kind and config are likewise non-nullable.
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.
Replaces the stored example actions. NON-AUTHORITATIVE (never read at turn time). Send [] to clear; null is rejected.
What kind of surface a registered environment is.
Deliberately not called platform: kind is the one vocabulary the environment object owns, and it stays stable no matter what the thing you are testing calls itself.
Closed on write (an unknown kind is a 422) and OPEN on read: new kinds are added over time, so a client must tolerate a value it does not recognize rather than failing on it.
web, device, world 1 - 120Replaces this environment's retention window: none, 30d, 90d, or indefinite. Omit to leave it unchanged. Applies to sessions opened after this write; already-open sessions and already-stored frames keep the window they were stamped with.
none, 30d, 90d, indefinite 8000120Response
Successful Response
A registered environment as the caller sees it.
Normalized target identity derived from config (scheme, host and path only). A duplicate-registration guard, NOT the environment's identity, since sessions always reference the id.
Set when the environment is archived (DELETE). An archived environment stays readable by id so existing sessions keep resolving, is hidden from the default list, and frees its name for reuse.
The configuration of an environment as stored, tolerant of unknown keys.
Same fields as the write shape, but a key this client does not know is IGNORED rather than rejected: reads must keep working across server versions, and because a list response parses the whole page, one unfamiliar key would otherwise fail an entire workspace listing rather than its own row. Closed on write, open on read.
Who computes the next observation for this environment. Derived from kind and config, never client-set. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.
What kind of surface this is. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.
How long sessions on this environment keep their observation frames: none, 30d, 90d, or indefinite. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.
Increments on every write to this environment's identity or configuration. Usage is aggregated by (id, revision), so a run reports against the configuration it actually ran on. Archiving does not change it.