roasOS
API referenceAgent

Cancel an agent run

Ask a run that has not finished to stop. The unused reservation is refunded. A generation the run already started keeps its own lifecycle — cancel that at POST /v1/jobs/{id}/cancel. A run that already finished answers 409 run_not_cancelable.

POST
/v1/agent-runs/{id}/cancel

Ask a run that has not finished to stop. The unused reservation is refunded. A generation the run already started keeps its own lifecycle — cancel that at POST /v1/jobs/{id}/cancel. A run that already finished answers 409 run_not_cancelable.

Authorization

bearerAuth
AuthorizationBearer <token>

API key authentication. Use your API key as the bearer token: Authorization: Bearer roasos_sk_...

In: header

Path Parameters

id*string
Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/agent-runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel"
{  "data": {    "schema_version": "agent-run@1",    "kind": "agent_run",    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "trigger": "chat",    "skill_id": "3cd68bb3-8b7e-48be-8232-1b99b5b4b3aa",    "conversation_id": "cc71b11a-25cd-4c2d-9950-df2cc38e3407",    "max_credits": 0,    "generation_spend_cap_credits": 0,    "pricing_version": "string",    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z",    "status": "quoted",    "credits_reserved": 0,    "credits_max": 0,    "quote_id": "3c071a1d-db86-46a7-9dc8-72ba3fbca992",    "expires_at": "2019-08-24T14:15:22Z",    "authorization": {      "status": "auto_approved"    }  }}

Get agent run events

The ordered lifecycle of one run: accepted, started, tool_called, gate_opened, gate_auto_approved, generation_started, settled, failed, cancelled. A run older than the timeline falls back to the steps its own timestamps can prove.

Decline an approval

Refuse one approval card the run opened, so the work behind it never starts and nothing is charged for it. Approving is a separate operation at `/approve`. It is deliberately absent from the MCP tool list: a connected model may refuse spend, and must never approve its own.