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 [email protected]"
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 [email protected] 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: []