API reference

Abort

POST /v1/agents/abort

Stops a running task. Safe to call when nothing is running.

Request

Recommended for API callers: name the session you started.

json

{ "sessionId": "cs_01HZY" }

Or name the computer and the channel:

json

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

Field	Type	Required	Notes
`sessionId`	string	one of the two	The `sessionId` from `POST /message` or `GET /events`. Must belong to the caller.
`machineId`	string	one of the two	Stops the conversation on this computer for the given `channel`.
`channel`	string	with `machineId`	`api` or `cli`. Omitted, it stops the `sai` CLI's conversation, not yours. Always send `api`.

Response

A task was stopped:

json

{ "ok": true, "aborted": true }

Nothing to stop:

json

{ "ok": true, "aborted": false, "reason": "session already idle or aborting" }

reason is no active session or session already idle or aborting.

Errors

Status	Body
`400`	Neither `sessionId` nor `machineId` was sent.
`403`	`{ "error": "Session not found or does not belong to your account." }`
`404`	`{ "error": "Machine not found or does not belong to your account." }`
`429`	More than 20 aborts in an hour.

Gotchas

Use sessionId. It needs no machine lookup, so it also works on a free account's computer between claims.
With machineId, the default channel is cli. Forgetting channel: "api" reports no active session while your task keeps running.
Pending approvals on the aborted task are resolved as denied, so nothing is left waiting.

Note

sessionId and channel on /abort are available from October 1. Today's staging accepts machineId only and stops the CLI's conversation.