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, kept 3 days.

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

A non-empty object of the provider's own fields, names unchanged, validated against input_schema.

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.

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
required
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
idempotency_key
string | null
required
app
object | null
required
sequence
required