OpenAPI Specification

Below is our OpenAPI specification, which provides a complete definition of the Metaphor API.
---
openapi: 3.1.0
info:
  version: 1.0.2
  title: Exa Search API - LATEST
  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
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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - type: object
                  properties:
                    query:
                      type: string
                      example: "Here is an article about the state of search:"
                      description: The query string.
                      default: "Here is an article about the state of search:"
                    useAutoprompt:
                      type: boolean
                      description: If true, your query will be converted to a Exa query. Default false.
                    type:
                      type: string
                      description: The Type of search, 'keyword', 'neural', or 'auto' (auto decides between keyword and neural). Default neural.
                    includeText: 
                      type: array
                      items:
                        type: string
                      description: The 'Phrase Filter' text used to post-process the neural search results and only return phrase filtered results.
                  required:
                    - query
                - $ref: "#/components/schemas/CommonRequest"
            example:
              query: "Here is a new legal-tech startup"
              useAutoprompt: true
              numResults: 5
              type: "neural"
              excludeDomains:
                - "www.linkedin.com"
              includeText:
                - "firm"
              startCrawlDate: "2015-03-01T00:00:00"
              endCrawlDate: "2024-06-24T00:00:00"
              category: "company"
      responses:
        "200":
          $ref: "#/components/responses/SearchResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "408":
          $ref: "#/components/responses/TimeoutError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /findSimilar:
    post:
      operationId: findSimilar
      summary: Find similar
      description: Find similar links to the link provided. Optionally get contents.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - type: object
                  properties:
                    url:
                      type: string
                      example: https://slatestarcodex.com/2014/07/30/meditations-on-moloch/
                      description: The url for which you would like to find similar links
                  required:
                    - url
                - $ref: "#/components/schemas/CommonRequest"

            examples:
              validRequest:
                summary: Valid findSimilar request
                value:
                  contents:
                    text:
                      maxCharacters: 100
                  url: "https://www.lesswrong.com/posts/D7PumeYTDPfBTp3i7/the-waluigi-effect-mega-post"
                  numResults: 5
                  excludeDomains:
                  startCrawlDate: "2023-01-01T00:00:00.000Z"
                  endCrawlDate: "2023-12-31T00:00:00.000Z"
                  startPublishedDate: "2023-01-01T00:00:00.000Z"
                  endPublishedDate: "2023-12-31T00:00:00.000Z"
      responses:
        "200":
          $ref: "#/components/responses/FindSimilarResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "408":
          $ref: "#/components/responses/TimeoutError"
        "429":  
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /contents:
    post:
      summary: Get contents
      operationId: 'getContents'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              allOf:
                - type: object
                  properties:
                    ids:
                      type: array
                      description: Array of document IDs obtained from searches
                      items:
                        type: string
                  required:
                    - ids
                - $ref: '#/components/schemas/ContentsRequest'
            example:
              text:
                maxCharacters: 100
                includeHtmlTags: false
              highlights:
                numSentences: 2
                highlightsPerUrl: 1
                query: "Description"
              ids:
                - "www.legalrobot.com"
                - "www.evenuplaw.com"
                - "www.legalontech.com"
      responses:
        "200":
          $ref: '#/components/responses/ContentsResponse'
        "400":
          $ref: "#/components/responses/BadRequestError"
        "408":
          $ref: "#/components/responses/TimeoutError"
        "429":
          $ref: "#/components/responses/RateLimitError"
        "500":
          $ref: "#/components/responses/InternalServerError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
        
