API reference

New session

POST /v1/agents/new-session

Starts a fresh conversation on a computer. The next message has no memory of earlier ones.

Request

json

{ "machineId": "m_7f2a", "channel": "api" }

Field	Required	Notes
`machineId`	yes	The computer whose API conversation to rotate.
`channel`	yes for API callers	Send `"api"`. Omitted, it rotates the `sai` CLI's conversation instead.

json

{ "sessionId": "cs_02KQA" }

The next POST /message on this computer lands in this session.

Status	Body
`404`	`{ "error": "Machine not found." }`
`429`	More than 20 new sessions in an hour.

Always send channel: "api". The default exists for the CLI.
You rarely need this. One long conversation per computer is the normal shape; rotate when a new task should not see the old context.
A running task is not stopped by a new session. Call /abort first if you want it stopped.