# Sessions and prompts

Start a session, send it a prompt, follow the delivery, answer its questions.



## Start a session [#start-a-session]

```bash
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 [#send-a-prompt]

```bash
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](/docs/api/streaming/)
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 [#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:

```bash
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 [#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 [#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.