components:
  securitySchemes:
    apikey:
      type: apiKey
      name: x-api-key
      in: header
      description: "An API key that will be supplied in a named header when logged in."
      x-default: "5364cbda-7f88-4683-a3f9-873d55f0bb2e"
  schemas:
    ContentsRequest:
      type: object
      properties:
        text:
          type: object
          description: Parsed contents of the page.
          properties:
            maxCharacters:
              type: integer
              description: Max length in characters for the text returned
            includeHtmlTags:
              type: boolean
              description: Whether HTML tags, which can help the LLM understand structure of text, should be included. Default false
        highlights:
          type: object
          description: Relevant extract(s) from the webpage.
          properties:
            numSentences:
              type: integer
              description: The number of sentences to be returned in each snippet. Default 5
            highlightsPerUrl:
              type: integer
              description: The number of snippets to return per page. Default 1
            query:
              type: string
              description: If specified, targets snippets most relevant to the query. In search, defaults to the search query.
        summary:
          type: object
          description: Summary of the webpage
          properties:
            query:
              type: string
              description: If specified, tries to answer the query in the summary
    CommonRequest:
      type: object
      properties:
        numResults:
          type: integer
          description: Number of search results to return. Default 10. Max 10 for basic
            plans. Up to thousands 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:
            - example.com
            - sample.net
        excludeDomains:
          type: array
          items:
            type: string
          description: List of domains to exclude in the search. If specified, results
            will not include any from these domains.
          example:
            - excludedomain.com
            - excludeme.net
        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.
        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.
        contents:
          $ref: '#/components/schemas/ContentsRequest'
    Result:
      type: object
      properties:
        title:
          type: string
          description: The title of the search result.
        url:
          type: string
          format: uri
          description: The URL of the search result.
        publishedDate:
          type: string
          nullable: true
          description: An estimate of the creation date, from parsing HTML content. Format
            is YYYY-MM-DD.
        author:
          type: string
          nullable: true
          description: If available, the author of the content.
        score:
          type: number
          nullable: true
          description: A number from 0 to 1 representing similarity between the query/url
            and the result.
        id:
          type: string
          description: The temporary ID for the document. Useful for /contents endpoint.
    ResultWithContent:
      allOf:
        - $ref: "#/components/schemas/Result"
        - type: object
          properties:
            text:
              type: string
              description: The full content text of the search result.
            # TODO: think we need to change this
            highlights:
              type: array
              items:
                type: string
              description: Array of highlights extracted from the search result content.
            highlightScores:
              type: array
              items:
                type: number
                format: float
              description: Array of cosine similarity scores for each highlighted
    Error:
      type: object
      properties:
        code:
          type: string
          description: A machine-readable error code.
        message:
          type: string
          description: A human-readable error message.

  responses:

    #Search API response schema and examples
    SearchResponse:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              results:
                type: array
                description: A list of search results containing title, URL, published date,
                  author, and score.
                items:
                  $ref: "#/components/schemas/ResultWithContent"
              autopromptString:
                type: string
                description: The Exa query created by the autoprompt functionality.
              autoDate:
                type: string
                description: If applicable, the date filter intelligently inferred from input queries that have autopropmpt on.
          example:
            autopromptString: "Here is a new legal-tech startup:"
            results:
              - score: 0.20622172951698303
                title: "Know what you sign â¢"
                id: "https://legalrobot.com/"
                url: "https://legalrobot.com/"
                publishedDate: "2022-11-01"
                author: null
              - score: 0.20499876141548157
                title: "EvenUp"
                id: "https://www.evenuplaw.com/"
                url: "https://www.evenuplaw.com/"
                publishedDate: "2023-01-01"
                author: null
              - score: 0.20453940331935883
                title: "Automateâtedious out ofcontract review."
                id: "https://www.legalontech.com/"
                url: "https://www.legalontech.com/"
                publishedDate: "2023-04-01"
                author: null
              - score: 0.20372281968593597
                title: "ChatGPT for Legal Documents"
                id: "https://www.law-pilot.com/"
                url: "https://www.law-pilot.com/"
                publishedDate: "2023-01-01"
                author: null
              - score: 0.20369493961334229
                title: "AI data analysis for law firms"
                id: "https://www.legalyze.ai/"
                url: "https://www.legalyze.ai/"
                publishedDate: "2023-01-01"
                author: null
            requestId: "d8035c28f0e49330ebf14b86c52593bc"

    #FindSimilar API response schema and examples
    FindSimilarResponse:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              results:
                type: array
                description: A list of search results containing title, URL, published date,
                  author, and score.
                items:
                  $ref: "#/components/schemas/ResultWithContent"
          example:
            results:
              - score: 0.8948079943656921
                title: "The Waluigi Effect (mega-post) - AI Alignment Forum"
                id: "https://www.alignmentforum.org/posts/D7PumeYTDPfBTp3i7/the-waluigi-effect-mega-post"
                url: "https://www.alignmentforum.org/posts/D7PumeYTDPfBTp3i7/the-waluigi-effect-mega-post"
                publishedDate: "2023-03-03"
                author: "Cleo Nardo"
                text: "Everyone carries a shadow, and the less it is embodied in the individual's conscious life, the black"
              - score: 0.729297399520874
                title: "The Waluigi Effect"
                id: "https://news.ycombinator.com/item?id=35042431"
                url: "https://news.ycombinator.com/item?id=35042431"
                publishedDate: "2023-03-06"
                author: null
                text: "This is fun to read and think about, but it's also important to keep in mind that this is very light"
              - score: 0.7086403965950012
                title: "Waluigi, Carl Jung, and the Case for Moral AI"
                id: "https://www.wired.com/story/waluigi-effect-generative-artificial-intelligence-morality/"
                url: "https://www.wired.com/story/waluigi-effect-generative-artificial-intelligence-morality/"
                publishedDate: "2023-05-25"
                author: "Condé Nast; Nabeel S Qureshi"
                text: "20th century, the psychoanalyst Carl Jung came up with the concept of the shadow—the human personali"
              - score: 0.6984729766845703
                title: "GPTs are Predictors, not Imitators - AI Alignment Forum"
                id: "https://www.alignmentforum.org/posts/nH4c3Q9t9F3nJ7y8W/gpts-are-predictors-not-imitators"
                url: "https://www.alignmentforum.org/posts/nH4c3Q9t9F3nJ7y8W/gpts-are-predictors-not-imitators"
                publishedDate: "2023-04-08"
                author: "Eliezer Yudkowsky"
                text: "(Related text posted to Twitter; this version is edited and has a more advanced final section.) Imag"
              - score: 0.6897473335266113
                title: "A Gentle Introduction to Hallucinations in Large Language Models - MachineLearningMastery.com"
                id: "https://machinelearningmastery.com/a-gentle-introduction-to-hallucinations-in-large-language-models/"
                url: "https://machinelearningmastery.com/a-gentle-introduction-to-hallucinations-in-large-language-models/"
                publishedDate: "2023-06-01"
                author: "Adrian Tam"
                text: "Large Language Models (LLMs) are known to have 'hallucinations.' This is a behavior in that the mode"
            requestId: "0509c907b3a8fc209a84d25848f4bcc3"

    #Contents API response schema and examples
    ContentsResponse:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              results:
                type: array
                items:
                  $ref: "#/components/schemas/ResultWithContent"
          example:
            autopromptString: "Here is a new legal-tech startup:"
            results:
              - score: 0.20622172951698303
                title: "Know what you sign â¢"
                id: "https://legalrobot.com/"
                url: "https://legalrobot.com/"
                publishedDate: "2022-11-01"
                author: null
              - score: 0.20499876141548157
                title: "EvenUp"
                id: "https://www.evenuplaw.com/"
                url: "https://www.evenuplaw.com/"
                publishedDate: "2023-01-01"
                author: null
              - score: 0.20453940331935883
                title: "Automateâtedious out ofcontract review."
                id: "https://www.legalontech.com/"
                url: "https://www.legalontech.com/"
                publishedDate: "2023-04-01"
                author: null
              - score: 0.20372281968593597
                title: "ChatGPT for Legal Documents"
                id: "https://www.law-pilot.com/"
                url: "https://www.law-pilot.com/"
                publishedDate: "2023-01-01"
                author: null
              - score: 0.20369493961334229
                title: "AI data analysis for law firms"
                id: "https://www.legalyze.ai/"
                url: "https://www.legalyze.ai/"
                publishedDate: "2023-01-01"
                author: null
            requestId: "d8035c28f0e49330ebf14b86c52593bc"



    #Error responses
    BadRequestError:
      description: Bad Request - Check your request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            generalError:
              summary: Bad Request Error
              value:
                requestId: "..."
                error: Bad Request
            invalidIncludeDomains:
              summary: Invalid Include Domains
              value:
                requestId: "..."
                error: "includeDomains must be an array of strings with length > 0 and length <= 100"
            invalidExcludeDomains:
              summary: Invalid Exclude Domains
              value:
                requestId: "..."
                error: "excludeDomains must be an array of strings with length > 0 and length <= 100"
            missingRequiredField:
              summary: Missing Required Field
              value:
                requestId: "..."
                error: "Missing required field: {field}"
            noContentFound:
              summary: No Content Found
              value:
                requestId: "..."
                error: "Could not find any content for the given ids."
            invalidNumResults:
              summary: Invalid Number of Results
              value:
                requestId: "..."
                error: "Invalid numResults. numResults must be greater than 0"
            invalidStartCrawlDate:
              summary: Invalid Start Crawl Date
              value:
                requestId: "..."
                error: "Invalid startCrawlDate. startCrawlDate must be a valid date"
            invalidEndCrawlDate:
              summary: Invalid End Crawl Date
              value:
                requestId: "..."
                error: "Invalid endCrawlDate. endCrawlDate must be a valid date"
            invalidCrawlDateRange:
              summary: Invalid Crawl Date Range
              value:
                requestId: "..."
                error: "Invalid startCrawlDate and endCrawlDate. startCrawlDate must be before endCrawlDate"
            invalidStartPublishedDate:
              summary: Invalid Start Published Date
              value:
                requestId: "..."
                error: "Invalid startPublishedDate. startPublishedDate must be a valid date"
            invalidEndPublishedDate:
              summary: Invalid End Published Date
              value:
                requestId: "..."
                error: "Invalid endPublishedDate. endPublishedDate must be a valid date"
            invalidPublishedDateRange:
              summary: Invalid Published Date Range
              value:
                requestId: "..."
                error: "Invalid startPublishedDate and endPublishedDate. startPublishedDate must be before endPublishedDate"
            invalidDomainSpecification:
              summary: Invalid Domain Specification
              value:
                requestId: "..."
                error: "Invalid includeDomains and excludeDomains. Only one of includeDomains or excludeDomains can be specified"
            invalidIncludeDomainsType:
              summary: Invalid Include Domains Type
              value:
                requestId: "..."
                error: "Invalid includeDomains. includeDomains must be an array"
            invalidExcludeDomainsType:
              summary: Invalid Exclude Domains Type
              value:
                requestId: "..."
                error: "Invalid excludeDomains. excludeDomains must be an array"
            invalidIncludeDomainsContent:
              summary: Invalid Include Domains Content
              value:
                requestId: "..."
                error: "Invalid includeDomains. includeDomains must be an array of nonempty strings."
            invalidExcludeDomainsContent:
              summary: Invalid Exclude Domains Content
              value:
                requestId: "..."
                error: "Invalid excludeDomains. excludeDomains must be an array of strings with length > 0 and length <= 100"
            invalidKeywordSearchDomain:
              summary: Invalid Keyword Search Domain
              value:
                requestId: "..."
                error: "Invalid includeDomains. Only one domain can be specified for keyword search type"
            invalidCategory:
              summary: Invalid Category
              value:
                requestId: "..."
                error: "Invalid category. Currently, the only categories: company, papers, news article, github, tweet, movie, song, personal site, pdf"
            emptyIds:
              summary: Empty IDs
              value:
                requestId: "..."
                error: "For contents requests, ids must not be empty"
            invalidQuery:
              summary: Invalid Query
              value:
                requestId: "..."
                error: "Invalid query. query must be a non-empty string"
            invalidSearchType:
              summary: Invalid Search Type
              value:
                requestId: "..."
                error: "Invalid search type. Search type must be neural, keyword, or auto."
            invalidNumResultsForHighlights:
              summary: Invalid Number of Results for Highlights
              value:
                requestId: "..."
                error: "Invalid numResults. numResults must be <= 40 for highlights searches for performance reasons. If you need this customized, contact us at hello@exa.ai"
    InternalServerError:
      description: Internal Server Error - Something went wrong on our end
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            generalError:
              summary: General internal server error
              value:
                requestId: "..."
                error: "Internal Server Error"
                message: "An unexpected error occurred. Please try again later."
            dependencyError:
              summary: Dependency error causing service outage
              value:
                requestId: "..."
                error: "3rd party dependency error"
                message: "3rd party dependency is failing"
    TimeoutError:
      description: Timeout Error - The request took too long to process
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            generalError:
              summary: Timeout Error
              value:
                requestId: "..."
                error: Timeout Error
    RateLimitError:
      description: Rate Limit Error - You have exceeded the rate limit
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            generalError:
              summary: Rate Limit Error
              value:
                requestId: "..."
                error: Rate Limit Error
            usageLimitReached:
              summary: API Key Usage Limit Reached
              value:
                requestId: "..."
                error: "API key usage limit reached: {currentUsage}/{usageLimit}"
            planLimitExceeded:
              summary: Plan Limit Exceeded
              value:
                requestId: "..."
                error: "You are asking for a number of results above what your plan allows. To be able to get up to thousands of results per search, contact hello@metaphor.systems and we will figure something out."
    ServiceUnavailableError:
      description: Service Unavailable Error - One or more services temporarily unavailable
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            serviceError:
              summary: Service is unavailable - either due to crawling or capacity issues
              value:
                requestId: "..."
                error: "Service unavailable error"
                message: "An unexpected error occurred. Please try again later."
            capacityError:
              summary: Capacity issues causing outage
              value:
                requestId: "..."
                error: "Service unavailable error"
                message: "Sorry, we are at capacity."



security:
  - apikey: []