AI Workforce OneHQDocs

Sessions

The sessions running on your AI teams.

List sessions

GET/v1/sessions
Permission sessions:read

The sessions the key's holder can see, narrowed by the key's team restriction.

Query parameters
limitinteger

How many objects to return, 1 to 100. Default 20.

starting_afterstring

Return objects older than this id (the next page).

ending_beforestring

Return objects newer than this id (the previous page).

teamstring

Only sessions of this AI team.

statusstring

Only sessions in this state. One of starting, running, stopped, error.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

A page of sessions.

Other

An RFC 9457 problem.

Get a session

GET/v1/sessions/{session_id}
Permission sessions:read
Path parameters
session_idstringrequired

A session id.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

The session.

Other

An RFC 9457 problem.

Rename a session

PATCH/v1/sessions/{session_id}
Permission sessions:operate

The name only. Who a session belongs to, its mode and its terminal stay in HQ.

Path parameters
session_idstringrequired

A session id.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Body parameters
namestringrequired

Returns a Session object.

Responses
200

The session.

Other

An RFC 9457 problem.

Delete a session

DELETE/v1/sessions/{session_id}
Permission sessions:delete

An org owner or admin only. Stops it if it runs, then deletes it and its schedules.

Path parameters
session_idstringrequired

A session id.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
204

Deleted.

Other

An RFC 9457 problem.

Get a session's token usage

GET/v1/sessions/{session_id}/usage
Permission sessions:read

The newest limit usage samples, returned oldest first.

Path parameters
session_idstringrequired

A session id.

Query parameters
limitinteger

How many objects to return, 1 to 100. Default 20.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

The usage samples.

Other

An RFC 9457 problem.

Create a session

POST/v1/teams/{team_id}/sessions
Permission sessions:create

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

Path parameters
team_idstringrequired

An AI team id.

Headers
Idempotency-Keystringrequired

Required 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, 409 idempotency_in_progress.

HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Body parameters
run_withstringrequired

personal: the user key's own member's login. team_key: the AI team's key. One of personal, team_key.

enginestring

Required on a team that runs both engines. One of claude, codex.

namestring
startboolean
permission_modestring

One of default, acceptEdits, bypassPermissions.

Returns a Session object.

Responses
201

The session, starting (or stopped when start was false).

Other

An RFC 9457 problem.

Start a session

POST/v1/sessions/{session_id}/start
Permission sessions:operate

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

Path parameters
session_idstringrequired

A session id.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
202

The session, starting. Follow GET /sessions/{session_id} or its event stream.

Other

An RFC 9457 problem.

Stop a session

POST/v1/sessions/{session_id}/stop
Permission sessions:operate
Path parameters
session_idstringrequired

A session id.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

The session, stopped.

Other

An RFC 9457 problem.

Restart a session

POST/v1/sessions/{session_id}/restart
Permission sessions:operate

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

Path parameters
session_idstringrequired

A session id.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Body parameters
freshboolean

Start a new conversation instead of resuming the last one.

Returns a Session object.

Responses
202

The session, starting again.

Other

An RFC 9457 problem.

Interrupt the current turn

POST/v1/sessions/{session_id}/interrupt
Permission sessions:type

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

Path parameters
session_idstringrequired

A session id.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
204

Esc was pressed.

Other

An RFC 9457 problem.

List a session's conversation

GET/v1/sessions/{session_id}/items
Permission sessions:chat.read

The 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).

Path parameters
session_idstringrequired

A session id.

Query parameters
afterstring

A cursor from this session (end_cursor, or an event id); return what follows it.

beforestring

A cursor from this session (start_cursor); return what precedes it.

limitinteger

How many objects to return, 1 to 100. Default 20.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

A page of items, oldest first.

Other

An RFC 9457 problem.

Get a tool use's or a thinking block's detail

GET/v1/sessions/{session_id}/items/{item_id}/detail
Permission sessions:chat.read

The masked detail behind an item's detail_ref (256 KiB at most).

Path parameters
session_idstringrequired

A session id.

item_idstringrequired

A session item id.

Query parameters
refstringrequired

The item's detail_ref.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

The detail.

Other

An RFC 9457 problem.

Stream a session's events

GET/v1/sessions/{session_id}/events
Permission sessions:chat.read

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

Path parameters
session_idstringrequired

A session id.

Query parameters
afterstring

A cursor from this session (end_cursor, or an event id); return what follows it.

Headers
Last-Event-IDstring

The id of the last event you received.

HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

The event stream.

Other

An RFC 9457 problem.

Send a message

POST/v1/sessions/{session_id}/messages
Permission sessions:type

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

Path parameters
session_idstringrequired

A session id.

Headers
Idempotency-Keystringrequired

Required 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, 409 idempotency_in_progress.

HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Body parameters
contentarray of objectrequired

Returns a Message object.

Responses
202

Accepted. Delivery continues in the background.

Other

An RFC 9457 problem.

Get a message's delivery state

GET/v1/sessions/{session_id}/messages/{message_id}
Permission sessions:chat.read
Path parameters
session_idstringrequired

A session id.

message_idstringrequired

A message id.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

The message.

Other

An RFC 9457 problem.

Answer a permission, plan or question card

POST/v1/sessions/{session_id}/actions
Permission sessions:type

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

Path parameters
session_idstringrequired

A session id.

Headers
Idempotency-Keystringrequired

Required 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, 409 idempotency_in_progress.

HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Body parameters
instance_idstringrequired
digeststringrequired
intentstring

One of select, toggle, otherText, next, back, review, submit, cancel.

choice_idstring
textstring

Returns a SessionActionResult object.

Responses
200

The answer was applied.

Other

An RFC 9457 problem.

Objects

Session

Attributes
objectstring
idstring
teamstring
namestring
statusstring

Open-ended: starting, running, stopped, error.

enginestring or null
run_withstring or null

personal (the owner's own login) or team_key.

ownerstring or null
permission_modestring
token_countinteger
cost_usdnumber
last_activity_atstring or null
created_atstring or null
created_byUserRef

SessionUsage

Attributes
objectstring
sessionstring
samplesarray of object

SessionItemList

Attributes
objectstringrequired
dataarray of SessionItemrequired
has_morebooleanrequired
start_cursorstring or null
end_cursorstring or null

SessionItemDetail

Attributes
objectstring
kindstring

Open-ended: diff, command, file_list, raw, thinking.

toolstring or null
targetarray of string or null
filesarray of string or null
diffarray of object or null
outputstring or null
errorstring or null
thinkingstring or null
truncatedboolean

Message

A prompt sent over the API. Its text is never stored or returned.

Attributes
objectstring
idstring
sessionstring
statusstring

Open-ended: accepted, queued, typing, submitted, delivered, unconfirmed, blocked_by_moment, failed.

waiting_forstring or null

While queued: wake, ready or moment.

codestring or null

Why it failed, when it did.

text_bytesinteger
image_countinteger
delivered_itemstring or null

The conversation item that proved delivery.

deadline_atstring (date-time)
created_atstring (date-time)
updated_atstring (date-time)

SessionActionResult

Attributes
objectstring
statusstring
digeststring or null

The card's new digest, for a next press on the same card.