API Reference
OpenAPI Specification
API Reference
OpenAPI Specification
Raw openAPI spec here.
openapi: 3.1.0
info:
version: 1.1.1
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: "Latest developments in LLM capabilities"
description: The query string for the search.
useAutoprompt:
type: boolean
description: Autoprompt converts your query to an Exa-style query. Enabled by default for auto search, optional for neural search, and not available for keyword search.
example: true
default: true
type:
type: string
enum:
- keyword
- neural
- auto
description: The type of search. Neural uses an embeddings-based model, keyword is google-like SERP. Default is auto, which automatically decides between keyword and neural.
example: "auto"
default: "auto"
category:
type: string
enum:
- company
- research paper
- news
- pdf
- github
- tweet
- personal site
- linkedin profile
- financial report
description: A data category to focus on.
example: "research paper"
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://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"
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.
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
mode:
type: string
enum: [fast, accurate]
default: fast
description: "`accurate` generates expanded queries based on the original queries, increasing the result coverage for the response. `fast` only uses your original query."
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"
components:
securitySchemes:
apikey:
type: apiKey
name: x-api-key
in: header
schemas:
AnswerSource:
type: object
properties:
id:
type: string
description: The temporary ID for the document.
example: "https://arxiv.org/abs/2307.06435"
url:
type: string
format: uri
description: The URL of the search result.
example: "https://arxiv.org/pdf/2307.06435.pdf"
title:
type: string
description: The title of the search result.
example: "A Comprehensive Overview of Large Language Models"
author:
type: string
nullable: true
description: If available, the author of the content.
example: "Humza Naveed, University of Engineering and Technology (UET), Lahore, Pakistan"
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: "Abstract Large Language Models (LLMs) have recently demonstrated remarkable capabilities..."
AnswerResult:
type: object
properties:
requestId:
type: string
description: Unique identifier for the request
answer:
type: string
description: The generated answer based on search results.
sources:
type: array
description: Search results used to generate the answer.
items:
$ref: "#/components/schemas/AnswerSource"
ContentsRequest:
type: object
properties:
text:
oneOf:
- type: boolean
description: If true, returns full page text with default settings. If false, disables text return.
- type: object
description: Parsed contents of the page with custom settings.
properties:
maxCharacters:
type: integer
description: Maximum character limit for the full page text.
example: 1000
includeHtmlTags:
type: boolean
default: false
description: Include HTML tags, which can help LLMs understand text structure.
example: false
highlights:
type: object
description: Text snippets the LLM identifies as most relevant from each page.
properties:
numSentences:
type: integer
default: 5
description: The number of sentences to return for each snippet.
example: 1
highlightsPerUrl:
type: integer
default: 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"
livecrawl:
type: string
enum: [never, fallback, always, auto]
description: |
Options for livecrawling pages.
'never': Disable livecrawling (default for neural search).
'fallback': Livecrawl when cache is empty (default for keyword search).
'always': Always livecrawl.
'auto': Use an LLM to detect if query needs real-time content.
example: "always"
livecrawlTimeout:
type: integer
default: 10000
description: The timeout for livecrawling in milliseconds.
example: 1000
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
CommonRequest:
type: object
properties:
numResults:
type: integer
maximum: 10
default: 10
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.
example:
- course
contents:
$ref: "#/components/schemas/ContentsRequest"
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, [email protected], 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, [email protected] 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: []
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"
searchType:
type: string
enum: [neural, keyword]
description: For auto searches, indicates which search type was selected.
example: "auto"
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"
AnswerResponse:
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/AnswerResult"
text/event-stream:
schema:
type: object
properties:
answer:
type: string
description: Partial answer chunk when streaming is enabled.
sources:
type: array
items:
$ref: "#/components/schemas/AnswerSource"
security:
- apikey: []