Skip to main content
POST
Start one run: 202 with the queued run (async models), 200 with the finished run (sync tools).

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string

Recommended. 1–255 printable ASCII characters, scoped to the API key; replays its run for 24 hours.

HTTP-Referer
string

Optional app attribution: your app's URL; only its origin counts. Without it the run is not attributed.

X-Spiral-Title
string

Optional. Your app's display name, 1–64 printable characters. Needs HTTP-Referer.

X-Spiral-Categories
string

Optional. Up to 2 comma-separated app categories from the documented list. Needs HTTP-Referer.

X-Spiral-App-Visibility
string

Optional. hidden keeps a new app out of public rankings. Needs HTTP-Referer.

Body

application/json
provider
string
required

Provider id from GET /v1/providers.

Minimum string length: 1
model
string
required

The provider's model id or tool operation (catalog id).

Minimum string length: 1
input
object
required

An object of the provider's own fields, names unchanged, validated against input_schema; it needs at least one field unless the schema names none.

webhook
object

A public https URL that receives this run's terminal event, signed with the org's webhook signing secret; without it no webhook is sent (poll the run). A private or local host is refused.

metadata
object

Echoed on the run; at most intake.max_metadata_bytes as JSON.

end_user_id
string

The end user this run is for, as the caller names them (ADR 0143). Echoed on the run; reads given the same end_user_id find only that end user's runs.

Pattern: ^[\x21-\x7E]{1,128}$

Response

A sync tool's finished run (or the replay of one).

id
string<uuid>
required
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
object
string
required
Allowed value: "run"
status
enum<string>
required
Available options:
queued,
running,
completed,
failed,
canceled
provider
string
required
model
string
required
output
object | null
required
usage
object | null
required
cost
object | null
required

The run's cost in USD. Null for an API key Spiral set to the customer price view (ADR 0145), whose answers state no USD amount.

charge_reason
enum<string> | null
required
Available options:
provider_billed_failure,
provider_billed_cancel
timings
object
required
error
object | null
required
metadata
object | null
required
end_user_id
string | null
required
idempotency_key
string | null
required
app
object | null
required
sequence
required
customer_cost
object | null

Only for an API key in the customer price view (ADR 0145), in place of cost: the run's cost in the organization's own unit, as cost.customer_price with the cost's state; null when the run has no customer price. Absent for every other key.