Sessions
The sessions running on your AI teams.
List sessions
/v1/sessionssessions:readThe sessions the key's holder can see, narrowed by the key's team restriction.
limitintegerHow many objects to return, 1 to 100. Default 20.
starting_afterstringReturn objects older than this id (the next page).
ending_beforestringReturn objects newer than this id (the previous page).
teamstringOnly sessions of this AI team.
statusstringOnly sessions in this state. One of
starting,running,stopped,error.
HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a list of Session objects.
200A page of sessions.
OtherAn RFC 9457 problem.
Get a session
/v1/sessions/{session_id}sessions:readsession_idstringrequiredA session id.
HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a Session object.
200The session.
OtherAn RFC 9457 problem.
Rename a session
/v1/sessions/{session_id}sessions:operateThe name only. Who a session belongs to, its mode and its terminal stay in HQ.
session_idstringrequiredA session id.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
namestringrequired
Returns a Session object.
200The session.
OtherAn RFC 9457 problem.
Delete a session
/v1/sessions/{session_id}sessions:deleteAn org owner or admin only. Stops it if it runs, then deletes it and its schedules.
session_idstringrequiredA session id.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
204Deleted.
OtherAn RFC 9457 problem.
Get a session's token usage
/v1/sessions/{session_id}/usagesessions:readThe newest limit usage samples, returned oldest first.
session_idstringrequiredA session id.
limitintegerHow many objects to return, 1 to 100. Default 20.
HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a SessionUsage object.
200The usage samples.
OtherAn RFC 9457 problem.
Create a session
/v1/teams/{team_id}/sessionssessions:createCreates a session on the AI team and, unless start is false, starts it. run_with: "personal" binds the member the user key acts as (their own Claude or ChatGPT login); a
service key cannot (422 personal_login_not_available). run_with: "team_key" also needs
sessions:run_with_team_key on the team. The plan's session limit applies. When the AI
team is paused, a start answers 409 workspace_paused, and while its Cloud Computer is
being updated or resized, 409 workspace_updating; while it is too busy for another
session, 409 machine_busy (either way the session is created, stopped). Requires an
Idempotency-Key.
On an AI team that turned on Protected files, a Codex session (named, or the team's only engine) needs files:protected.read and files:protected.write on the key and its person: 403 protected_files_shell otherwise.
team_idstringrequiredAn AI team id.
Idempotency-KeystringrequiredRequired here. The same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422; while the first request is still running, 409idempotency_in_progress.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
run_withstringrequiredpersonal: the user key's own member's login. team_key: the AI team's key. One of
personal,team_key.enginestringRequired on a team that runs both engines. One of
claude,codex.namestringstartbooleanpermission_modestringOne of
default,acceptEdits,bypassPermissions.
Returns a Session object.
201The session, starting (or stopped when
startwas false).OtherAn RFC 9457 problem.
Start a session
/v1/sessions/{session_id}/startsessions:operateStarts a stopped session. Its owner, or an org owner or admin, may start it. A service key
never starts an unclaimed personal-login session (starting it would bind a login). When the
AI team is paused, the answer is 409 workspace_paused; while its Cloud Computer is being
updated or resized, 409 workspace_updating; while it is too busy for another session,
409 machine_busy.
On an AI team that turned on Protected files, a Codex session start needs files:protected.read and files:protected.write on the key and its person: 403 protected_files_shell otherwise.
session_idstringrequiredA session id.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a Session object.
202The session, starting. Follow
GET /sessions/{session_id}or its event stream.OtherAn RFC 9457 problem.
Stop a session
/v1/sessions/{session_id}/stopsessions:operatesession_idstringrequiredA session id.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a Session object.
200The session, stopped.
OtherAn RFC 9457 problem.
Restart a session
/v1/sessions/{session_id}/restartsessions:operateStops and starts the session. fresh starts a new conversation instead of resuming. When
the AI team is paused, the answer is 409 workspace_paused; while its Cloud Computer is
being updated or resized, 409 workspace_updating; while it is too busy for another
session, 409 machine_busy. Either way a running session keeps running.
On an AI team that turned on Protected files, a Codex session restart needs files:protected.read and files:protected.write on the key and its person: 403 protected_files_shell otherwise.
session_idstringrequiredA session id.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
freshbooleanStart a new conversation instead of resuming the last one.
Returns a Session object.
202The session, starting again.
OtherAn RFC 9457 problem.
Interrupt the current turn
/v1/sessions/{session_id}/interruptsessions:typePresses Esc in the session, as the Chat view's Stop button does. The same keyboard rule as
sending a message applies. While Claude is holding a message from another session, Esc
would decline it: the answer is 409 held_peer_message and nothing is pressed. Deliver or
deny the message in the session in HQ, then interrupt again.
session_idstringrequiredA session id.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
204Esc was pressed.
OtherAn RFC 9457 problem.
List a session's conversation
/v1/sessions/{session_id}/itemssessions:chat.readThe conversation as HQ's Chat view shows it: messages, tool uses, thinking markers and
notices, masked. Newest page by default; page with the start_cursor / end_cursor the
response returns. Never wakes a sleeping machine (409 while it sleeps).
session_idstringrequiredA session id.
afterstringA cursor from this session (
end_cursor, or an eventid); return what follows it.beforestringA cursor from this session (
start_cursor); return what precedes it.limitintegerHow many objects to return, 1 to 100. Default 20.
HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a SessionItemList object.
200A page of items, oldest first.
OtherAn RFC 9457 problem.
Get a tool use's or a thinking block's detail
/v1/sessions/{session_id}/items/{item_id}/detailsessions:chat.readThe masked detail behind an item's detail_ref (256 KiB at most).
session_idstringrequiredA session id.
item_idstringrequiredA session item id.
refstringrequiredThe item's
detail_ref.
HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a SessionItemDetail object.
200The detail.
OtherAn RFC 9457 problem.
Stream a session's events
/v1/sessions/{session_id}/eventssessions:chat.readServer-Sent Events: session.message.completed, session.tool_use.started|completed|failed,
session.thinking.completed, session.notice, session.status, session.input_required,
session.turn.completed and session.message.status_changed, each a JSON event envelope.
Reconnect with Last-Event-ID to resume without a gap. : ping every 15 s; stream.rotate
at 50 minutes (reconnect); stream.reset when you fell behind (list the items, then
reconnect). A stream never wakes the machine. At most 4 streams per session.
session_idstringrequiredA session id.
afterstringA cursor from this session (
end_cursor, or an eventid); return what follows it.
Last-Event-IDstringThe
idof the last event you received.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
200The event stream.
OtherAn RFC 9457 problem.
Send a message
/v1/sessions/{session_id}/messagessessions:typeSends a prompt to a running session; follow session.message.status_changed on the event
stream, or this message. A personal-login session accepts messages only from its owner's own
user key (403 session_not_owned for anyone else); a team-key session needs
sessions:run_with_team_key. A sleeping machine is woken (waiting_for: "wake"). A prompt
is typed at most once. Requires an Idempotency-Key.
session_idstringrequiredA session id.
Idempotency-KeystringrequiredRequired here. The same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422; while the first request is still running, 409idempotency_in_progress.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
contentarray of objectrequired
Returns a Message object.
202Accepted. Delivery continues in the background.
OtherAn RFC 9457 problem.
Get a message's delivery state
/v1/sessions/{session_id}/messages/{message_id}sessions:chat.readsession_idstringrequiredA session id.
message_idstringrequiredA message id.
HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a Message object.
200The message.
OtherAn RFC 9457 problem.
Answer a permission, plan or question card
/v1/sessions/{session_id}/actionssessions:typeAnswers the card a session.input_required event announced (answerable_via_api: true),
naming its instance_id and digest. The server re-reads the screen and types only the
recorded keys for the choice. The keyboard rule of messages applies. Requires an
Idempotency-Key.
session_idstringrequiredA session id.
Idempotency-KeystringrequiredRequired here. The same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422; while the first request is still running, 409idempotency_in_progress.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
instance_idstringrequireddigeststringrequiredintentstringOne of
select,toggle,otherText,next,back,review,submit,cancel.choice_idstringtextstring
Returns a SessionActionResult object.
200The answer was applied.
OtherAn RFC 9457 problem.
Objects
Session
objectstringidstringteamstringnamestringstatusstringOpen-ended: starting, running, stopped, error.
enginestring or nullrun_withstring or nullpersonal (the owner's own login) or team_key.
ownerstring or nullpermission_modestringtoken_countintegercost_usdnumberlast_activity_atstring or nullcreated_atstring or nullcreated_byUserRef
SessionUsage
objectstringsessionstringsamplesarray of object
SessionItemList
objectstringrequireddataarray of SessionItemrequiredhas_morebooleanrequiredstart_cursorstring or nullend_cursorstring or null
SessionItemDetail
objectstringkindstringOpen-ended: diff, command, file_list, raw, thinking.
toolstring or nulltargetarray of string or nullfilesarray of string or nulldiffarray of object or nulloutputstring or nullerrorstring or nullthinkingstring or nulltruncatedboolean
Message
A prompt sent over the API. Its text is never stored or returned.
objectstringidstringsessionstringstatusstringOpen-ended: accepted, queued, typing, submitted, delivered, unconfirmed, blocked_by_moment, failed.
waiting_forstring or nullWhile queued: wake, ready or moment.
codestring or nullWhy it failed, when it did.
text_bytesintegerimage_countintegerdelivered_itemstring or nullThe conversation item that proved delivery.
deadline_atstring (date-time)created_atstring (date-time)updated_atstring (date-time)
SessionActionResult
objectstringstatusstringdigeststring or nullThe card's new digest, for a next press on the same card.