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

# Create a search

> Start a search for answers to a query. Returns HTTP 202 with a search ID; use it to retrieve status and results.

Send a `query` and `results` count. The API returns HTTP `202` with an `id`; use it to [read the answers](https://www.thred.dev/api-reference/search-results.md).

Optional `output` fields add structured values alongside the text answer. Choose **Structured answers** in the example menu to see the format.

`results` accepts 1–100 and caps call attempts to distinct sources; the number of complete answers may be smaller.


## OpenAPI

````yaml api-reference/openapi.json POST /search
openapi: 3.0.3
info:
  title: Thred API
  version: 2.0.0
  description: >-
    Retrieve information over the phone for your app or AI assistant. Submit a
    search query and read answers asynchronously, with source details and
    supporting evidence. API keys select workspace and environment.
servers:
  - url: https://api.thred.dev
    description: Thred API
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: Verify the workspace and environment selected by your API key.
  - name: Usage
    description: Read daily operational usage.
  - name: Health
    description: Check public API availability.
  - name: Search
    description: >-
      Search for answers over the phone, with source details and supporting
      evidence.
paths:
  /search:
    post:
      tags:
        - Search
      summary: Create a search
      description: >-
        Start a search for answers to a query. Returns HTTP 202 with a search
        ID; use it to retrieve status and results.
      operationId: createSearch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            examples:
              Text answers:
                summary: Search for answers
                value:
                  query: Where can I buy a Nintendo Switch 2 in Austin today?
                  results: 2
              Structured answers:
                summary: Request structured fields
                value:
                  query: Where can I buy a Nintendo Switch 2 in Austin today?
                  results: 2
                  output:
                    in_stock:
                      type: boolean
                      description: Whether the Nintendo Switch 2 is currently in stock.
                    pickup_details:
                      type: string
                      description: >-
                        Same-day pickup availability and the latest local pickup
                        time.
      responses:
        '202':
          description: Search accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Search'
              example:
                id: search_6c479a30-cf06-4dba-8dc9-2d2893bbc64f
                query: Where can I buy a Nintendo Switch 2 in Austin today?
                status: discovering
                environment: development
                identity:
                  name: AI assistant
                call_reason: public
                requested_calls: 2
                selected_businesses: 0
                attempted_calls: 0
                answered_calls: 0
                published_results: 0
                discovery_shortfall: null
                created_at: '2026-11-12T15:00:00Z'
                deadline_at: '2026-11-12T15:30:00Z'
                finished_at: null
                terminal: false
                cancellation_requested: false
                stop_reason: null
                error: null
          headers:
            X-Request-ID:
              description: >-
                Server-generated request identifier for correlating this
                response.
              schema:
                type: string
                format: uuid
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          $ref: '#/components/responses/TooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  schemas:
    SearchRequest:
      type: object
      required:
        - query
        - results
      additionalProperties: false
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 8000
          description: >-
            The information to obtain. Must contain non-whitespace text. Include
            location when it matters.
          example: Where can I buy a Nintendo Switch 2 in Austin today?
          pattern: \S
        results:
          type: integer
          minimum: 1
          maximum: 100
          description: >-
            Hard cap of call attempts to distinct sources. Unanswered calls and
            negative answers count; successful matches are not guaranteed.
          example: 2
        identity:
          type: object
          additionalProperties: false
          required:
            - name
          properties:
            name:
              type: string
              minLength: 1
              maxLength: 100
              pattern: \S
            url:
              type: string
              format: uri
              description: >-
                HTTPS website without embedded credentials, to share when
                relevant.
              minLength: 1
              maxLength: 2000
            description:
              type: string
              maxLength: 1000
              minLength: 1
              pattern: \S
          default:
            name: AI assistant
        call_reason:
          type: string
          enum:
            - public
            - customer
          default: public
          description: >-
            Purpose of the call. Public does not make results publicly
            accessible.
        location:
          type: string
          maxLength: 300
          minLength: 1
          description: Geographic context for the search.
          pattern: \S
        language:
          type: string
          example: en
          pattern: ^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8}){0,3}$
          description: Language tag such as en or fr-CA.
        output:
          type: object
          minProperties: 1
          maxProperties: 20
          additionalProperties:
            type: object
            required:
              - type
              - description
            additionalProperties: false
            properties:
              type:
                type: string
                enum:
                  - string
                  - string[]
                  - number
                  - integer
                  - boolean
              description:
                type: string
                maxLength: 1000
                minLength: 1
                pattern: \S
          description: >-
            Optional custom fields to collect, at most 20 fields and 12,000
            characters of JSON. If omitted, each result contains a concise
            natural-language answer in content and no output property; Thred
            does not generate custom fields. Field names must contain 1–120
            characters and cannot be `__proto__`, `prototype`, or `constructor`.
            Descriptions must contain non-whitespace text.
        webhook_id:
          type: string
          description: An enabled webhook endpoint in the same workspace/environment.
          minLength: 1
          maxLength: 200
          pattern: \S
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Custom metadata stored with the search, up to 4000 UTF-8 bytes of
            JSON. Defaults to an empty object. It is not echoed in status,
            results, or webhook payloads.
          default: {}
      example:
        query: Where can I buy a Nintendo Switch 2 in Austin today?
        results: 2
    Search:
      type: object
      required:
        - id
        - query
        - status
        - environment
        - identity
        - call_reason
        - requested_calls
        - selected_businesses
        - attempted_calls
        - answered_calls
        - published_results
        - discovery_shortfall
        - created_at
        - deadline_at
        - finished_at
        - terminal
        - cancellation_requested
        - stop_reason
        - error
      properties:
        id:
          type: string
          pattern: ^search_[a-z0-9-]+$
          description: Search ID returned when the request was accepted.
          example: search_6c479a30-cf06-4dba-8dc9-2d2893bbc64f
        query:
          type: string
          example: Where can I buy a Nintendo Switch 2 in Austin today?
        status:
          type: string
          enum:
            - discovering
            - running
            - canceling
            - completed
            - failed
            - canceled
            - expired
          description: >-
            Current search state. completed, failed, canceled, and expired are
            terminal.
        environment:
          type: string
          enum:
            - development
            - production
        identity:
          type: object
          additionalProperties: false
          required:
            - name
          properties:
            name:
              type: string
              minLength: 1
              maxLength: 100
            url:
              type: string
              format: uri
              description: >-
                HTTPS website without embedded credentials, to share when
                relevant.
              minLength: 1
            description:
              type: string
              maxLength: 1000
              minLength: 1
        call_reason:
          type: string
          enum:
            - public
            - customer
        requested_calls:
          type: integer
          minimum: 1
          maximum: 100
          description: The call-attempt limit supplied in the request results field.
        selected_businesses:
          type: integer
          minimum: 0
          description: Number of selected sources.
        attempted_calls:
          type: integer
          minimum: 0
          description: Number of sources where starting a call was attempted.
        answered_calls:
          type: integer
          minimum: 0
          description: >-
            Calls answered by the destination, including automated answering
            systems.
        published_results:
          type: integer
          minimum: 0
          description: >-
            Number of published result entries available from the results
            endpoint.
        discovery_shortfall:
          type: integer
          nullable: true
          minimum: 0
          description: >-
            Requested calls minus selected sources, bounded at zero. Null until
            source selection has finished.
        created_at:
          type: string
          format: date-time
        deadline_at:
          type: string
          format: date-time
          description: >-
            New dialing stops after 30 minutes. Active calls are canceled;
            post-call processing may finish later.
        finished_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            When the search reached a terminal state; null while work is in
            progress.
        terminal:
          type: boolean
          description: Whether all work has settled and no more results will be published.
        cancellation_requested:
          type: boolean
          description: Whether cancellation was requested for this search.
        stop_reason:
          type: string
          nullable: true
          description: >-
            Reason work was stopped early, when present; null for normal
            completion.
        error:
          type: object
          nullable: true
          properties:
            code:
              type: string
            message:
              type: string
          required:
            - code
            - message
          description: >-
            Search-level failure details, or null when no search-level error was
            recorded.
      example:
        id: search_6c479a30-cf06-4dba-8dc9-2d2893bbc64f
        query: Where can I buy a Nintendo Switch 2 in Austin today?
        status: completed
        environment: development
        identity:
          name: AI assistant
        call_reason: public
        requested_calls: 2
        selected_businesses: 2
        attempted_calls: 2
        answered_calls: 2
        published_results: 2
        discovery_shortfall: 0
        created_at: '2026-11-12T15:00:00Z'
        deadline_at: '2026-11-12T15:30:00Z'
        finished_at: '2026-11-12T15:03:10Z'
        terminal: true
        cancellation_requested: false
        stop_reason: null
        error: null
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
          description: >-
            Request-level error details with a machine-readable code and a
            message.
  responses:
    BadRequest:
      description: >-
        Invalid JSON, query, options, output fields, cursor, webhook, or date
        range. Inspect error.code and error.message.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: >-
        Missing, malformed, invalid, revoked, or environment-mismatched bearer
        API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooLarge:
      description: >-
        The request body exceeds 64 KiB. Shorten the query, output descriptions,
        identity details, or metadata.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: >-
        The workspace/environment already has 20 unfinished searches. Existing
        searches continue; submit new work after capacity is available.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unavailable:
      description: >-
        The service or required environment configuration is unavailable. Codes
        include calling_unavailable, environment_unavailable, not_configured,
        and backend_unavailable. Inspect error.code and error.message.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Thred API key
      description: >-
        Send Authorization: Bearer <THRED_API_KEY>. Development keys begin
        thr_dev_; Production keys begin thr_prod_. Each key is scoped to a
        workspace and environment. Keep secrets on your server.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.