Skip to main content
PATCH
Update Environment

Authorizations

Authorization
string
header
required

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

environment_id
string<uuid>
required

Body

application/json

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.

config
EnvironmentConfig · object | null

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.

example_actions
Example Actions · object[] | null

Replaces the stored example actions. NON-AUTHORITATIVE (never read at turn time). Send [] to clear; null is rejected.

kind
enum<string> | null

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.

Available options:
web,
device,
world
name
string | null
Required string length: 1 - 120
observation_retention
enum<string> | null

Replaces 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.

Available options:
none,
30d,
90d,
indefinite
operating_notes
string | null
Maximum string length: 8000
slug
string | null
Maximum string length: 120

Response

Successful Response

A registered environment as the caller sees it.

address
string | null
required

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.

archived_at
string<date-time> | null
required

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.

config
StoredEnvironmentConfig · object
required

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.

created_at
string<date-time>
required
example_actions
Example Actions · object[]
required
hosting
string
required

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.

id
string<uuid>
required
kind
string
required

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.

name
string
required
observation_retention
string
required

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.

operating_notes
string | null
required
revision
integer
required

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.

slug
string | null
required
updated_at
string<date-time>
required
workspace_id
string<uuid>
required