API reference

Abort

POST /v1/agents/abort

Stops a running task. Safe to call when nothing is running. A turn stopped before it answered ends failed with reason_code: aborted.

Request

Recommended for API callers: name the session you started.

Stop a session's task

curl -s "$SAI_API_URL/v1/agents/abort" \
  -H "Authorization: Bearer $SAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sessionId": "cs_01HZY" }'

Or name the computer and the channel:

Stop the running task on a computercURL

curl -s "$SAI_API_URL/v1/agents/abort" \
  -H "Authorization: Bearer $SAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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 this API key's conversation on this computer for the given `channel`.
`channel`	string	with `machineId`	`api` or `cli`. Omitted, it is `api` for an API key or a Tenant token, `cli` for a signed-in session.

Response

A task was stopped:

200 OK · Task stoppedJSON

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

Nothing to stop:

200 OK · Nothing to stopJSON

{ "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 and no channel, an API key or a Tenant token stops its own api conversation. The sai CLI sends channel: "cli".
Pending approvals on the aborted task are resolved as denied, so nothing is left waiting.