exa-openapi-spec.yaml

openapi: 3.1.0
info:
  version: 1.2.0
  title: Exa Search API
  description: A comprehensive API for internet-scale search, allowing users to perform queries and retrieve results from a wide variety of sources using embeddings-based and traditional search.
servers:
  - url: https://api.exa.ai
security:
  - apikey: []
paths:
  /search:
    post:
      operationId: search
      summary: Search
      description: Perform a search with a Exa prompt-engineered query and retrieve a list of relevant results. Optionally get contents.
      x-codeSamples:
        - lang: bash
          label: Simple search and contents
          source: |
            curl -X POST 'https://api.exa.ai/search' \
              -H 'x-api-key: YOUR-EXA-API-KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "query": "Latest research in LLMs",
                "text": true
              }'
        - lang: python
          label: Simple search and contents
          source: |
            # pip install exa-py
            from exa_py import Exa
            exa = Exa('YOUR_EXA_API_KEY')

            results = exa.search_and_contents(
                "Latest research in LLMs", 
                text=True
            )

            print(results)
        - lang: javascript
          label: Simple search and contents
          source: |
            // npm install exa-js
            import Exa from 'exa-js';
            const exa = new Exa('YOUR_EXA_API_KEY');

            const results = await exa.searchAndContents(
                'Latest research in LLMs', 
                { text: true }
            );

            console.log(results);
        - lang: php
          label: Simple search and contents
          source: ""
        - lang: go
          label: Simple search and contents
          source: ""
        - lang: java
          label: Simple search and contents
          source: ""
        - lang: bash
          label: Advanced search with filters
          source: |
            curl --request POST \
              --url https://api.exa.ai/search \
              --header 'x-api-key: <token>' \
              --header 'Content-Type: application/json' \
              --data '{
              "query": "Latest research in LLMs",
              "type": "auto",
              "category": "research paper",
              "numResults": 10,
              "contents": {
                "text": true,
                "summary": {
                  "query": "Main developments"
                },
                "subpages": 1,
                "subpageTarget": "sources",
                "extras": {
                  "links": 1,
                  "imageLinks": 1
                }
              }
            }'
        - lang: python
          label: Advanced search with filters
          source: |
            # pip install exa-py
            from exa_py import Exa
            exa = Exa('YOUR_EXA_API_KEY')

            results = exa.search_and_contents(
                "Latest research in LLMs",
                type="auto",
                category="research paper",
                num_results=10,
                text=True,
                summary={
                    "query": "Main developments"
                },
                subpages=1,
                subpage_target="sources",
                extras={
                    "links": 1,
                    "image_links": 1
                }
            )

            print(results)
        - lang: javascript
          label: Advanced search with filters
          source: |
            // npm install exa-js
            import Exa from 'exa-js';
            const exa = new Exa('YOUR_EXA_API_KEY');

            const results = await exa.searchAndContents('Latest research in LLMs', {
                type: 'auto',
                category: 'research paper',
                numResults: 10,
                contents: {
                    text: true,
                    summary: {
                        query: 'Main developments'
                    },
                    subpages: 1,
                    subpageTarget: 'sources',
                    extras: {
                        links: 1,
                        imageLinks: 1
                    }
                }
            });

            console.log(results);
        - lang: bash
          label: Deep search with query variations
          source: |
            curl --request POST \
              --url https://api.exa.ai/search \
              --header 'x-api-key: <token>' \
              --header 'Content-Type: application/json' \
              --data '{
              "query": "blog post about AI",
              "additionalQueries": ["AI blogpost", "machine learning blogs"],
              "type": "deep",
              "contents": {
                "text": true,
                "context": true
              }
            }'
        - lang: python
          label: Deep search with query variations
          source: |
            # pip install exa-py
            from exa_py import Exa
            exa = Exa('YOUR_EXA_API_KEY')

            results = exa.search_and_contents(
                "blog post about AI",
                type="deep",
                additional_queries=["AI blogpost", "machine learning blogs"],
                text=True,
                context=True
            )

            print(results)
        - lang: javascript
          label: Deep search with query variations
          source: |
            // npm install exa-js
            import Exa from 'exa-js';
            const exa = new Exa('YOUR_EXA_API_KEY');

            const results = await exa.searchAndContents('blog post about AI', {
                type: 'deep',
                additionalQueries: ['AI blogpost', 'machine learning blogs'],
                text: true,
                context: true
            });

            console.log(results);
        - lang: php
          label: Advanced search with filters
          source: ""
        - lang: go
          label: Advanced search with filters
          source: ""
        - lang: java
          label: Advanced search with filters
          source: ""
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - type: object
                  properties:
                    query:
                      type: string
                      example: "Latest developments in LLM capabilities"
                      description: The query string for the search.
                    additionalQueries:
                      type: array
                      items:
                        type: string
                      description: Additional query variations for deep search. Only works with type="deep" or type="deep-reasoning". When provided, these queries are used alongside the main query for comprehensive results.
                      example: ["LLM advancements", "large language model progress"]
                    type:
                      type: string
                      enum:
                        - neural
                        - fast
                        - auto
                        - deep
                        - deep-reasoning
                        - instant
                      description: The type of search. Neural uses an embeddings-based model, auto (default) intelligently combines neural and other search methods, fast uses streamlined versions of the search models, deep is light deep search, deep-reasoning is base deep search, and instant provides the lowest latency search optimized for real-time applications.
                      example: "auto"
                      default: "auto"
                    outputSchema:
                      type: object
                      description: >-
                        JSON schema for deep search structured output mode. When provided, the
                        output.content field is returned as structured JSON matching this schema.
                      additionalProperties: {}
                    category:
                      type: string
                      enum:
                        - company
                        - research paper
                        - news
                        - pdf
                        - github
                        - personal site
                        - people
                        - financial report
                      description: "A data category to focus on. The `people` and `company` categories have improved quality for finding LinkedIn profiles and company pages. Note: The `company` and `people` categories only support a limited set of filters. The following parameters are NOT supported for these categories: `startPublishedDate`, `endPublishedDate`, `startCrawlDate`, `endCrawlDate`, `includeText`, `excludeText`, `excludeDomains`. For `people` category, `includeDomains` only accepts LinkedIn domains. Using unsupported parameters will result in a 400 error."
                      example: "research paper"
                    userLocation:
                      type: string
                      description: The two-letter ISO country code of the user, e.g. US.
                      example: "US"
                  required:
                    - query
                - $ref: "#/components/schemas/CommonRequest"
      responses:
        "200":
          $ref: "#/components/responses/SearchResponse"
  /findSimilar:
    post:
      operationId: findSimilar
      summary: Find similar links
      description: Find similar links to the link provided. Optionally get contents.
      x-codeSamples:
        - lang: bash
          label: Find similar links
          source: |
            curl -X POST 'https://api.exa.ai/findSimilar' \
              -H 'x-api-key: YOUR-EXA-API-KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "url": "https://arxiv.org/abs/2307.06435",
                "text": true
              }'
        - lang: python
          label: Find similar links
          source: |
            # pip install exa-py
            from exa_py import Exa
            exa = Exa('YOUR_EXA_API_KEY')

            results = exa.find_similar_and_contents(
                url="https://arxiv.org/abs/2307.06435",
                text=True
            )

            print(results)
        - lang: javascript
          label: Find similar links
          source: |
            // npm install exa-js
            import Exa from 'exa-js';
            const exa = new Exa('YOUR_EXA_API_KEY');

            const results = await exa.findSimilarAndContents(
                'https://arxiv.org/abs/2307.06435',
                { text: true }
            );

            console.log(results);
        - lang: php
          label: Find similar links
          source: ""
        - lang: go
          label: Find similar links
          source: ""
        - lang: java
          label: Find similar links
          source: ""
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - type: object
                  properties:
                    url:
                      type: string
                      example: "https://arxiv.org/abs/2307.06435"
                      description: The url for which you would like to find similar links.
                    excludeSourceDomain:
                      type: boolean
                      description: If true, excludes links from the same domain as the provided URL from the results.
                      example: true
                  required:
                    - url
                - $ref: "#/components/schemas/CommonRequest"
      responses:
        "200":
          $ref: "#/components/responses/FindSimilarResponse"
  /contents:
    post:
      summary: Get Contents
      operationId: "getContents"
      x-codeSamples:
        - lang: bash
          label: Simple contents retrieval
          source: |
            curl -X POST 'https://api.exa.ai/contents' \
              -H 'x-api-key: YOUR-EXA-API-KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "urls": ["https://arxiv.org/abs/2307.06435"],
                "text": true
              }'
        - lang: python
          label: Simple contents retrieval
          source: |
            # pip install exa-py
            from exa_py import Exa
            exa = Exa('YOUR_EXA_API_KEY')

            results = exa.get_contents(
                urls=["https://arxiv.org/abs/2307.06435"],
                text=True
            )

            print(results)
        - lang: javascript
          label: Simple contents retrieval
          source: |
            // npm install exa-js
            import Exa from 'exa-js';
            const exa = new Exa('YOUR_EXA_API_KEY');

            const results = await exa.getContents(
                ["https://arxiv.org/abs/2307.06435"],
                { text: true }
            );

            console.log(results);
        - lang: php
          label: Simple contents retrieval
          source: ""
        - lang: go
          label: Simple contents retrieval
          source: ""
        - lang: java
          label: Simple contents retrieval
          source: ""
        - lang: bash
          label: Advanced contents retrieval
          source: |
            curl --request POST \
              --url https://api.exa.ai/contents \
              --header 'x-api-key: YOUR-EXA-API-KEY' \
              --header 'Content-Type: application/json' \
              --data '{
                "urls": ["https://arxiv.org/abs/2307.06435"],
                "text": {
                  "maxCharacters": 1000,
                  "includeHtmlTags": false
                },
                "highlights": {
                  "numSentences": 3,
                  "highlightsPerUrl": 2,
                  "query": "Key findings"
                },
                "summary": {
                  "query": "Main research contributions"
                },
                "subpages": 1,
                "subpageTarget": "references",
                "extras": {
                  "links": 2,
                  "imageLinks": 1
                }
              }'
        - lang: python
          label: Advanced contents retrieval
          source: |
            # pip install exa-py
            from exa_py import Exa
            exa = Exa('YOUR_EXA_API_KEY')

            results = exa.get_contents(
                urls=["https://arxiv.org/abs/2307.06435"],
                text={
                    "maxCharacters": 1000,
                    "includeHtmlTags": False
                },
                highlights={
                    "numSentences": 3,
                    "highlightsPerUrl": 2,
                    "query": "Key findings"
                },
                summary={
                    "query": "Main research contributions"
                },
                subpages=1,
                subpage_target="references",
                extras={
                    "links": 2,
                    "image_links": 1
                }
            )

            print(results)
        - lang: javascript
          label: Advanced contents retrieval
          source: |
            // npm install exa-js
            import Exa from 'exa-js';
            const exa = new Exa('YOUR_EXA_API_KEY');

            const results = await exa.getContents(
                ["https://arxiv.org/abs/2307.06435"],
                {
                    text: {
                        maxCharacters: 1000,
                        includeHtmlTags: false
                    },
                    highlights: {
                        numSentences: 3,
                        highlightsPerUrl: 2,
                        query: "Key findings"
                    },
                    summary: {
                        query: "Main research contributions"
                    },
                    subpages: 1,
                    subpageTarget: "references",
                    extras: {
                        links: 2,
                        imageLinks: 1
                    }
                }
            );

            console.log(results);
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              allOf:
                - type: object
                  properties:
                    urls:
                      type: array
                      description: Array of URLs to crawl (backwards compatible with 'ids' parameter).
                      items:
                        type: string
                      example: ["https://arxiv.org/pdf/2307.06435"]
                    ids:
                      type: array
                      deprecated: true
                      description: Deprecated - use 'urls' instead. Array of document IDs obtained from searches.
                      items:
                        type: string
                      example: ["https://arxiv.org/pdf/2307.06435"]
                  required:
                    - urls
                - $ref: "#/components/schemas/ContentsRequest"
      responses:
        "200":
          $ref: "#/components/responses/ContentsResponse"
  /answer:
    post:
      operationId: answer
      summary: Generate an answer from search results
      description: |
        Performs a search based on the query and generates either a direct answer or a detailed summary with citations, depending on the query type.
      x-codeSamples:
        - lang: bash
          label: Simple answer
          source: |
            curl -X POST 'https://api.exa.ai/answer' \
              -H 'x-api-key: YOUR-EXA-API-KEY' \
              -H 'Content-Type: application/json' \
              -d '{
                "query": "What is the latest valuation of SpaceX?",
                "text": true
              }'
        - lang: python
          label: Simple answer
          source: |
            # pip install exa-py
            from exa_py import Exa
            exa = Exa('YOUR_EXA_API_KEY')

            result = exa.answer(
                "What is the latest valuation of SpaceX?",
                text=True
            )

            print(result)
        - lang: javascript
          label: Simple answer
          source: |
            // npm install exa-js
            import Exa from 'exa-js';
            const exa = new Exa('YOUR_EXA_API_KEY');

            const result = await exa.answer(
                'What is the latest valuation of SpaceX?',
                { text: true }
            );

            console.log(result);
        - lang: php
          label: Simple answer
          source: ""
        - lang: go
          label: Simple answer
          source: ""
        - lang: java
          label: Simple answer
          source: ""
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  description: The question or query to answer.
                  example: "What is the latest valuation of SpaceX?"
                  minLength: 1
                stream:
                  type: boolean
                  default: false
                  description: If true, the response is returned as a server-sent events (SSS) stream.
                text:
                  type: boolean
                  default: false
                  description: If true, the response includes full text content in the search results
                outputSchema:
                  type: object
                  description: >-
                    A [JSON Schema Draft 7](https://json-schema.org/draft-07) specification
                    for the desired answer structure. When provided, the answer will be
                    returned as a structured object matching the schema instead of a plain string.
                  properties:
                    type:
                      type: string
                      description: The root schema type (typically "object").
                      example: "object"
                    properties:
                      type: object
                      description: >-
                        An object where each key is a property name and each value is
                        a JSON Schema describing that property (with `type`, `description`, etc).
                    required:
                      type: array
                      items:
                        type: string
                      description: List of required property names.
                    description:
                      type: string
                      description: A description of the schema.
                    additionalProperties:
                      type: boolean
                      description: Whether to allow properties not listed in `properties`.
                      default: false
      responses:
        "200":
          $ref: "#/components/responses/AnswerResponse"
  /research/v0/tasks:
    post:
      operationId: research-tasks-create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                instructions:
                  type: string
                  maxLength: 4096
                  description: Instructions for what the research task should accomplish
                model:
                  type: string
                  enum:
                    - exa-research
                    - exa-research-pro
                  default: exa-research
                output:
                  type: object
                  properties:
                    schema:
                      description: >-
                        A JsonSchema specification of the desired output. See
                        https://json-schema.org/draft-07.
                    inferSchema:
                      type: boolean
                      description: When set to true and no output schema is provided, an LLM will generate an output schema.
              required:
                - instructions
              example:
                instructions: "What species of ant are similar to honeypot ants?"
                model: "exa-research"
                output:
                  schema:
                    type: "object"
                    properties:
                      answer:
                        type: "string"
      responses:
        "201":
          $ref: "#/components/responses/ResearchCreateTaskResponse"
      summary: Create a research task with instructions and an output schema
      tags: &ref_0
        - Research
    get:
      operationId: research-tasks-list
      parameters:
        - name: cursor
          required: false
          in: query
          description: The cursor to paginate through the results
          schema:
            minLength: 1
            type: string
        - name: limit
          required: false
          in: query
          description: The number of results to return
          schema:
            minimum: 1
            maximum: 200
            default: 25
            type: number
      responses:
        "200":
          $ref: "#/components/responses/ListResearchTasksResponse"
      summary: List research tasks
      tags: *ref_0
  /research/v0/tasks/{id}:
    get:
      operationId: ResearchControllerV0_getResearchTask
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        "200":
          $ref: "#/components/responses/ResearchTaskResponse"
      summary: Get a research task by id
      tags: *ref_0
components:
  securitySchemes:
    apikey:
      type: apiKey
      name: x-api-key
      in: header
      description: API key can be provided either via x-api-key header or Authorization header with Bearer scheme
    bearer:
      type: http
      scheme: bearer
      description: API key can be provided either via x-api-key header or Authorization header with Bearer scheme
  schemas:
    AnswerCitation:
      type: object
      properties:
        id:
          type: string
          description: The temporary ID for the document.
          example: "https://www.theguardian.com/science/2024/dec/11/spacex-valued-at-350bn-as-company-agrees-to-buy-shares-from-employees"
        url:
          type: string
          format: uri
          description: The URL of the search result.
          example: "https://www.theguardian.com/science/2024/dec/11/spacex-valued-at-350bn-as-company-agrees-to-buy-shares-from-employees"
        title:
          type: string
          description: The title of the search result.
          example: "SpaceX valued at $350bn as company agrees to buy shares from ..."
        author:
          type:
            - string
            - "null"
          description: If available, the author of the content.
          example: "Dan Milmon"
        publishedDate:
          type:
            - string
            - "null"
          description: An estimate of the creation date, from parsing HTML content. Format is YYYY-MM-DD.
          example: "2023-11-16T01:36:32.547Z"
        text:
          type: string
          description: The full text content of each source. Only present when includeText is enabled.
          example: "SpaceX valued at $350bn as company agrees to buy shares from ..."
        image:
          type: string
          format: uri
          description: The URL of the image associated with the search result, if available.
          example: "https://i.guim.co.uk/img/media/7cfee7e84b24b73c97a079c402642a333ad31e77/0_380_6176_3706/master/6176.jpg?width=1200&height=630&quality=85&auto=format&fit=crop&overlay-align=bottom%2Cleft&overlay-width=100p&overlay-base64=L2ltZy9zdGF0aWMvb3ZlcmxheXMvdGctZGVmYXVsdC5wbmc&enable=upscale&s=71ebb2fbf458c185229d02d380c01530"
        favicon:
          type: string
          format: uri
          description: The URL of the favicon for the search result's domain, if available.
          example: "https://assets.guim.co.uk/static/frontend/icons/homescreen/apple-touch-icon.svg"
    AnswerResult:
      type: object
      properties:
        answer:
          oneOf:
            - type: string
            - type: object
              additionalProperties: {}
          description: >-
            The generated answer based on search results. Returns a string by
            default, or a structured object matching the provided outputSchema.
          example: "$350 billion."
        citations:
          type: array
          description: Search results used to generate the answer.
          items:
            $ref: "#/components/schemas/AnswerCitation"
    ContentsRequest:
      type: object
      properties:
        text:
          oneOf:
            - type: boolean
              title: "Simple text retrieval"
              description: If true, returns full page text with default settings. If false, disables text return.
            - type: object
              title: "Advanced text options"
              description: Advanced options for controlling text extraction. Use this when you need to limit text length or include HTML structure.
              properties:
                maxCharacters:
                  type: integer
                  description: Maximum character limit for the full page text. Useful for controlling response size and API costs.
                  example: 1000
                includeHtmlTags:
                  type: boolean
                  default: false
                  description: Include HTML tags in the response, which can help LLMs understand text structure and formatting.
                  example: false
                verbosity:
                  type: string
                  enum: ["compact", "standard", "full"]
                  default: "compact"
                  description: |
                    Controls the verbosity level of returned content. Requires livecrawl: "always" to take effect.
                    - compact: Most concise output, main content only (default)
                    - standard: Balanced content with more detail
                    - full: Complete content including all sections
                  example: "standard"
                includeSections:
                  type: array
                  items:
                    type: string
                    enum:
                      [
                        "header",
                        "navigation",
                        "banner",
                        "body",
                        "sidebar",
                        "footer",
                        "metadata",
                      ]
                  description: |
                    Only include content from these semantic page sections. Requires livecrawl: "always" to take effect.
                  example: ["body", "header"]
                excludeSections:
                  type: array
                  items:
                    type: string
                    enum:
                      [
                        "header",
                        "navigation",
                        "banner",
                        "body",
                        "sidebar",
                        "footer",
                        "metadata",
                      ]
                  description: |
                    Exclude content from these semantic page sections. Requires livecrawl: "always" to take effect.
                  example: ["navigation", "footer", "sidebar"]
        highlights:
          oneOf:
            - type: boolean
              title: "Simple highlights retrieval"
              description: If true, returns highlights with default settings. If false, disables highlights.
            - type: object
              title: "Advanced highlights options"
              description: Advanced options for controlling highlight extraction. Use this when you need to customize the number of sentences, highlights per URL, or provide a custom query.
              properties:
                maxCharacters:
                  type: integer
                  minimum: 1
                  description: Maximum number of characters to return for highlights. Controls the total length of highlight text returned per URL.
                  example: 2000
                numSentences:
                  type: integer
                  minimum: 1
                  description: "Deprecated: use maxCharacters instead. The number of sentences to return for each snippet."
                  example: 1
                  deprecated: true
                highlightsPerUrl:
                  type: integer
                  minimum: 1
                  description: "Deprecated: use maxCharacters instead. The number of snippets to return for each result."
                  deprecated: true
                query:
                  type: string
                  description: Custom query to direct the LLM's selection of highlights.
                  example: "Key advancements"
          description: Text snippets the LLM identifies as most relevant from each page.
        summary:
          type: object
          description: Summary of the webpage
          properties:
            query:
              type: string
              description: Custom query for the LLM-generated summary.
              example: "Main developments"
            schema:
              type: object
              description: |
                JSON schema for structured output from summary. 
                See https://json-schema.org/overview/what-is-jsonschema for JSON Schema documentation.
              example:
                {
                  "$schema": "http://json-schema.org/draft-07/schema#",
                  "title": "Title",
                  "type": "object",
                  "properties":
                    {
                      "Property 1":
                        { "type": "string", "description": "Description" },
                      "Property 2":
                        {
                          "type": "string",
                          "enum": ["option 1", "option 2", "option 3"],
                          "description": "Description",
                        },
                    },
                  "required": ["Property 1"],
                }
        livecrawl:
          type: string
          enum: [never, fallback, preferred, always]
          deprecated: true
          description: |
            **Deprecated**: Use `maxAgeHours` instead for more precise control over content freshness.

            Options for livecrawling pages.
            'never': Disable livecrawling (default for neural search).
            'fallback': Livecrawl when cache is empty.
            'preferred': Always try to livecrawl, but fall back to cache if crawling fails.
            'always': Always live-crawl, never use cache. Only use if you cannot tolerate any cached content. This option is not recommended unless consulted with the Exa team.
          example: "preferred"
        livecrawlTimeout:
          type: integer
          default: 10000
          description: The timeout for livecrawling in milliseconds.
          example: 1000
        maxAgeHours:
          type: integer
          description: |
            Maximum age of cached content in hours. Controls when livecrawling is triggered based on content freshness.
            - Positive value (e.g. 24): Use cached content if it's less than this many hours old, otherwise livecrawl.
            - 0: Always livecrawl, never use cache.
            - -1: Never livecrawl, always use cache.
            - Omit (default): Livecrawl as fallback only when no cached content exists.
          example: 24
        subpages:
          type: integer
          default: 0
          description: The number of subpages to crawl. The actual number crawled may be limited by system constraints.
          example: 1
        subpageTarget:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: Keyword to find specific subpages of search results. Can be a single string or an array of strings, comma delimited.
          example: "sources"
        extras:
          type: object
          description: Extra parameters to pass.
          properties:
            links:
              type: integer
              default: 0
              description: Number of URLs to return from each webpage.
              example: 1
            imageLinks:
              type: integer
              default: 0
              description: Number of images to return for each result.
              example: 1
        context:
          oneOf:
            - type: boolean
              deprecated: true
              description: "Deprecated: Use highlights or text instead. Returns page contents as a combined context string."
              example: true
            - type: object
              deprecated: true
              description: "Deprecated: Use highlights or text instead. Returns page contents as a combined context string."
              properties:
                maxCharacters:
                  type: integer
                  description: "Deprecated. Maximum character limit for the context string."
                  example: 10000

    CommonRequest:
      type: object
      properties:
        numResults:
          type: integer
          maximum: 100
          default: 10
          minimum: 1
          description: Number of results to return (up to thousands of results available for custom plans)
          example: 10
        includeDomains:
          type: array
          items:
            type: string
          description: List of domains to include in the search. If specified, results will only come from these domains.
          example:
            - arxiv.org
            - paperswithcode.com
        excludeDomains:
          type: array
          items:
            type: string
          description: List of domains to exclude from search results. If specified, no results will be returned from these domains.
        startCrawlDate:
          type: string
          format: date-time
          description: Crawl date refers to the date that Exa discovered a link. Results will include links that were crawled after this date. Must be specified in ISO 8601 format.
          example: 2023-01-01
        endCrawlDate:
          type: string
          format: date-time
          description: Crawl date refers to the date that Exa discovered a link. Results will include links that were crawled before this date. Must be specified in ISO 8601 format.
          example: 2023-12-31
        startPublishedDate:
          type: string
          format: date-time
          description: Only links with a published date after this will be returned. Must be specified in ISO 8601 format.
          example: 2023-01-01
        endPublishedDate:
          type: string
          format: date-time
          description: Only links with a published date before this will be returned. Must be specified in ISO 8601 format.
          example: 2023-12-31
        includeText:
          type: array
          items:
            type: string
          description: List of strings that must be present in webpage text of results. Currently, only 1 string is supported, of up to 5 words.
          example:
            - large language model
        excludeText:
          type: array
          items:
            type: string
          description: List of strings that must not be present in webpage text of results. Currently, only 1 string is supported, of up to 5 words. Checks from the first 1000 words of the webpage text.
          example:
            - course
        context:
          oneOf:
            - type: boolean
              deprecated: true
              description: "Deprecated: Use highlights or text instead. Returns page contents as a combined context string."
              example: true
            - type: object
              deprecated: true
              description: "Deprecated: Use highlights or text instead. Returns page contents as a combined context string."
              properties:
                maxCharacters:
                  type: integer
                  description: "Deprecated. Maximum character limit for the context string."
                  example: 10000

        moderation:
          type: boolean
          default: false
          description: Enable content moderation to filter unsafe content from search results.
          example: true
        contents:
          $ref: "#/components/schemas/ContentsRequest"

    EntityCompanyPropertiesWorkforce:
      type: object
      description: Company workforce information.
      properties:
        total:
          type:
            - integer
            - "null"
          description: Total number of employees.
          example: 500

    EntityCompanyPropertiesHeadquarters:
      type: object
      description: Company headquarters information.
      properties:
        address:
          type:
            - string
            - "null"
          description: Street address.
          example: "123 Main St"
        city:
          type:
            - string
            - "null"
          description: City name.
          example: "San Francisco"
        postalCode:
          type:
            - string
            - "null"
          description: Postal/ZIP code.
          example: "94105"
        country:
          type:
            - string
            - "null"
          description: Full country name.
          example: "United States"

    EntityCompanyPropertiesFundingRound:
      type: object
      description: Funding round information.
      properties:
        name:
          type:
            - string
            - "null"
          description: Name of the funding round (e.g., "Series A", "Seed").
          example: "Series B"
        date:
          type:
            - string
            - "null"
          description: Date of the funding round.
          example: "2023-06-15"
        amount:
          type:
            - integer
            - "null"
          description: Amount raised in USD.
          example: 50000000

    EntityCompanyPropertiesFinancials:
      type: object
      description: Company financial information.
      properties:
        revenueAnnual:
          type:
            - integer
            - "null"
          description: Annual revenue in USD.
          example: 1000000000
        fundingTotal:
          type:
            - integer
            - "null"
          description: Total funding raised in USD.
          example: 500000000
        fundingLatestRound:
          oneOf:
            - $ref: "#/components/schemas/EntityCompanyPropertiesFundingRound"
            - type: "null"

    EntityCompanyPropertiesWebTraffic:
      type: object
      description: Company web traffic information.
      properties:
        visitsMonthly:
          type:
            - integer
            - "null"
          description: Estimated monthly website visits.
          example: 266306714

    EntityCompanyProperties:
      type: object
      description: Structured properties for a company entity.
      properties:
        name:
          type:
            - string
            - "null"
          description: Company name.
          example: "Exa"
        foundedYear:
          type:
            - integer
            - "null"
          description: Year the company was founded.
          example: 2022
        description:
          type:
            - string
            - "null"
          description: Brief description of the company.
          example: "AI-powered search engine"
        workforce:
          oneOf:
            - $ref: "#/components/schemas/EntityCompanyPropertiesWorkforce"
            - type: "null"
        headquarters:
          oneOf:
            - $ref: "#/components/schemas/EntityCompanyPropertiesHeadquarters"
            - type: "null"
        financials:
          oneOf:
            - $ref: "#/components/schemas/EntityCompanyPropertiesFinancials"
            - type: "null"
        webTraffic:
          oneOf:
            - $ref: "#/components/schemas/EntityCompanyPropertiesWebTraffic"
            - type: "null"

    EntityDateRange:
      type: object
      description: Date range for work history entries.
      properties:
        from:
          type:
            - string
            - "null"
          description: Start date (YYYY-MM-DD format).
          example: "2020-01-15"
        to:
          type:
            - string
            - "null"
          description: End date (YYYY-MM-DD format).
          example: "2023-06-30"

    EntityPersonPropertiesCompanyRef:
      type: object
      description: Reference to a company in work history.
      properties:
        id:
          type:
            - string
            - "null"
          description: Exa entity ID for the company.
          example: "https://exa.ai/library/company/exa"
        name:
          type:
            - string
            - "null"
          description: Company name.
          example: "Exa"

    EntityPersonPropertiesWorkHistoryEntry:
      type: object
      description: A single work history entry for a person.
      properties:
        title:
          type:
            - string
            - "null"
          description: Job title.
          example: "Software Engineer"
        location:
          type:
            - string
            - "null"
          description: Work location.
          example: "San Francisco, CA"
        dates:
          oneOf:
            - $ref: "#/components/schemas/EntityDateRange"
            - type: "null"
        company:
          oneOf:
            - $ref: "#/components/schemas/EntityPersonPropertiesCompanyRef"
            - type: "null"

    EntityPersonProperties:
      type: object
      description: Structured properties for a person entity.
      properties:
        name:
          type:
            - string
            - "null"
          description: Person's full name.
          example: "John Doe"
        location:
          type:
            - string
            - "null"
          description: Person's location.
          example: "San Francisco, CA"
        workHistory:
          type: array
          description: List of work history entries.
          items:
            $ref: "#/components/schemas/EntityPersonPropertiesWorkHistoryEntry"

    CompanyEntity:
      type: object
      description: Structured entity data for a company.
      required:
        - id
        - type
        - version
        - properties
      properties:
        id:
          type: string
          description: Exa entity ID.
          example: "https://exa.ai/library/company/exa"
        type:
          type: string
          enum: [company]
          description: Entity type discriminator.
          example: "company"
        version:
          type: integer
          description: Schema version number.
          example: 1
        properties:
          $ref: "#/components/schemas/EntityCompanyProperties"

    PersonEntity:
      type: object
      description: Structured entity data for a person.
      required:
        - id
        - type
        - version
        - properties
      properties:
        id:
          type: string
          description: Exa entity ID.
          example: "https://exa.ai/library/person/john-doe"
        type:
          type: string
          enum: [person]
          description: Entity type discriminator.
          example: "person"
        version:
          type: integer
          description: Schema version number.
          example: 1
        properties:
          $ref: "#/components/schemas/EntityPersonProperties"

    Entity:
      oneOf:
        - $ref: "#/components/schemas/CompanyEntity"
        - $ref: "#/components/schemas/PersonEntity"
      discriminator:
        propertyName: type
        mapping:
          company: "#/components/schemas/CompanyEntity"
          person: "#/components/schemas/PersonEntity"
      description: Structured entity data for company or person search results. Only returned for category=company or category=people searches.

    Result:
      type: object
      properties:
        title:
          type: string
          description: The title of the search result.
          example: "A Comprehensive Overview of Large Language Models"
        url:
          type: string
          format: uri
          description: The URL of the search result.
          example: "https://arxiv.org/pdf/2307.06435.pdf"
        publishedDate:
          type:
            - string
            - "null"
          description: An estimate of the creation date, from parsing HTML content. Format is YYYY-MM-DD.
          example: "2023-11-16T01:36:32.547Z"
        author:
          type:
            - string
            - "null"
          description: If available, the author of the content.
          example: "Humza  Naveed, University of Engineering and Technology (UET), Lahore, Pakistan"
        score:
          type:
            - number
            - "null"
          description: A number from 0 to 1 representing similarity between the query/url and the result.
          example: 0.4600165784358978
        id:
          type: string
          description: The temporary ID for the document. Useful for /contents endpoint.
          example: "https://arxiv.org/abs/2307.06435"
        image:
          type: string
          format: uri
          description: The URL of an image associated with the search result, if available.
          example: "https://arxiv.org/pdf/2307.06435.pdf/page_1.png"
        favicon:
          type: string
          format: uri
          description: The URL of the favicon for the search result's domain.
          example: "https://arxiv.org/favicon.ico"

    ResultWithContent:
      allOf:
        - $ref: "#/components/schemas/Result"
        - type: object
          properties:
            text:
              type: string
              description: The full content text of the search result.
              example: "Abstract Large Language Models (LLMs) have recently demonstrated remarkable capabilities..."
            highlights:
              type: array
              items:
                type: string
              description: Array of highlights extracted from the search result content.
              example:
                - "Such requirements have limited their adoption..."
            highlightScores:
              type: array
              items:
                type: number
                format: float
              description: Array of cosine similarity scores for each highlighted
              example: [0.4600165784358978]
            summary:
              type: string
              description: Summary of the webpage
              example: "This overview paper on Large Language Models (LLMs) highlights key developments..."
            subpages:
              type: array
              items:
                $ref: "#/components/schemas/ResultWithContent"
              description: Array of subpages for the search result.
              example:
                [
                  {
                    "id": "https://arxiv.org/abs/2303.17580",
                    "url": "https://arxiv.org/pdf/2303.17580.pdf",
                    "title": "HuggingGPT: Solving AI Tasks with ChatGPT and its Friends in Hugging Face",
                    "author": "Yongliang  Shen, Microsoft Research Asia, Kaitao  Song, Microsoft Research Asia, Xu  Tan, Microsoft Research Asia, Dongsheng  Li, Microsoft Research Asia, Weiming  Lu, Microsoft Research Asia, Yueting  Zhuang, Microsoft Research Asia, yzhuang@zju.edu.cn, Zhejiang  University, Microsoft Research Asia, Microsoft  Research, Microsoft Research Asia",
                    "publishedDate": "2023-11-16T01:36:20.486Z",
                    "text": "HuggingGPT: Solving AI Tasks with ChatGPT and its Friends in Hugging Face Date Published: 2023-05-25 Authors: Yongliang Shen, Microsoft Research Asia Kaitao Song, Microsoft Research Asia Xu Tan, Microsoft Research Asia Dongsheng Li, Microsoft Research Asia Weiming Lu, Microsoft Research Asia Yueting Zhuang, Microsoft Research Asia, yzhuang@zju.edu.cn Zhejiang University, Microsoft Research Asia Microsoft Research, Microsoft Research Asia Abstract Solving complicated AI tasks with different domains and modalities is a key step toward artificial general intelligence. While there are abundant AI models available for different domains and modalities, they cannot handle complicated AI tasks. Considering large language models (LLMs) have exhibited exceptional ability in language understanding, generation, interaction, and reasoning, we advocate that LLMs could act as a controller to manage existing AI models to solve complicated AI tasks and language could be a generic interface to empower t",
                    "summary": "HuggingGPT is a framework using ChatGPT as a central controller to orchestrate various AI models from Hugging Face to solve complex tasks. ChatGPT plans the task, selects appropriate models based on their descriptions, executes subtasks, and summarizes the results. This approach addresses limitations of LLMs by allowing them to handle multimodal data (vision, speech) and coordinate multiple models for complex tasks, paving the way for more advanced AI systems.",
                    "highlights":
                      [
                        "2) Recently, some researchers started to investigate the integration of using tools or models in LLMs  .",
                      ],
                    "highlightScores": [0.32679107785224915],
                  },
                ]
            extras:
              type: object
              description: Results from extras.
              properties:
                links:
                  type: array
                  items:
                    type: string
                  description: Array of links from the search result.
                  example: []
            entities:
              type: array
              description: Structured entity data for company or person search results. Only returned for category=company or category=people searches.
              items:
                $ref: "#/components/schemas/Entity"

    CostDollars:
      type: object
      properties:
        total:
          type: number
          format: float
          description: Total dollar cost for your request
          example: 0.005
        breakDown:
          type: array
          description: Breakdown of costs by operation type
          items:
            type: object
            properties:
              search:
                type: number
                format: float
                description: Cost of your search operations
                example: 0.005
              contents:
                type: number
                format: float
                description: Cost of your content operations
                example: 0
              breakdown:
                type: object
                properties:
                  neuralSearch:
                    type: number
                    format: float
                    description: Cost of your neural search operations
                    example: 0.005
                  deepSearch:
                    type: number
                    format: float
                    description: Cost of your deep search operations
                    example: 0.015
                  contentText:
                    type: number
                    format: float
                    description: Cost of your text content retrieval
                    example: 0
                  contentHighlight:
                    type: number
                    format: float
                    description: Cost of your highlight generation
                    example: 0
                  contentSummary:
                    type: number
                    format: float
                    description: Cost of your summary generation
                    example: 0
        perRequestPrices:
          type: object
          description: Standard price per request for different operations
          properties:
            neuralSearch_1_25_results:
              type: number
              format: float
              description: Standard price for neural search with 1-25 results
              example: 0.005
            neuralSearch_26_100_results:
              type: number
              format: float
              description: Standard price for neural search with 26-100 results
              example: 0.025
            neuralSearch_100_plus_results:
              type: number
              format: float
              description: Standard price for neural search with 100+ results
              example: 1
            deepSearch_1_25_results:
              type: number
              format: float
              description: Standard price for deep search with 1-25 results
              example: 0.015
            deepSearch_26_100_results:
              type: number
              format: float
              description: Standard price for deep search with 26-100 results
              example: 0.075
        perPagePrices:
          type: object
          description: Standard price per page for different content operations
          properties:
            contentText:
              type: number
              format: float
              description: Standard price per page for text content
              example: 0.001
            contentHighlight:
              type: number
              format: float
              description: Standard price per page for highlights
              example: 0.001
            contentSummary:
              type: number
              format: float
              description: Standard price per page for summaries
              example: 0.001

    ResearchTaskDto:
      type:
        - object
      properties:
        id:
          type:
            - string
          description: The unique identifier for the research task
        status:
          type:
            - string
          enum:
            - running
            - completed
            - failed
          description: The current status of the research task
        instructions:
          type:
            - string
          description: The instructions or query for the research task
        schema:
          type:
            - object
          additionalProperties: {}
          description: The JSON schema specification for the expected output format
        data:
          type:
            - object
          additionalProperties: {}
          description: The research results data conforming to the specified schema
        citations:
          type:
            - object
          additionalProperties:
            type:
              - array
            items:
              type:
                - object
              properties:
                id:
                  type:
                    - string
                url:
                  type:
                    - string
                title:
                  type:
                    - string
                snippet:
                  type:
                    - string
              required:
                - id
                - url
                - snippet
          description: Citations grouped by the root field they were used in
      required:
        - id
        - status
        - instructions
  responses:
    SearchResponse:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              requestId:
                type: string
                description: Unique identifier for the request
                example: "b5947044c4b78efa9552a7c89b306d95"
              results:
                type: array
                description: A list of search results containing title, URL, published date, and author.
                items:
                  $ref: "#/components/schemas/ResultWithContent"
              searchType:
                type: string
                enum: [neural, deep, deep-reasoning]
                description: For auto searches, indicates which search type was selected.
                example: "auto"
              context:
                type: string
                description: "Deprecated. Combined context string from search results. Use highlights or text instead."
              output:
                type: object
                description: Deep-search synthesized output. Returned for deep search variants.
                properties:
                  content:
                    oneOf:
                      - type: string
                      - type: object
                        additionalProperties: {}
                    description: Deep-search synthesized content. String by default, or object when outputSchema is provided.
                  grounding:
                    type: array
                    description: Field-level grounding for synthesized output.
                    items:
                      type: object
                      required:
                        - field
                        - citations
                        - confidence
                      properties:
                        field:
                          type: string
                          description: Field path in output.content (for example, content or companies[0].funding).
                        citations:
                          type: array
                          description: Sources supporting this output field.
                          items:
                            type: object
                            required:
                              - url
                              - title
                            properties:
                              url:
                                type: string
                              title:
                                type: string
                        confidence:
                          type: string
                          enum: [low, medium, high]
                required:
                  - content
                  - grounding
              costDollars:
                $ref: "#/components/schemas/CostDollars"

    FindSimilarResponse:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              requestId:
                type: string
                description: Unique identifier for the request
                example: "c6958155d5c89ffa0663b7c90c407396"
              context:
                type: string
                description: "Deprecated. Combined context string from search results. Use highlights or text instead."
              results:
                type: array
                description: A list of search results containing title, URL, published date, and author.
                items:
                  $ref: "#/components/schemas/ResultWithContent"
              costDollars:
                $ref: "#/components/schemas/CostDollars"

    ContentsResponse:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              requestId:
                type: string
                description: Unique identifier for the request
                example: "e492118ccdedcba5088bfc4357a8a125"
              results:
                type: array
                items:
                  $ref: "#/components/schemas/ResultWithContent"
              context:
                type: string
                description: "Deprecated. Combined context string from search results. Use highlights or text instead."
              statuses:
                type: array
                description: Status information for each requested URL
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: The URL that was requested
                      example: "https://example.com"
                    status:
                      type: string
                      enum: ["success", "error"]
                      description: Status of the content fetch operation
                      example: "success"
                    error:
                      type: object
                      nullable: true
                      description: Error details, only present when status is "error"
                      properties:
                        tag:
                          type: string
                          enum:
                            [
                              "CRAWL_NOT_FOUND",
                              "CRAWL_TIMEOUT",
                              "CRAWL_LIVECRAWL_TIMEOUT",
                              "SOURCE_NOT_AVAILABLE",
                              "UNSUPPORTED_URL",
                              "CRAWL_UNKNOWN_ERROR",
                            ]
                          description: Specific error type
                          example: "CRAWL_NOT_FOUND"
                        httpStatusCode:
                          type: integer
                          nullable: true
                          description: The corresponding HTTP status code
                          example: 404
              costDollars:
                $ref: "#/components/schemas/CostDollars"

    AnswerResponse:
      description: OK
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/AnswerResult"
              - type: object
                properties:
                  costDollars:
                    $ref: "#/components/schemas/CostDollars"
        text/event-stream:
          schema:
            type: object
            properties:
              answer:
                type: string
                description: Partial answer chunk when streaming is enabled.
              citations:
                type: array
                items:
                  $ref: "#/components/schemas/AnswerCitation"

    ResearchCreateTaskResponse:
      description: Research task created
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                type: string
                description: The unique identifier for the research task
                example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    ListResearchTasksResponse:
      description: List of research tasks
      content:
        application/json:
          schema:
            type: object
            properties:
              requestId:
                type: string
                description: Unique identifier for the request
                example: "b5947044c4b78efa9552a7c89b306d95"
              data:
                type: array
                items:
                  $ref: "#/components/schemas/ResearchTaskDto"
                description: The list of research tasks
              hasMore:
                type: boolean
                description: Whether there are more results to paginate through
              nextCursor:
                type: string
                nullable: true
                description: The cursor to paginate through the next set of results
    ResearchTaskResponse:
      description: Research task details
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ResearchTaskDto"