roasOS
API referenceAgent

Approve an approval

Approve one approval card the run opened, and start the follow-up run that renders it. A run started from a skill or a workflow writes no thread, so there is no card in roasOS for you to press. This is the door that releases that work. It spends on this API key: an `Idempotency-Key` is required, the amount is bounded by the key's per-request ceiling and by its daily and monthly budgets, and `max_credits` / `generation_spend_cap_credits` bound the follow-up run the same way they bound the first one. The follow-up run's text is composed by roasOS from the approved card, never by the caller, and the run id comes back as `follow_up_run_id`. On a batch card, send `drop` with the `index` of each item in `pending_approvals[].items` that must not run. The dropped items do not run and cost nothing, and the per-request ceiling is checked against the kept items only. The list must leave at least one item; to refuse the whole card, decline it. This operation is deliberately absent from the MCP tool list. A connected model may decline; it must never approve its own spend.

POST
/v1/agent-runs/{id}/gates/{gate_id}/approve

Approve one approval card the run opened, and start the follow-up run that renders it.

A run started from a skill or a workflow writes no thread, so there is no card in roasOS for you to press. This is the door that releases that work.

It spends on this API key: an Idempotency-Key is required, the amount is bounded by the key's per-request ceiling and by its daily and monthly budgets, and max_credits / generation_spend_cap_credits bound the follow-up run the same way they bound the first one.

The follow-up run's text is composed by roasOS from the approved card, never by the caller, and the run id comes back as follow_up_run_id.

On a batch card, send drop with the index of each item in pending_approvals[].items that must not run. The dropped items do not run and cost nothing, and the per-request ceiling is checked against the kept items only. The list must leave at least one item; to refuse the whole card, decline it.

This operation is deliberately absent from the MCP tool list. A connected model may decline; it must never approve its own spend.

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
gate_id*string
Formatuuid

Header Parameters

Idempotency-Key*string

A unique string that makes retries safe. Any value 16-255 characters; reuse it only when retrying the exact same request.

Match^[A-Za-z0-9._:-]+$
Length16 <= length <= 255
X-RoasOS-Project?string

Optional label to group this request under one of your projects. Appears in your usage records.

Match^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
Length1 <= length <= 64
X-RoasOS-Cost-Center?string

Optional label to attribute this request to a cost center. Appears in your usage records.

Match^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$
Length1 <= length <= 64

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/agent-runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/gates/497f6eca-6276-4993-bfeb-53cbbbba6f08/approve" \  -H "Idempotency-Key: stringstringstri" \  -H "Content-Type: application/json" \  -d '{}'
{  "data": {    "gate_id": "a33726af-ba3a-459e-a71e-d28211d14ddb",    "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",    "status": "approved",    "decided_at": "2019-08-24T14:15:22Z",    "follow_up_run_id": "f2c9599e-f75d-4fde-a384-e49208b98583"  }}