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". 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
                      description: The type of search. Neural uses an embeddings-based model, auto (default) intelligently combines available search methods, fast uses streamlined versions of the neural model, and deep provides comprehensive search with query expansion and detailed context.
                      example: "auto"
                      default: "auto"
                    category:
                      type: string
                      enum:
                        - company
                        - research paper
                        - news
                        - pdf
                        - github
                        - tweet
                        - personal site
                        - people
                        - financial report
                      description: A data category to focus on.
                      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.
                  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
      responses:
        "200":
          $ref: "#/components/responses/AnswerResponse"
  /research/v1:
    get:
      description: Get a paginated list of research requests
      operationId: ResearchController_listResearch
      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: 50
            default: 10
            type: number
      responses:
        '200':
          description: List of research requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResearchResponseDto'
      summary: List research requests
      tags: &ref_0
        - Research
    post:
      operationId: ResearchController_createResearch
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResearchCreateRequestDtoClass'
      responses:
        '201':
          description: Research request created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResearchDtoClass'
      summary: Create a new research request
      tags: *ref_0
  /research/v1/{researchId}:
    get:
      description: Retrieve research by ID. Add ?stream=true for real-time SSE updates.
      operationId: ResearchController_getResearch
      parameters:
        - name: researchId
          required: true
          in: path
          schema:
            type: string
        - name: stream
          required: true
          in: query
          schema:
            type: string
        - name: events
          required: true
          in: query
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResearchDtoClass'
      summary: Get a research request 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
          nullable: true
          description: If available, the author of the content.
          example: "Dan Milmon"
        publishedDate:
          type: string
          nullable: true
          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:
          type: string
          description: The generated answer based on search results.
          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
        highlights:
          type: object
          description: Text snippets the LLM identifies as most relevant from each page. We recommend you using context instead of highlights for LLMs.
          properties:
            numSentences:
              type: integer
              minimum: 1
              description: The number of sentences to return for each snippet.
              example: 1
            highlightsPerUrl:
              type: integer
              minimum: 1
              description: The number of snippets to return for each result.
              example: 1
            query:
              type: string
              description: Custom query to direct the LLM's selection of highlights.
              example: "Key advancements"
        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, always, preferred]
          description: |
            Options for livecrawling pages.
            'never': Disable livecrawling (default for neural search).
            'fallback': Livecrawl when cache is empty.
            'always': Always livecrawl.
            'preferred': Always try to livecrawl, but fall back to cache if crawling fails.
          example: "always"
        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
              description: Return page contents as a context string for LLM. When true, combines all result contents into one string. Context strings often perform better than highlights for LLMs.
              example: true
            - type: object
              description: Return page contents as a context string for LLM. When true, combines all result contents into one string. Context strings often perform better than highlights for LLMs.
              properties:
                maxCharacters:
                  type: integer
                  description: Maximum character limit.
                  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
              description: Return page contents as a context string for LLM. When true, combines all result contents into one string. Context strings often perform better than highlights for LLMs.
              example: true
            - type: object
              description: Return page contents as a context string for LLM. When true, combines all result contents into one string. Context strings often perform better than highlights for LLMs.
              properties:
                maxCharacters:
                  type: integer
                  description: Maximum character limit.
                  example: 10000

        contents:
          $ref: "#/components/schemas/ContentsRequest"

    EntityCompanyPropertiesWorkforce:
      type: object
      description: Company workforce information.
      properties:
        total:
          type: integer
          nullable: true
          description: Total number of employees.
          example: 500

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

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

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

    EntityCompanyPropertiesWebTraffic:
      type: object
      description: Company web traffic information.
      properties:
        visitsMonthly:
          type: integer
          nullable: true
          description: Estimated monthly website visits.
          example: 266306714

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

    EntityDateRange:
      type: object
      description: Date range for work history entries.
      properties:
        from:
          type: string
          nullable: true
          description: Start date (YYYY-MM-DD format).
          example: "2020-01-15"
        to:
          type: string
          nullable: true
          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
          nullable: true
          description: Exa entity ID for the company.
          example: "https://exa.ai/library/company/exa"
        name:
          type: string
          nullable: true
          description: Company name.
          example: "Exa"

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

    EntityPersonProperties:
      type: object
      description: Structured properties for a person entity.
      properties:
        name:
          type: string
          nullable: true
          description: Person's full name.
          example: "John Doe"
        location:
          type: string
          nullable: true
          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
          nullable: true
          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
          nullable: true
          description: If available, the author of the content.
          example: "Humza  Naveed, University of Engineering and Technology (UET), Lahore, Pakistan"
        score:
          type: number
          nullable: true
          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

    ListResearchResponseDto:
      type:
        - object
      properties:
        data:
          type:
            - array
          items:
            discriminator:
              propertyName: status
            examples: &ref_1
              - researchId: 01jszdfs0052sg4jc552sg4jc5
                model: exa-research
                instructions: What species of ant are similar to honeypot ants?
                status: running
              - researchId: 01jszdfs0052sg4jc552sg4jc5
                model: exa-research
                instructions: What species of ant are similar to honeypot ants?
                status: completed
                output: Melophorus bagoti
            $ref: '#/components/schemas/ResearchDtoClass'
          description: The list of research requests
        hasMore:
          type:
            - boolean
          description: Whether there are more results to paginate through
        nextCursor:
          type:
            - string
            - 'null'
          description: The cursor to paginate through the next set of results
      required:
        - data
        - hasMore
        - nextCursor
    ResearchCreateRequestDtoClass:
      type:
        - object
      properties:
        model:
          default: exa-research
          type:
            - string
          enum:
            - exa-research
            - exa-research-pro
        instructions:
          type:
            - string
          maxLength: 4096
          description: Instructions for what research should be conducted
        outputSchema:
          type:
            - object
          additionalProperties: {}
      required:
        - instructions
      examples:
        - model: exa-research
          instructions: What species of ant are similar to honeypot ants?
    ResearchDtoClass:
      discriminator:
        propertyName: status
      oneOf:
        - type:
            - object
          properties:
            researchId:
              type:
                - string
              description: The unique identifier for the research request
            createdAt:
              type:
                - number
              description: Milliseconds since epoch time
            model:
              default: exa-research
              type:
                - string
              enum:
                - exa-research
                - exa-research-pro
              description: The model used for the research request
            instructions:
              type:
                - string
              description: The instructions given to this research request
            status:
              type:
                - string
              enum:
                - pending
          required:
            - researchId
            - createdAt
            - instructions
            - status
        - type:
            - object
          properties:
            researchId:
              type:
                - string
              description: The unique identifier for the research request
            createdAt:
              type:
                - number
              description: Milliseconds since epoch time
            model:
              default: exa-research
              type:
                - string
              enum:
                - exa-research
                - exa-research-pro
              description: The model used for the research request
            instructions:
              type:
                - string
              description: The instructions given to this research request
            status:
              type:
                - string
              enum:
                - running
            events:
              type:
                - array
              items:
                $ref: '#/components/schemas/ResearchEventDtoClass'
          required:
            - researchId
            - createdAt
            - instructions
            - status
        - type:
            - object
          properties:
            researchId:
              type:
                - string
              description: The unique identifier for the research request
            createdAt:
              type:
                - number
              description: Milliseconds since epoch time
            model:
              default: exa-research
              type:
                - string
              enum:
                - exa-research
                - exa-research-pro
              description: The model used for the research request
            instructions:
              type:
                - string
              description: The instructions given to this research request
            status:
              type:
                - string
              enum:
                - completed
            events:
              type:
                - array
              items:
                $ref: '#/components/schemas/ResearchEventDtoClass'
            output:
              type:
                - object
              properties:
                content:
                  type:
                    - string
                parsed:
                  type:
                    - object
                  additionalProperties: {}
              required:
                - content
            costDollars:
              type:
                - object
              properties:
                total:
                  type:
                    - number
                numSearches:
                  type:
                    - number
                numPages:
                  type:
                    - number
                reasoningTokens:
                  type:
                    - number
              required:
                - total
                - numSearches
                - numPages
                - reasoningTokens
          required:
            - researchId
            - createdAt
            - instructions
            - status
            - output
            - costDollars
        - type:
            - object
          properties:
            researchId:
              type:
                - string
              description: The unique identifier for the research request
            createdAt:
              type:
                - number
              description: Milliseconds since epoch time
            model:
              default: exa-research
              type:
                - string
              enum:
                - exa-research
                - exa-research-pro
              description: The model used for the research request
            instructions:
              type:
                - string
              description: The instructions given to this research request
            status:
              type:
                - string
              enum:
                - canceled
            events:
              type:
                - array
              items:
                $ref: '#/components/schemas/ResearchEventDtoClass'
          required:
            - researchId
            - createdAt
            - instructions
            - status
        - type:
            - object
          properties:
            researchId:
              type:
                - string
              description: The unique identifier for the research request
            createdAt:
              type:
                - number
              description: Milliseconds since epoch time
            model:
              default: exa-research
              type:
                - string
              enum:
                - exa-research
                - exa-research-pro
              description: The model used for the research request
            instructions:
              type:
                - string
              description: The instructions given to this research request
            status:
              type:
                - string
              enum:
                - failed
            events:
              type:
                - array
              items:
                $ref: '#/components/schemas/ResearchEventDtoClass'
            error:
              type:
                - string
              description: A message indicating why the request failed
          required:
            - researchId
            - createdAt
            - instructions
            - status
            - error
      examples: *ref_1
    ResearchOperationDtoClass:
      discriminator:
        propertyName: type
      oneOf:
        - type:
            - object
          properties:
            type:
              type:
                - string
              enum:
                - think
            content:
              type:
                - string
          required:
            - type
            - content
        - type:
            - object
          properties:
            type:
              type:
                - string
              enum:
                - search
            searchType:
              type:
                - string
              enum:
                - neural
                - auto
                - fast
                - deep
            goal:
              type:
                - string
            query:
              type:
                - string
            results:
              type:
                - array
              items:
                type:
                  - object
                properties:
                  url:
                    type:
                      - string
                required:
                  - url
            pageTokens:
              type:
                - number
          required:
            - type
            - searchType
            - query
            - results
            - pageTokens
        - type:
            - object
          properties:
            type:
              type:
                - string
              enum:
                - crawl
            goal:
              type:
                - string
            result:
              type:
                - object
              properties:
                url:
                  type:
                    - string
              required:
                - url
            pageTokens:
              type:
                - number
          required:
            - type
            - result
            - pageTokens
    ResearchEventDtoClass:
      oneOf:
        - discriminator:
            propertyName: eventType
          oneOf:
            - type:
                - object
              properties:
                eventType:
                  type:
                    - string
                  enum:
                    - research-definition
                instructions:
                  type:
                    - string
                outputSchema:
                  type:
                    - object
                  additionalProperties: {}
                createdAt:
                  type:
                    - number
                  description: Milliseconds since epoch time
                researchId:
                  type:
                    - string
              required:
                - eventType
                - instructions
                - createdAt
                - researchId
            - type:
                - object
              properties:
                eventType:
                  type:
                    - string
                  enum:
                    - research-output
                output:
                  discriminator:
                    propertyName: outputType
                  oneOf:
                    - type:
                        - object
                      properties:
                        outputType:
                          type:
                            - string
                          enum:
                            - completed
                        costDollars:
                          type:
                            - object
                          properties:
                            total:
                              type:
                                - number
                            numSearches:
                              type:
                                - number
                            numPages:
                              type:
                                - number
                            reasoningTokens:
                              type:
                                - number
                          required:
                            - total
                            - numSearches
                            - numPages
                            - reasoningTokens
                        content:
                          type:
                            - string
                        parsed:
                          type:
                            - object
                          additionalProperties: {}
                      required:
                        - outputType
                        - costDollars
                        - content
                    - type:
                        - object
                      properties:
                        outputType:
                          type:
                            - string
                          enum:
                            - failed
                        error:
                          type:
                            - string
                      required:
                        - outputType
                        - error
                createdAt:
                  type:
                    - number
                  description: Milliseconds since epoch time
                researchId:
                  type:
                    - string
              required:
                - eventType
                - output
                - createdAt
                - researchId
        - discriminator:
            propertyName: eventType
          oneOf:
            - type:
                - object
              properties:
                eventType:
                  type:
                    - string
                  enum:
                    - plan-definition
                planId:
                  type:
                    - string
                createdAt:
                  type:
                    - number
                  description: Milliseconds since epoch time
                researchId:
                  type:
                    - string
              required:
                - eventType
                - planId
                - createdAt
                - researchId
            - type:
                - object
              properties:
                eventType:
                  type:
                    - string
                  enum:
                    - plan-operation
                planId:
                  type:
                    - string
                operationId:
                  type:
                    - string
                data:
                  discriminator:
                    propertyName: type
                  $ref: '#/components/schemas/ResearchOperationDtoClass'
                createdAt:
                  type:
                    - number
                  description: Milliseconds since epoch time
                researchId:
                  type:
                    - string
              required:
                - eventType
                - planId
                - operationId
                - data
                - createdAt
                - researchId
            - type:
                - object
              properties:
                eventType:
                  type:
                    - string
                  enum:
                    - plan-output
                planId:
                  type:
                    - string
                output:
                  discriminator:
                    propertyName: outputType
                  oneOf:
                    - type:
                        - object
                      properties:
                        outputType:
                          type:
                            - string
                          enum:
                            - tasks
                        reasoning:
                          type:
                            - string
                        tasksInstructions:
                          type:
                            - array
                          items:
                            type:
                              - string
                      required:
                        - outputType
                        - reasoning
                        - tasksInstructions
                    - type:
                        - object
                      properties:
                        outputType:
                          type:
                            - string
                          enum:
                            - stop
                        reasoning:
                          type:
                            - string
                      required:
                        - outputType
                        - reasoning
                createdAt:
                  type:
                    - number
                  description: Milliseconds since epoch time
                researchId:
                  type:
                    - string
              required:
                - eventType
                - planId
                - output
                - createdAt
                - researchId
        - discriminator:
            propertyName: eventType
          oneOf:
            - type:
                - object
              properties:
                eventType:
                  type:
                    - string
                  enum:
                    - task-definition
                planId:
                  type:
                    - string
                taskId:
                  type:
                    - string
                instructions:
                  type:
                    - string
                createdAt:
                  type:
                    - number
                  description: Milliseconds since epoch time
                researchId:
                  type:
                    - string
              required:
                - eventType
                - planId
                - taskId
                - instructions
                - createdAt
                - researchId
            - type:
                - object
              properties:
                eventType:
                  type:
                    - string
                  enum:
                    - task-operation
                planId:
                  type:
                    - string
                taskId:
                  type:
                    - string
                operationId:
                  type:
                    - string
                data:
                  discriminator:
                    propertyName: type
                  $ref: '#/components/schemas/ResearchOperationDtoClass'
                createdAt:
                  type:
                    - number
                  description: Milliseconds since epoch time
                researchId:
                  type:
                    - string
              required:
                - eventType
                - planId
                - taskId
                - operationId
                - data
                - createdAt
                - researchId
            - type:
                - object
              properties:
                eventType:
                  type:
                    - string
                  enum:
                    - task-output
                planId:
                  type:
                    - string
                taskId:
                  type:
                    - string
                output:
                  type:
                    - object
                  properties:
                    outputType:
                      type:
                        - string
                      enum:
                        - completed
                    content:
                      type:
                        - string
                  required:
                    - outputType
                    - content
                createdAt:
                  type:
                    - number
                  description: Milliseconds since epoch time
                researchId:
                  type:
                    - string
              required:
                - eventType
                - planId
                - taskId
                - output
                - createdAt
                - researchId
  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, author, and score.
                items:
                  $ref: "#/components/schemas/ResultWithContent"
              searchType:
                type: string
                enum: [neural, deep]
                description: For auto searches, indicates which search type was selected.
                example: "auto"
              context:
                type: string
                description: A formatted string of the search results ready for LLMs.
              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: A formatted string of the search results ready for LLMs.
              results:
                type: array
                description: A list of search results containing title, URL, published date, author, and score.
                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: A formatted string of the search results ready for LLMs.
              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",
                              "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"