AI Workforce OneHQDocs

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. Needs sessions: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.

statusMeaning
accepted, queuedWaiting. waiting_for says what for: wake, ready or moment.
typing, submittedBeing typed, then sent.
deliveredIt is in the session. delivered_item is its item id.
blocked_by_momentThe 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.
unconfirmedIt may have been typed, but HQ could not confirm it within 5 minutes. Read the items before sending it again.
failedcode says why (below).

Common code values on a failed prompt:

codeMeaning
login_requiredThe 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_runningThe session is stopped. Start it first.
wake_timeoutThe Cloud Computer did not wake within 5 minutes.
reconnectingHQ could not reach the running session within 5 minutes. Send again.
forbiddenThe 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

SessionWho 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.
CodexOnly 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.