roasOS
API referenceAgent

Ask the agent

Start one agent run without a browser. The agent plans, calls tools, and can start paid generations on its own up to the cap you set. Two caps govern the run and neither replaces the other. `max_credits` bounds what the run's own thinking may cost. `generation_spend_cap_credits` bounds what the run may spend on renders, voices and other paid work without asking a person — it defaults to 0, so a run you say nothing about can never charge you for a render. Both caps are bounded again by this API key's own spend policy, and the policy always wins. Send `quote_only: true` to see the ceiling for free; the ceiling is `max_credits + generation_spend_cap_credits`. Send the same body with the returned `quote_id` to run it. Confirming reserves the ceiling, and the unused part is refunded when the run ends, so you are never charged more than the number you saw. The run is asynchronous: read it at `/v1/agent-runs/{id}`. Anything the run could not auto-approve waits as a card in `pending_approvals`; approve it in roasOS, or decline it here.

POST
/v1/agent/completions

Start one agent run without a browser. The agent plans, calls tools, and can start paid generations on its own up to the cap you set.

Two caps govern the run and neither replaces the other. max_credits bounds what the run's own thinking may cost. generation_spend_cap_credits bounds what the run may spend on renders, voices and other paid work without asking a person — it defaults to 0, so a run you say nothing about can never charge you for a render. Both caps are bounded again by this API key's own spend policy, and the policy always wins.

Send quote_only: true to see the ceiling for free; the ceiling is max_credits + generation_spend_cap_credits. Send the same body with the returned quote_id to run it. Confirming reserves the ceiling, and the unused part is refunded when the run ends, so you are never charged more than the number you saw.

The run is asynchronous: read it at /v1/agent-runs/{id}. Anything the run could not auto-approve waits as a card in pending_approvals; approve it in roasOS, or decline it here.

Authorization

bearerAuth
AuthorizationBearer <token>

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

In: header

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

application/json

curl -X POST "https://example.com/v1/agent/completions" \  -H "Idempotency-Key: stringstringstri" \  -H "Content-Type: application/json" \  -d '{    "text": "string"  }'
{  "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"    }  }}

Extract a brand

Read one brand from its own website and keep what you find. roasOS renders the homepage, discovers the rest of the site through its sitemap and its own links, reads up to twelve pages, and returns one structured profile: the products, the offer, the promise, the proof, the customers it talks to and the way it talks. Every field carries a confidence label — `stated` when the site says it, `inferred` when the model concluded it, and `verified` only when a reviews page backs it up. Send the site as `website_url`. Every crawl bound is ours: twelve pages, eight seconds a page, one minute for the whole crawl, and `robots.txt` is honoured. A site that says stay out is not read. It costs 2 credits. Set `quote_only: true` to see the price for free, then send the same body with the returned `quote_id` to run it. An extraction this workspace already ran in the last seven days is a cache hit and costs nothing. The run is asynchronous and is read where every analysis is read: `/v1/workflows/analyses/{id}`.

Get an agent run

Read one run: what started it, its caps, the approvals it is waiting on, and — once it is terminal — what it cost. Every brain run is read here: an ask, a skill run, a routine run.