roasOS
API referenceWorkflows

Make statics

Turn one product into a set of static ads. Send the `product_id` the ads must sell. Add `brief` to steer the angle, `variants` to render more than three takes, `aspect_ratio` to pick the frame, `lane` to choose how the image is built, and `avatar_id` to put your own person in the picture. The two lanes differ in how the product reaches the canvas. `scene` renders the whole static in one call. `product` places your product kit's verified cutout into the scene, which holds the product's shape and label exactly. The headline, the sub-head and the call to action are rendered **by the image model** from exact strings, with your logo passed as a reference and your brand colours passed as hex values. Read that limit before you build on it: the model cannot guarantee your exact typeface, and a wrong glyph is a regenerate, not a refund. This is the typed door onto the `roasos:statics-factory` skill, so it is an agent run and not a job. `generation_spend_cap_credits` is what lets the run render without asking a person; it defaults to 0, so a statics call you say nothing about quotes the work and waits. `variants` stops at 8, because that is how many quotes one approval card can carry. Send `quote_only: true` to see the ceiling for free, then send the same body with the returned `quote_id`. Read the run at `/v1/agent-runs/{id}`. Anything the run could not auto-approve waits in `pending_approvals`; release it at `/v1/agent-runs/{id}/gates/{gate_id}/approve`.

POST
/v1/workflows/statics

Turn one product into a set of static ads.

Send the product_id the ads must sell. Add brief to steer the angle, variants to render more than three takes, aspect_ratio to pick the frame, lane to choose how the image is built, and avatar_id to put your own person in the picture.

The two lanes differ in how the product reaches the canvas. scene renders the whole static in one call. product places your product kit's verified cutout into the scene, which holds the product's shape and label exactly.

The headline, the sub-head and the call to action are rendered by the image model from exact strings, with your logo passed as a reference and your brand colours passed as hex values. Read that limit before you build on it: the model cannot guarantee your exact typeface, and a wrong glyph is a regenerate, not a refund.

This is the typed door onto the roasos:statics-factory skill, so it is an agent run and not a job. generation_spend_cap_credits is what lets the run render without asking a person; it defaults to 0, so a statics call you say nothing about quotes the work and waits. variants stops at 8, because that is how many quotes one approval card can carry. Send quote_only: true to see the ceiling for free, then send the same body with the returned quote_id.

Read the run at /v1/agent-runs/{id}. Anything the run could not auto-approve waits in pending_approvals; release it at /v1/agent-runs/{id}/gates/{gate_id}/approve.

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

application/json

application/json

curl -X POST "https://example.com/v1/workflows/statics" \  -H "Idempotency-Key: stringstringstri" \  -H "Content-Type: application/json" \  -d '{    "product_id": "0d012afa-f885-4e65-aeca-37e27701e2d1"  }'
{  "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"    }  }}

Remix an ad

Analyze one ad, storyboard the same structure with your own product and person, and render it. Send exactly one source (`ad_url`, `discover_item_id` or `source_generation_id`) and the `product_id` the remix must sell. Add `avatar_id` to cast your own person, `variants` to render two takes instead of one, and `note` to steer it. `discover_item_id` is how a Discover creative enters a remix: it is the analysis source, and it is the only field that admits one. The same creative sent as `ad_url`, or reached through `source_generation_id`, is refused with `discover_source_not_allowed` — a competitor ad is something you read and re-create, never something you edit. This is the typed door onto the `roasos:remix-ad` skill, so it is an agent run and not a job. `generation_spend_cap_credits` is what lets the run render without asking a person; it defaults to 0, so a remix you say nothing about quotes the board and waits. Send `quote_only: true` to see the ceiling for free, then send the same body with the returned `quote_id`. Read the run at `/v1/agent-runs/{id}`. Anything the run could not auto-approve waits in `pending_approvals`; release it at `/v1/agent-runs/{id}/gates/{gate_id}/approve`.

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}`.