> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a run ## OpenAPI ````yaml api-reference/openapi.json POST /v1/runs openapi: 3.1.0 info: title: Spiral API version: '1' description: >- 1. Retry automatically only on network errors and timeouts (same `Idempotency-Key`) and on the codes below. `retryable` and `x-should-retry` on the answer always win over this table (for example `RATE_LIMITED` is not retryable once the `day` policy is exhausted). Every other code needs a change before the request is sent again. | Code | HTTP | Retry | Wait | |---|---|---|---| | INSUFFICIENT_BALANCE | 402 | only when the problem says `retryable: true`, with the same `Idempotency-Key` | `Retry-After` (30 s by default) | | IDEMPOTENCY_IN_PROGRESS | 409 | yes, with the same `Idempotency-Key` | `Retry-After` (1 s by default) | | RATE_LIMITED | 429 | yes | `Retry-After` | | CONCURRENCY_LIMITED | 429 | yes | `Retry-After` (2 s by default) | | QUEUE_FULL | 429 | yes | `Retry-After` (2 s by default) | | INTERNAL_ERROR | 500 | yes, with the same `Idempotency-Key` | backoff (rule 2) | | BILLING_UNAVAILABLE | 503 | yes, with the same `Idempotency-Key` | `Retry-After` (5 s by default) | | SCHEMA_UNAVAILABLE | 503 | yes | `Retry-After` (10 s by default) | | PROVIDER_PAUSED | 503 | yes | `Retry-After` (60 s by default) | | MODEL_PAUSED | 503 | yes | `Retry-After` (60 s by default) | | SERVICE_UNAVAILABLE | 503 | yes, with the same `Idempotency-Key` | `Retry-After` (5 s by default) | 2. Backoff: capped exponential with full jitter, `sleep = random(0, min(30 s, 1 s × 2^attempt))`, at most 4 retries and about 2 minutes in total for a create. 3. Retry-After is a floor: wait at least that long (add 0–20 % jitter). Magica never sends more than 60 s. 4. Keys: send a UUIDv4 `Idempotency-Key` on every `POST /v1/runs` and store it with your task before sending. Reuse it for every retry of the same intent, including after a restart; a replay returns the original run with `Idempotent-Replayed: true`, never a second run or charge. Use a new key only to start a new run deliberately. A key is remembered for 3 days, then may start a new run. 5. Unknown outcome of a create (timeout, connection reset): retry with the same key. Never switch to a new key until the first request is known not to have created a run. 6. Failed runs: start at most one new run (new key), and only when `error.retryable` is true. `PROVIDER_OUTCOME_UNKNOWN` is not retryable: check your own results first, because the provider may have done the work. 7. Polling: prefer webhooks. Otherwise use `GET /v1/runs/{id}?wait_seconds=30`, or poll by `Retry-After` on 202 and running responses; without it start at 1 s (search and scrape), 2 s (images), 5 s (video and audio), back off × 1.5 up to 30 s, and stop at a final status. Polling has its own rate-limit policy (`poll`), so it never consumes create quota. 8. Webhooks: verify the signature over the raw body with your org's signing secret (any Standard Webhooks library; during a secret rotation the header carries two signatures and either verifies); answer 2xx fast and do the work afterwards (a delivery that takes over 10 s is re-sent); ignore event types you do not handle (types are added over time); dedupe on `webhook-id` for at least 7 days (every re-send carries the same one); on `truncated: true` read the run with `GET /v1/runs/{id}` (the body left out `output` to stay under receiver limits); ignore a delivery whose run `sequence` is lower than one already applied; download outputs within 24 hours. A webhook is sent right after the run is charged, so it usually carries the final charge (`sequence` 4); when the provider's bill comes later it carries `cost.state: held` (`sequence` 3) and the final charge is on `GET /v1/runs/{id}` (`sequence` 4). No separate billing event is sent. 9. Runs cannot be canceled after submission. Poll the run or wait for its configured terminal webhook. servers: - url: https://api.spiral.ai security: [] paths: /v1/runs: post: tags: - Runs summary: >- Start one run: 202 with the queued run (async models), 200 with the finished run (sync tools). operationId: post-runs parameters: - name: Idempotency-Key in: header required: false description: >- Recommended. 1–255 printable ASCII characters, scoped to the API key, kept 3 days. schema: type: string - name: HTTP-Referer in: header required: false description: >- Optional app attribution: your app's URL; only its origin counts. Without it the run is not attributed. schema: type: string - name: X-Spiral-Title in: header required: false description: >- Optional. Your app's display name, 1–64 printable characters. Needs HTTP-Referer. schema: type: string - name: X-Spiral-Categories in: header required: false description: >- Optional. Up to 2 comma-separated app categories from the documented list. Needs HTTP-Referer. schema: type: string - name: X-Spiral-App-Visibility in: header required: false description: >- Optional. `hidden` keeps a new app out of public rankings. Needs HTTP-Referer. schema: type: string requestBody: required: true content: application/json: schema: type: object properties: provider: type: string minLength: 1 description: Provider id from `GET /v1/providers`. model: type: string minLength: 1 description: The provider's model id or tool operation (catalog id). input: type: object propertyNames: type: string additionalProperties: {} description: >- A non-empty object of the provider's own fields, names unchanged, validated against `input_schema`. webhook: description: >- 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. type: object properties: url: type: string format: uri pattern: ^https:// required: - url additionalProperties: false metadata: description: >- Echoed on the run; at most `intake.max_metadata_bytes` as JSON. type: object propertyNames: type: string additionalProperties: {} required: - provider - model - input additionalProperties: false responses: '200': description: A sync tool's finished run (or the replay of one). headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' Idempotent-Replayed: $ref: '#/components/headers/Idempotent-Replayed' Cache-Control: $ref: '#/components/headers/Cache-Control' Deprecation: $ref: '#/components/headers/Deprecation' Sunset: $ref: '#/components/headers/Sunset' content: application/json: schema: type: object properties: id: type: string format: uuid 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: type: string const: run status: type: string enum: - queued - running - completed - failed - canceled provider: type: string model: type: string output: anyOf: - type: object properties: items: type: array items: type: object properties: type: type: string enum: - image - video - audio - text - json - 3d url: type: string format: uri mime_type: type: string size_bytes: type: integer minimum: -9007199254740991 maximum: 9007199254740991 width: type: integer minimum: -9007199254740991 maximum: 9007199254740991 height: type: integer minimum: -9007199254740991 maximum: 9007199254740991 duration_seconds: type: number kind: type: string data: {} expires_at: type: string description: RFC 3339 timestamp field: type: string source: type: string const: provider notice: type: string error: type: object properties: code: type: string enum: - OUTPUT_UNAVAILABLE - OUTPUT_TOO_LARGE message: type: string required: - code - message required: - type expired: type: boolean dropped_count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - items - expired - type: 'null' usage: anyOf: - type: object properties: units: type: array items: type: object properties: unit: type: string quantity: type: number required: - unit - quantity required: - units - type: 'null' cost: type: object properties: currency: type: string const: USD state: type: string enum: - held - settled - released estimated: type: object properties: amount: type: string amount_micros: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - amount - amount_micros charged: anyOf: - type: object properties: amount: type: string amount_micros: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - amount - amount_micros - type: 'null' required: - currency - state - estimated - charged charge_reason: anyOf: - type: string enum: - provider_billed_failure - provider_billed_cancel - type: 'null' timings: type: object properties: created_at: type: string description: RFC 3339 timestamp started_at: anyOf: - type: string description: RFC 3339 timestamp - type: 'null' completed_at: anyOf: - type: string description: RFC 3339 timestamp - type: 'null' required: - created_at - started_at - completed_at error: anyOf: - type: object properties: code: type: string message: type: string retryable: type: boolean errors: type: array items: type: object properties: pointer: type: string message: type: string reason: type: string enum: - unknown_field - missing_required - wrong_type - not_in_enum - below_minimum - above_maximum - not_multiple_of - too_short - too_long - too_few_items - too_many_items - pattern_mismatch - invalid_format - no_matching_variant - invalid_combination - control_field - invalid_value - file_too_large - unsupported_media_type - duration_too_long - duration_too_short - resolution_too_low - resolution_too_high - unreachable - file_not_found - content_policy - provider_refused expected: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object propertyNames: type: string additionalProperties: type: - string - number - boolean - 'null' received: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object propertyNames: type: string additionalProperties: type: - string - number - boolean - 'null' allowed: type: array items: type: - string - number - boolean - 'null' required: - pointer - message required: - code - message - retryable - type: 'null' metadata: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' idempotency_key: type: - string - 'null' app: anyOf: - type: object properties: id: type: string url: type: string title: type: - string - 'null' required: - id - url - title - type: 'null' sequence: anyOf: - type: number const: 1 - type: number const: 2 - type: number const: 3 - type: number const: 4 links: type: object properties: self: type: string required: - self required: - id - object - status - provider - model - output - usage - cost - charge_reason - timings - error - metadata - idempotency_key - app - sequence - links '202': description: The queued run (or the replay of an async run). headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' Location: $ref: '#/components/headers/Location' Retry-After: $ref: '#/components/headers/Retry-After' Idempotent-Replayed: $ref: '#/components/headers/Idempotent-Replayed' Cache-Control: $ref: '#/components/headers/Cache-Control' Deprecation: $ref: '#/components/headers/Deprecation' Sunset: $ref: '#/components/headers/Sunset' content: application/json: schema: type: object properties: id: type: string format: uuid 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: type: string const: run status: type: string enum: - queued - running - completed - failed - canceled provider: type: string model: type: string output: anyOf: - type: object properties: items: type: array items: type: object properties: type: type: string enum: - image - video - audio - text - json - 3d url: type: string format: uri mime_type: type: string size_bytes: type: integer minimum: -9007199254740991 maximum: 9007199254740991 width: type: integer minimum: -9007199254740991 maximum: 9007199254740991 height: type: integer minimum: -9007199254740991 maximum: 9007199254740991 duration_seconds: type: number kind: type: string data: {} expires_at: type: string description: RFC 3339 timestamp field: type: string source: type: string const: provider notice: type: string error: type: object properties: code: type: string enum: - OUTPUT_UNAVAILABLE - OUTPUT_TOO_LARGE message: type: string required: - code - message required: - type expired: type: boolean dropped_count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - items - expired - type: 'null' usage: anyOf: - type: object properties: units: type: array items: type: object properties: unit: type: string quantity: type: number required: - unit - quantity required: - units - type: 'null' cost: type: object properties: currency: type: string const: USD state: type: string enum: - held - settled - released estimated: type: object properties: amount: type: string amount_micros: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - amount - amount_micros charged: anyOf: - type: object properties: amount: type: string amount_micros: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - amount - amount_micros - type: 'null' required: - currency - state - estimated - charged charge_reason: anyOf: - type: string enum: - provider_billed_failure - provider_billed_cancel - type: 'null' timings: type: object properties: created_at: type: string description: RFC 3339 timestamp started_at: anyOf: - type: string description: RFC 3339 timestamp - type: 'null' completed_at: anyOf: - type: string description: RFC 3339 timestamp - type: 'null' required: - created_at - started_at - completed_at error: anyOf: - type: object properties: code: type: string message: type: string retryable: type: boolean errors: type: array items: type: object properties: pointer: type: string message: type: string reason: type: string enum: - unknown_field - missing_required - wrong_type - not_in_enum - below_minimum - above_maximum - not_multiple_of - too_short - too_long - too_few_items - too_many_items - pattern_mismatch - invalid_format - no_matching_variant - invalid_combination - control_field - invalid_value - file_too_large - unsupported_media_type - duration_too_long - duration_too_short - resolution_too_low - resolution_too_high - unreachable - file_not_found - content_policy - provider_refused expected: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object propertyNames: type: string additionalProperties: type: - string - number - boolean - 'null' received: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object propertyNames: type: string additionalProperties: type: - string - number - boolean - 'null' allowed: type: array items: type: - string - number - boolean - 'null' required: - pointer - message required: - code - message - retryable - type: 'null' metadata: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' idempotency_key: type: - string - 'null' app: anyOf: - type: object properties: id: type: string url: type: string title: type: - string - 'null' required: - id - url - title - type: 'null' sequence: anyOf: - type: number const: 1 - type: number const: 2 - type: number const: 3 - type: number const: 4 links: type: object properties: self: type: string required: - self required: - id - object - status - provider - model - output - usage - cost - charge_reason - timings - error - metadata - idempotency_key - app - sequence - links '400': description: >- Problem: INVALID_JSON, INVALID_REQUEST, INVALID_INPUT, INVALID_HEADER. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '401': description: 'Problem: UNAUTHENTICATED, API_KEY_REVOKED, API_KEY_EXPIRED.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '402': description: 'Problem: INSUFFICIENT_BALANCE, SPEND_LIMIT_REACHED.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' Retry-After: $ref: '#/components/headers/Retry-After' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '403': description: >- Problem: PROVIDER_DISABLED_BY_ORG, MODEL_DISABLED_BY_ORG, ORG_SUSPENDED, PERMISSION_DENIED. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '404': description: 'Problem: PROVIDER_NOT_FOUND, MODEL_NOT_FOUND, FILE_NOT_FOUND.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '405': description: 'Problem: METHOD_NOT_ALLOWED.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' Allow: $ref: '#/components/headers/Allow' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '409': description: 'Problem: IDEMPOTENCY_IN_PROGRESS.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' Retry-After: $ref: '#/components/headers/Retry-After' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '410': description: 'Problem: MODEL_RETIRED.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '413': description: 'Problem: PAYLOAD_TOO_LARGE.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '415': description: 'Problem: UNSUPPORTED_MEDIA_TYPE.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '422': description: >- Problem: PRICE_UNAVAILABLE, MODEL_NOT_AVAILABLE, INPUT_URL_UNREACHABLE, IDEMPOTENCY_KEY_REUSED. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '429': description: 'Problem: RATE_LIMITED.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' Retry-After: $ref: '#/components/headers/Retry-After' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '500': description: 'Problem: INTERNAL_ERROR.' headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '503': description: >- Problem: PROVIDER_PAUSED, MODEL_PAUSED, SCHEMA_UNAVAILABLE, BILLING_UNAVAILABLE, SERVICE_UNAVAILABLE. headers: X-Request-Id: $ref: '#/components/headers/X-Request-Id' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit: $ref: '#/components/headers/RateLimit' x-should-retry: $ref: '#/components/headers/x-should-retry' Retry-After: $ref: '#/components/headers/Retry-After' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - bearer: [] components: headers: X-Request-Id: description: >- `req_`; equals `request_id` in problems and the log context. Every response. schema: type: string RateLimit-Policy: description: >- IETF draft-11, e.g. `"minute";q=600;w=60, "day";q=200000;w=86400`. Authenticated responses. schema: type: string RateLimit: description: >- IETF draft-11, e.g. `"minute";r=12;t=41`. Authenticated responses; `Retry-After` wins. schema: type: string Idempotent-Replayed: description: >- `true` on the replay of a stored run (the original status code, the current run). schema: type: string Cache-Control: description: '`no-store` on run, balance and file responses.' schema: type: string Deprecation: description: '`@` for a `deprecated` model.' schema: type: string Sunset: description: '`` for a `deprecated` model.' schema: type: string Location: description: '`/v1/runs/` on the 202 of `POST /v1/runs`.' schema: type: string Retry-After: description: >- Delay-seconds, never more than 60: every 429 and 503, 409 `IDEMPOTENCY_IN_PROGRESS`, 402 `INSUFFICIENT_BALANCE` while an auto top-up is expected, and the poll hint on a 202 or a running run. schema: type: string x-should-retry: description: '`true` or `false`, mirrors `retryable`. Every error response.' schema: type: string Allow: description: The allowed methods. Every 405. schema: type: string schemas: Problem: type: object properties: type: type: string format: uri title: type: string status: type: integer minimum: -9007199254740991 maximum: 9007199254740991 detail: type: string code: type: string retryable: type: boolean request_id: type: string errors: type: array items: type: object properties: pointer: type: string message: type: string reason: type: string enum: - unknown_field - missing_required - wrong_type - not_in_enum - below_minimum - above_maximum - not_multiple_of - too_short - too_long - too_few_items - too_many_items - pattern_mismatch - invalid_format - no_matching_variant - invalid_combination - control_field - invalid_value - file_too_large - unsupported_media_type - duration_too_long - duration_too_short - resolution_too_low - resolution_too_high - unreachable - file_not_found - content_policy - provider_refused expected: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object propertyNames: type: string additionalProperties: type: - string - number - boolean - 'null' received: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object propertyNames: type: string additionalProperties: type: - string - number - boolean - 'null' allowed: type: array items: type: - string - number - boolean - 'null' required: - pointer - message additionalProperties: false retry_after_seconds: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - type - title - status - detail - code - retryable - request_id additionalProperties: {} securitySchemes: bearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.