> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simular.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> One conversation per computer on the API channel.

A session is a conversation with Sai on one computer. Every message you send through the API lands in the same session for that computer, so a follow-up message continues the last task's context.

## The API channel

Sai has several channels: the desktop app, the `sai` CLI, messaging integrations and this API. Each channel keeps its own session per computer. A message sent over the API never appears in the desktop app's conversation, and the other way round.

The API's channel is named `api`. Endpoints that read or rotate a session take `channel: "api"`.

## Session ids

`POST /message` returns the `sessionId` its message landed in. You use it to poll `GET /events`. The id stays the same across messages until you start a new session.

## The session's model

Each session runs on one model, `auto` unless you set one. Pass `model` on `POST /message` to change it; the choice is written to the session before the message lands and stays until you pass another. See [Models](/sai-api/api-reference/models).

## Starting fresh

`POST /new-session` with `channel: "api"` rotates the conversation on a computer. The next message starts with no context. See [New session](/sai-api/api-reference/new-session).

## One task at a time

A computer runs one task at a time. If you send a message while Sai is busy, the API accepts it and parks it as a steer for the running task:

```json theme={null}
{ "sessionId": "cs_01HZY", "machineId": "m_7f2a", "queued": true }
```

`queued: true` means the message was folded into the running turn, not started as a new one. Poll the same `sessionId`.

## Status

`GET /events` reports one of four states for the session:

| `status` | Meaning |
| - | - |
| `running` | Sai is working. Keep polling. |
| `needs_approval` | An approval is pending. See [Approvals](/sai-api/concepts/approvals). |
| `idle` | The turn is finished. `text` holds the answer. |
| `error` | The turn failed. The `error` event holds `errorText`. |

## What a caller can see

No screenshots travel over this API. What you get for a task is one progress line per step (the agent's own one-line title for it), the first line of each console message a step printed, and the final `text`. That is the whole record. Sai puts what it sees on the screen into those lines. To watch the computer itself, open the session in the Sai app.

## Reading history

`GET /context?machineId=...&channel=api` returns recent messages from the API session. `GET /sessions?machineId=...&channel=api` lists sessions on a computer. Both default to the CLI's channel when `channel` is omitted, so always pass it.

<Note>
  The `channel` parameter on `/context`, `/sessions` and `/session` is available from October 1.
</Note>