Below is our OpenAPI specification, which provides a complete definition of the Metaphor API.

---
openapi: 3.1.0
info:
  version: 1.0.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
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.
                    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 'magic' (decides between keyword and neural). Default neural.
                  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.
      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"
      responses:
        "200":
          $ref: "#/components/responses/FindSimilarResponse"
  /contents:
    post:
      summary: Get contents of documents, many different types
      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'
      responses:
        "200":
          $ref: '#/components/responses/ContentsResponse'
components:
  securitySchemes:
    apikey:
      type: apiKey
      name: x-api-key
      in: header
  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.
    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
        category:
          type: string
          description: A data category to focus on, with higher comprehensivity and data cleanliness. Invite only - email [email protected]
        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
  responses:
    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.
    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"
    ContentsResponse:
      description: OK
      content:
        application/json:
          schema:
            type: object
            properties:
              results:
                type: array
                items:
                  $ref: "#/components/schemas/ResultWithContent"
security:
  - apikey: []