---
openapi: 3.0.0
info:
  title: Duck.ai API
  description: Get Duck.ai answers as structured JSON. To continue an answer, pass
    pagination.conversation_token with the next question. Keep the same model for
    the conversation. Web search and reasoning availability depend on the selected
    model. Image-only answers do not return a conversation token.
  version: 1.0.0
servers:
- url: https://www.searchapi.io/api/v1
paths:
  "/search":
    get:
      summary: Duck.ai Search
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      parameters:
      - name: engine
        in: query
        required: true
        description: Set to duck_ai.
        schema:
          type: string
          enum:
          - duck_ai
      - name: q
        in: query
        required: true
        description: The question to send to Duck.ai, up to 16000 characters. The
          limit counts UTF-16 code units; a supplementary character such as an emoji
          counts as two. Send a long question with POST.
        schema:
          type: string
          maxLength: 16000
      - name: model
        in: query
        required: false
        description: The model to use. A follow-up keeps its conversation model.
        schema:
          type: string
          enum:
          - gpt-6-luna
          - gpt-5.6-luna
          - gpt-5.4-mini
          - claude-haiku-5-5
          - claude-haiku-4-5
          - mistral-small-2603
          - tinfoil/gpt-oss-120b
          - tinfoil/gemma4-31b
          default: gpt-6-luna
      - name: reasoning_effort
        in: query
        required: false
        description: 'The reasoning effort supported by the selected model. gpt-6-luna:
          none, low; gpt-5.6-luna: none, low; gpt-5.4-mini: none, low; claude-haiku-5-5:
          none, low; claude-haiku-4-5: none, low; mistral-small-2603: omit reasoning_effort;
          tinfoil/gpt-oss-120b: low; tinfoil/gemma4-31b: none, low. When omitted,
          the first supported effort is used.'
        schema:
          type: string
          enum:
          - none
          - low
      - name: web_search
        in: query
        required: false
        description: 'Request web search on a model that supports it. Supported models:
          gpt-6-luna, gpt-5.6-luna, gpt-5.4-mini, claude-haiku-5-5, claude-haiku-4-5,
          tinfoil/gpt-oss-120b.'
        schema:
          type: string
          enum:
          - 'true'
      - name: conversation_token
        in: query
        required: false
        description: Use pagination.conversation_token from a fresh response to continue
          the conversation. Send a long token with POST.
        schema:
          type: string
          maxLength: 64000
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SearchResponse"
        '400':
          description: Validation Error. There is an issue with query parameters,
            such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been
            exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
    post:
      summary: Duck.ai Search with a JSON body
      description: Takes the same parameters as a JSON body. Use it when the question
        or the conversation token is too long for a URL.
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/SearchRequest"
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/SearchResponse"
        '400':
          description: Validation Error. There is an issue with the parameters, such
            as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been
            exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchMetadata:
      type: object
      required:
      - status
      - created_at
      properties:
        id:
          type: string
          description: Unique identifier for the search request
        status:
          type: string
          description: Status of the search request
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created
        request_time_taken:
          type: number
          description: Time taken to make the request in seconds
        parsing_time_taken:
          type: number
          description: Time taken to parse the results in seconds
        total_time_taken:
          type: number
          description: Total time taken for the search in seconds
        request_url:
          type: string
          description: Upstream URL used for this search
        html_url:
          type: string
          description: URL to view the raw event stream
        json_url:
          type: string
          description: URL to view JSON results
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
    SearchRequest:
      type: object
      required:
      - engine
      - q
      properties:
        engine:
          type: string
          enum:
          - duck_ai
          description: Set to duck_ai.
        q:
          type: string
          maxLength: 16000
          description: The question to send to Duck.ai, up to 16000 characters. The
            limit counts UTF-16 code units; a supplementary character such as an emoji
            counts as two.
        model:
          type: string
          enum:
          - gpt-6-luna
          - gpt-5.6-luna
          - gpt-5.4-mini
          - claude-haiku-5-5
          - claude-haiku-4-5
          - mistral-small-2603
          - tinfoil/gpt-oss-120b
          - tinfoil/gemma4-31b
          default: gpt-6-luna
          description: The model to use. A follow-up keeps its conversation model.
        reasoning_effort:
          type: string
          enum:
          - none
          - low
          description: 'The reasoning effort supported by the selected model. gpt-6-luna:
            none, low; gpt-5.6-luna: none, low; gpt-5.4-mini: none, low; claude-haiku-5-5:
            none, low; claude-haiku-4-5: none, low; mistral-small-2603: omit reasoning_effort;
            tinfoil/gpt-oss-120b: low; tinfoil/gemma4-31b: none, low. When omitted,
            the first supported effort is used.'
        web_search:
          type: string
          enum:
          - 'true'
          description: 'Request web search on a model that supports it. Supported
            models: gpt-6-luna, gpt-5.6-luna, gpt-5.4-mini, claude-haiku-5-5, claude-haiku-4-5,
            tinfoil/gpt-oss-120b.'
        conversation_token:
          type: string
          maxLength: 64000
          description: Use pagination.conversation_token from a fresh response to
            continue the conversation.
    SearchResponse:
      type: object
      properties:
        search_metadata:
          "$ref": "#/components/schemas/SearchMetadata"
        search_parameters:
          "$ref": "#/components/schemas/SearchParameters"
        error:
          type: string
          description: Message saying why Duck.ai returned no answer.
        text_blocks:
          type: array
          description: The answer split into structured blocks.
          items:
            "$ref": "#/components/schemas/AiAnswerTextBlock"
        markdown:
          type: string
          description: The answer in Markdown.
        response_metadata:
          type: object
          description: Details about the answer.
          properties:
            model:
              type: string
              description: The model that wrote the answer.
            message_id:
              type: string
              description: Duck.ai's identifier for the answer.
            title:
              type: string
              description: The title Duck.ai gave the conversation.
            is_web_search_performed:
              type: boolean
              description: Whether Duck.ai searched the web for the answer.
            conversation_limit_percentage:
              type: integer
              description: How much of Duck.ai's conversation limit is used, as a
                percentage.
            is_truncated:
              type: boolean
              description: Whether the answer was cut off at the model's output limit.
          additionalProperties: false
        pagination:
          type: object
          description: How to continue the conversation.
          properties:
            conversation_token:
              type: string
              description: The token to pass with the next question.
          additionalProperties: false
        web_results:
          type: array
          description: The pages retrieved for the answer.
          items:
            type: object
            properties:
              position:
                type: integer
                description: Position of the page among the retrieved pages.
              title:
                type: string
                description: Page title.
              link:
                type: string
                description: Page URL.
              source:
                type: string
                description: Website name.
              favicon:
                type: string
                description: Favicon URL of the website.
              date:
                type: string
                description: Publication date of the page.
            additionalProperties: false
        search_queries:
          type: array
          description: The web searches Duck.ai ran for the answer.
          items:
            type: string
        reference_links:
          type: array
          description: The sources cited by the answer.
          items:
            type: object
            properties:
              index:
                type: integer
                description: Zero-based position of this reference in `reference_links`
              title:
                type: string
                description: Page title
              link:
                type: string
                description: URL of the reference
              source:
                type: string
                description: Source website name
              date:
                type: string
                description: Publication date shown for the reference
              favicon:
                type: string
                description: Favicon URL of the source
            additionalProperties: false
        citations:
          type: array
          description: Where the answer cites its sources.
          items:
            type: object
            properties:
              index:
                type: integer
                description: Character offset in `markdown` where the citation sits.
              source_indexes:
                type: array
                description: The `reference_links` indexes of the sources cited there.
                items:
                  type: integer
            additionalProperties: false
        thinking_steps:
          type: array
          description: The reasoning Duck.ai showed before the answer.
          items:
            type: object
            properties:
              title:
                type: string
                description: Heading of the reasoning step.
              description:
                type: string
                description: Text of the reasoning step.
            additionalProperties: false
        related_searches:
          type: array
          description: Searches Duck.ai suggested after the answer.
          items:
            type: object
            properties:
              query:
                type: string
                description: The suggested search.
              link:
                type: string
                description: DuckDuckGo URL of the suggested search.
              score:
                type: number
                description: Duck.ai's relevance score for the suggestion.
            additionalProperties: false
        inline_images:
          type: array
          description: Images generated for the answer.
          items:
            type: object
            properties:
              title:
                type: string
                description: Image title.
              original:
                type: string
                description: The image as a base64 data URI.
              width:
                type: integer
                description: Image width in pixels.
              height:
                type: integer
                description: Image height in pixels.
              query:
                type: string
                description: The prompt the image was generated from.
              model:
                type: string
                description: Name of the image model.
            additionalProperties: false
      additionalProperties: false
      required:
      - search_metadata
      - search_parameters
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          enum:
          - duck_ai
          description: Set to duck_ai.
        q:
          type: string
          maxLength: 16000
          description: The question to send to Duck.ai, up to 16000 characters. The
            limit counts UTF-16 code units; a supplementary character such as an emoji
            counts as two.
        model:
          type: string
          enum:
          - gpt-6-luna
          - gpt-5.6-luna
          - gpt-5.4-mini
          - claude-haiku-5-5
          - claude-haiku-4-5
          - mistral-small-2603
          - tinfoil/gpt-oss-120b
          - tinfoil/gemma4-31b
          default: gpt-6-luna
          description: The model to use. A follow-up keeps its conversation model.
        reasoning_effort:
          type: string
          enum:
          - none
          - low
          description: 'The reasoning effort supported by the selected model. gpt-6-luna:
            none, low; gpt-5.6-luna: none, low; gpt-5.4-mini: none, low; claude-haiku-5-5:
            none, low; claude-haiku-4-5: none, low; mistral-small-2603: omit reasoning_effort;
            tinfoil/gpt-oss-120b: low; tinfoil/gemma4-31b: none, low. When omitted,
            the first supported effort is used.'
        web_search:
          type: boolean
          description: Whether web search was requested.
        conversation_token:
          type: string
          maxLength: 64000
          description: Use pagination.conversation_token from a fresh response to
            continue the conversation.
    AiAnswerTextBlock:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - header
          - paragraph
          - unordered_list
          - ordered_list
          - table
          - code_blocks
          description: Type of content block.
        answer:
          type: string
          description: Text of a header, paragraph or list item, with inline code
            kept in backticks.
        reference_indexes:
          type: array
          description: Zero-based indexes into `reference_links` cited by this block
          items:
            type: integer
        items:
          type: array
          description: Nested blocks within a list or list item.
          items:
            "$ref": "#/components/schemas/AiAnswerTextBlock"
        table:
          type: object
          description: Table data (for table type)
          required:
          - headers
          - rows
          properties:
            headers:
              type: array
              description: Table header row; cells keep inline-code backticks like
                `answer`
              items:
                type: string
            rows:
              type: array
              description: Table data rows; cells keep inline-code backticks like
                `answer`
              items:
                type: array
                items:
                  type: string
        language:
          type: string
          description: Programming language (for code_blocks type)
        code:
          type: string
          description: Code content (for code_blocks type)
