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
enum:
- company
- news
- pdf
- papers
- tweet
- github
- movies
- songs
- personal sites
description: (beta) A data category to focus on, with higher comprehensivity and data cleanliness. Categories right now include company, news, pdf, papers, tweet, github, movies, songs, personal sites
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: []