Sessions and prompts
Start a session, send it a prompt, follow the delivery, answer its questions.
Start a session
curl -X POST https://api-hq.aiworkforceone.com/v1/teams/team_…/sessions \
-H "Authorization: Bearer $HQ_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"Nightly triage","engine":"claude","run_with":"team_key"}'201 with the session and its Location. run_with chooses whose Claude account it runs on:
team_key: the AI team's own key. Needssessions:run_with_team_key.personal: the person a user key acts as signs in with their own account. A service key has no person, so it cannot create one (422 personal_login_not_available).
start, stop, restart, rename (PATCH) and DELETE work like the buttons in HQ.
Send a prompt
curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_…/messages \
-H "Authorization: Bearer $HQ_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"content":[{"type":"text","text":"Summarise the open pull requests"}]}'202 with a message: the prompt's delivery, never its text. HQ types it into the session when
the session is ready, waking a sleeping machine first. Follow it with
GET /v1/sessions/{session_id}/messages/{message_id}, or on the event stream
as session.message.status_changed.
status | Meaning |
|---|---|
accepted, queued | Waiting. waiting_for says what for: wake, ready or moment. |
typing, submitted | Being typed, then sent. |
delivered | It is in the session. delivered_item is its item id. |
blocked_by_moment | The session is asking something first. Answer it, and the prompt goes in. This includes a message from another Claude session that is waiting to be delivered or denied: someone answers it in the session's terminal in HQ. There is no item or action for it in the API yet. |
unconfirmed | It may have been typed, but HQ could not confirm it within 5 minutes. Read the items before sending it again. |
failed | code says why (below). |
Common code values on a failed prompt:
code | Meaning |
|---|---|
login_required | The session is signed out of Claude. Its owner signs in from the session in HQ, then send again. HQ says so as soon as it knows, without waiting out the 5 minutes. |
not_running | The session is stopped. Start it first. |
wake_timeout | The Cloud Computer did not wake within 5 minutes. |
reconnecting | HQ could not reach the running session within 5 minutes. Send again. |
forbidden | The key may no longer type into this session. |
A prompt is typed at most once. HQ never retypes one on its own, so a retry of the same request
with the same Idempotency-Key answers with the same message. The text is typed as written, up to
16 KB, exactly as if it were sent from the chat in HQ.
Answer a question
When the session asks something (a permission, a plan to approve, a multiple-choice question), the
stream sends session.input_required with its instance_id, digest and options. When
answerable_via_api is true, answer with the choice you want:
curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_…/actions \
-H "Authorization: Bearer $HQ_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"instance_id":"…","digest":"…","choice_id":"…"}'digest names the exact question you saw: if the session has moved on, the answer is refused
rather than landing on a different question. Other kinds of prompt stay in HQ.
POST /v1/sessions/{session_id}/interrupt stops what the session is doing, like pressing Esc.
Who may type into a session
| Session | Who may send prompts and answers |
|---|---|
Signed in with a person's own Claude account (personal) | Only a user key of that person. Never another member, an admin, the owner or a service key: it is their account. |
On the AI team's key (team_key) | Any key with sessions:type and sessions:run_with_team_key on that team. |
| Codex | Only a user key of the person signed in. |
Anyone else gets 403 session_not_owned or 403 permission_denied. Reading a session (items,
the stream) follows sessions:chat.read and the team's session visibility.
Read what happened
GET /v1/sessions/{session_id}/items pages through the conversation (after / before cursors).
A tool call or a thinking block carries a detail_ref; pass it to
GET /v1/sessions/{session_id}/items/{item_id}/detail?ref=… for the full, masked detail.