> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Run several searches



## OpenAPI

````yaml api-reference/openapi.json POST /v1/tools/search
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. Exception (rule 5, ADR 0167): a create whose outcome is still
    unknown after those retries may be sent again with the same key at most 3
    more times, each at least 60 s after the last (up to 8 sends in about 4
    minutes); a keyed replay is answered before the input checks, so these
    resolve in milliseconds once the run exists.

    3. Retry-After is a floor: wait at least that long (add 0–20 % jitter).
    Spiral 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 replays its run for 24 hours;
    after that the same key starts 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 7 days. 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/tools/search:
    post:
      tags:
        - Discovery
      summary: >-
        Several catalog searches in one call: one page per query, the filters
        shared (ADR 0220).
      operationId: tools-search
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                category:
                  description: >-
                    One of `llm`, `image`, `video`, `3d`, `audio`, `web`,
                    `data`, `social-media`, `e-commerce`, `finance`, `lead-gen`,
                    `public-records`, `listings`, `maps-reviews`, `seo`,
                    `news-media`, `developer`, `sports`, `industry-data`,
                    `health`, or several separated by commas (`image,video`): a
                    tool in any of them.
                  type: string
                exclude_category:
                  description: >-
                    Categories to leave out, separated by commas (`llm,data`);
                    with `category`, both apply.
                  type: string
                provider:
                  description: >-
                    A provider id, or several separated by commas
                    (`fal,replicate`): a tool of any of them.
                  type: string
                exclude_provider:
                  description: >-
                    Provider ids to leave out, separated by commas
                    (`tikhub,scrapecreators`).
                  type: string
                execution:
                  description: >-
                    Only tools that answer in the run's response (`sync`) or by
                    webhook and polling (`async`).
                  type: string
                  enum:
                    - sync
                    - async
                include_deprecated:
                  description: >-
                    `false`: leave out deprecated tools (`deprecated_at` set;
                    they retire at `retires_at`). Omitted or `true`: keep them.
                  anyOf:
                    - type: boolean
                    - type: string
                      enum:
                        - 'true'
                        - 'false'
                include_disabled:
                  description: >-
                    `true`: also list the tools this organization or key may not
                    run (`allowed: false`: the tool or its provider is turned
                    off). Omitted or `false`: only tools it may run.
                  anyOf:
                    - type: boolean
                    - type: string
                      enum:
                        - 'true'
                        - 'false'
                url:
                  description: >-
                    A page or a host (`https://www.amazon.com/dp/B0…`,
                    `tiktok.com`): only the tools made for that site, named by
                    their id (Alexandria's domain tools, ScrapeCreators' and
                    TikHub's platform tools).
                  type: string
                  maxLength: 2048
                facets:
                  description: >-
                    `true`: add `facets`, the counts by category and provider of
                    the tools matching every word, to narrow the next search.
                  anyOf:
                    - type: boolean
                    - type: string
                      enum:
                        - 'true'
                        - 'false'
                availability:
                  description: >-
                    Deprecated (ADR 0187): every listed tool is `live`, so
                    `live` keeps them all and `preview` none.
                  type: string
                  enum:
                    - live
                    - preview
                priced:
                  description: >-
                    Deprecated (ADR 0223): every listed tool is priceable, so it
                    changes nothing; still accepted.
                  anyOf:
                    - type: boolean
                    - type: string
                      enum:
                        - 'true'
                        - 'false'
                released_after:
                  description: >-
                    `YYYY-MM-DD`: only tools first released on or after this day
                    (`release_date`). Tools without a known release date are
                    left out.
                  type: string
                  format: date
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                released_before:
                  description: >-
                    `YYYY-MM-DD`: only tools first released on or before this
                    day (`release_date`). Tools without a known release date are
                    left out.
                  type: string
                  format: date
                  pattern: >-
                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                sort:
                  description: >-
                    `relevance` (the default): best match first. `newest`:
                    latest `release_date` first, tools without one last; with
                    `q`, tools matching every word still come before those
                    matching some.
                  type: string
                  enum:
                    - relevance
                    - newest
                limit:
                  type: integer
                  minimum: 1
                  maximum: 100
                  description: 1–`list.max_limit` (100), default `list.default_limit` (20).
                queries:
                  minItems: 1
                  maxItems: 10
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 500
                  description: >-
                    1–10 searches, one per need, each in the user's own words:
                    one page each, in this order.
              required:
                - queries
              additionalProperties: false
      responses:
        '200':
          description: One page of models per query, in order.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    const: list
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        object:
                          type: string
                          const: list
                        items:
                          type: array
                          items:
                            type: object
                            properties:
                              provider:
                                type: string
                              model:
                                type: string
                              title:
                                type: string
                              description:
                                type:
                                  - string
                                  - 'null'
                              category:
                                type: string
                              execution:
                                type: string
                                enum:
                                  - async
                                  - sync
                              status:
                                type: string
                                enum:
                                  - active
                                  - deprecated
                              availability:
                                type: string
                                enum:
                                  - live
                                  - preview
                              allowed:
                                type: boolean
                              priceable:
                                type: boolean
                              deprecated_at:
                                anyOf:
                                  - type: string
                                    description: RFC 3339 timestamp
                                  - type: 'null'
                              retires_at:
                                anyOf:
                                  - type: string
                                    description: RFC 3339 timestamp
                                  - type: 'null'
                              release_date:
                                description: >-
                                  The day the tool was first available from its
                                  provider (`YYYY-MM-DD`); null when unknown.
                                type:
                                  - string
                                  - 'null'
                              match:
                                type: string
                                enum:
                                  - full
                                  - partial
                              matched:
                                type: array
                                items:
                                  type: string
                                  enum:
                                    - title
                                    - model
                                    - category
                                    - provider
                                    - description
                              score:
                                type: integer
                                minimum: -9007199254740991
                                maximum: 9007199254740991
                            required:
                              - provider
                              - model
                              - title
                              - description
                              - category
                              - execution
                              - status
                              - availability
                              - allowed
                              - priceable
                              - deprecated_at
                              - retires_at
                              - release_date
                              - match
                              - matched
                              - score
                        next_cursor:
                          type:
                            - string
                            - 'null'
                        has_more:
                          type: boolean
                        facets:
                          type: object
                          properties:
                            total:
                              type: integer
                              minimum: -9007199254740991
                              maximum: 9007199254740991
                            category:
                              type: object
                              propertyNames:
                                type: string
                              additionalProperties:
                                type: integer
                                minimum: -9007199254740991
                                maximum: 9007199254740991
                            provider:
                              type: object
                              propertyNames:
                                type: string
                              additionalProperties:
                                type: integer
                                minimum: -9007199254740991
                                maximum: 9007199254740991
                          required:
                            - total
                            - category
                            - provider
                        suggestions:
                          type: object
                          properties:
                            categories:
                              type: array
                              items:
                                type: string
                          required:
                            - categories
                        q:
                          type: string
                      required:
                        - object
                        - items
                        - next_cursor
                        - has_more
                        - q
                required:
                  - object
                  - results
        '400':
          description: 'Problem: INVALID_JSON, INVALID_REQUEST.'
          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'
        '403':
          description: 'Problem: 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'
        '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'
        '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'
        '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: 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_<ULID>`; 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
    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
    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
  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.