The API channel
Sai has several channels: the desktop app, thesai 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.
Starting fresh
POST /new-session with channel: "api" rotates the conversation on a computer. The next message starts with no context. See 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: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:
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 finaltext. 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.
The
channel parameter on /context, /sessions and /session is available from October 1.