Close Session
Close an open session and return it (idempotent on an already-closed one).
A POST on a /close subresource rather than DELETE /sessions/{id}:
closing is a state TRANSITION that settles the session’s turns and leaves a
readable record, not a removal. DELETE promised an erasure this route never
performed, and it had no honest way to return the closed session’s body.
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
Response
Successful Response
The full session, without its decision trace.
What create and close return: a caller that opened a session holds the same object a read would give it, so nothing has to be fetched twice to learn what was actually frozen. The TRACE is deliberately absent: turns are a paged subresource of the detail read, and a create has none yet.
This session's spend in credits (0 if it had no billable turns).
direct, intent When the session left open (UTC), stamped on the first terminal transition and never moved. Null while the session is open. This is the timestamp sessions_ended usage buckets on.
Why the session ended, when that is finer than status: credits_exhausted or plan_allowance_exhausted (both end the session as balance_exhausted), or spend_cap_reached. Null for an ordinary ending. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.
The environment as frozen at create (name + kind snapshot).
Session status. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.
open, completed, gave_up, closed, max_turns, spend_cap_reached, balance_exhausted The session's intent, frozen when it was created. A later edit to a registered task never changes it.
Retention window resolved at open: none, 30d, 90d, or indefinite. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.
pause_on_decide, frame_on_demand, free_running The person as they were when the session was created, frozen onto the session.
This, not the live person, is what the session was run against: it stays readable and unchanged after the person is edited or deleted, which is what makes an old trace still mean something. id is the person's id at create time.
Additional keys may be present and more may be added over time; treat anything not listed here as unspecified rather than failing on it.
Deliberation budget the session was opened with: low, medium or high. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.