openapi: 3.0.0
info:
  title: Brave AI Mode API
  description: |
    Get the answers of Ask Brave, the AI mode of Brave Search, in structured JSON. This API returns the answer as
    text blocks and markdown, the pages the answer cites, the web results Brave searched and the follow-up questions
    Brave suggests.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Brave AI Mode Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Search engine to use
          schema:
            type: string
            enum: ["brave_ai_mode"]
            default: "brave_ai_mode"
        - name: q
          in: query
          required: true
          description: The question to ask Brave, up to 2048 characters and 7,000 bytes once URL-encoded, which non-Latin scripts reach in fewer characters. Brave answers in the language of the question.
          schema:
            type: string
            maxLength: 2048
        - name: country
          in: query
          required: false
          description: Two-letter country code that sets the region Brave answers for. Set it to `all` for all regions.
          schema:
            type: string
            default: "us"
            enum: ["all", "ar", "au", "at", "be", "br", "ca", "cl", "cn", "dk", "fi", "fr", "de", "gr", "hk", "in", "id", "it", "jp", "kr", "my", "mx", "nl", "nz", "no", "ph", "pl", "pt", "ru", "sa", "sg", "za", "es", "se", "ch", "tw", "tr", "gb", "us"]
        - name: language
          in: query
          required: false
          description: Two-letter language code. Brave uses it when the question does not show its language, for example a bare name.
          schema:
            type: string
            default: "en"
            enum: ["az", "bg", "br", "ca", "cs", "cy", "da", "de", "el", "en", "es", "et", "eu", "fi", "fr", "gl", "hr", "hu", "id", "it", "ja", "ka", "ko", "lt", "lv", "ms", "nb", "nl", "pl", "pt", "ro", "ru", "sk", "sl", "sq", "sr", "sv", "sw", "th", "tr", "uk", "vi", "zh"]
      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'
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:
    SearchResponse:
      type: object
      required: [search_metadata, search_parameters]
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        error:
          type: string
          description: Message saying Brave wrote no answer to the question
        text_blocks:
          type: array
          description: The answer as typed content blocks
          items:
            $ref: '#/components/schemas/TextBlock'
        markdown:
          type: string
          description: The answer as one markdown string
        reference_links:
          type: array
          description: The pages the answer cites, once each, in the order the answer first cites them
          items:
            $ref: '#/components/schemas/ReferenceLink'
        web_results:
          type: array
          description: The web results Brave searched for the question, in Brave's order
          items:
            $ref: '#/components/schemas/WebResult'
        related_questions:
          type: array
          description: The follow-up questions Brave suggests under the answer
          items:
            $ref: '#/components/schemas/RelatedQuestion'
    SearchMetadata:
      type: object
      required: [id, 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: Ask Brave URL for this search
        html_url:
          type: string
          description: URL to view the raw response
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Search engine used
        q:
          type: string
          description: The question asked
        country:
          type: string
          description: Two-letter country code of the request
        language:
          type: string
          description: Two-letter language code of the request
    TextBlock:
      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 content for header, paragraph, or list introduction
        reference_indexes:
          type: array
          description: Zero-based indexes into `reference_links` cited by this block
          items:
            type: integer
        items:
          type: array
          description: List items (for ordered/unordered lists)
          items:
            $ref: '#/components/schemas/TextBlock'
        table:
          type: object
          description: Table data (for table type)
          properties:
            headers:
              type: array
              description: Table header row
              items:
                type: string
            rows:
              type: array
              description: Table data rows
              items:
                type: array
                items:
                  type: string
          required: [headers, rows]
        language:
          type: string
          description: Programming language (for code_blocks type)
        code:
          type: string
          description: Code content (for code_blocks type)
    ReferenceLink:
      type: object
      required: [index, link]
      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: Host name of the cited page's website
        snippet:
          type: string
          description: Passage of the page the answer cites, as plain text that keeps its line breaks
        favicon:
          type: string
          description: Favicon URL of the source
    WebResult:
      type: object
      required: [position, link]
      properties:
        position:
          type: integer
          description: One-based position of the result in Brave's order
        title:
          type: string
          description: Page title
        link:
          type: string
          description: URL of the result
        source:
          type: string
          description: Host name of the result's website
        snippet:
          type: string
          description: Description of the page shown with the result
        date:
          type: string
          description: Date Brave shows for the page
        favicon:
          type: string
          description: Favicon URL of the source
    RelatedQuestion:
      type: object
      required: [question]
      properties:
        question:
          type: string
          description: Suggested follow-up question text
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong