openapi: 3.1.0
info:
title: Exa Agent Search API
version: 2.0.0
description: Exa Agent API - subset of the Exa Public API.
servers:
- url: https://api.exa.ai
security:
- apiKey: []
- bearer: []
tags:
- name: Search
paths:
/search:
post:
operationId: search
summary: Search
description: Perform a search with an Exa prompt-engineered query and retrieve a list of relevant results. Optionally get contents.
x-codeSamples:
- lang: bash
label: Simple search with contents
source: "curl -X POST 'https://api.exa.ai/search' \\\n -H 'x-api-key: YOUR-EXA-API-KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"query\": \"Latest research in LLMs\",\n \"contents\": {\n \"highlights\": true\n }\n }'"
- lang: python
label: Simple search with contents
source: "# pip install exa-py\nfrom exa_py import Exa\nexa = Exa(api_key='YOUR_EXA_API_KEY')\n\nresults = exa.search(\n \"Latest research in LLMs\",\n contents={\"highlights\": True}\n)\n\nprint(results)"
- lang: javascript
label: Simple search with contents
source: "// npm install exa-js\nimport Exa from 'exa-js';\nconst exa = new Exa('YOUR_EXA_API_KEY');\n\nconst results = await exa.search(\n 'Latest research in LLMs',\n { contents: { highlights: true } }\n);\n\nconsole.log(results);"
- lang: bash
label: Advanced search with filters
source: "curl --request POST \\\n --url https://api.exa.ai/search \\\n --header 'x-api-key: <token>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"query\": \"Latest research in LLMs\",\n \"type\": \"auto\",\n \"category\": \"research paper\",\n \"numResults\": 10,\n \"moderation\": true,\n \"contents\": {\n \"text\": true,\n \"summary\": {\n \"query\": \"Main developments\"\n },\n \"subpages\": 1,\n \"subpageTarget\": \"sources\",\n \"extras\": {\n \"links\": 1,\n \"imageLinks\": 1\n }\n }\n }'"
- lang: bash
label: Deep search with query variations
source: "curl --request POST \\\n --url https://api.exa.ai/search \\\n --header 'x-api-key: <token>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"query\": \"Who is the CEO of OpenAI?\",\n \"additionalQueries\": [\n \"OpenAI CEO current\",\n \"OpenAI leadership official source\"\n ],\n \"type\": \"deep\",\n \"systemPrompt\": \"Prefer official sources and avoid duplicate results\",\n \"outputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"leader\": { \"type\": \"string\" },\n \"title\": { \"type\": \"string\" },\n \"sourceCount\": { \"type\": \"number\" }\n },\n \"required\": [\"leader\", \"title\"]\n },\n \"contents\": {\n \"text\": true\n }\n }'"
- lang: python
label: Advanced search with filters
source: "# pip install exa-py\nfrom exa_py import Exa\nexa = Exa(api_key='YOUR_EXA_API_KEY')\n\nresults = exa.search(\n \"Latest research in LLMs\",\n type=\"auto\",\n category=\"research paper\",\n num_results=10,\n moderation=True,\n contents={\n \"text\": True,\n \"summary\": {\n \"query\": \"Main developments\"\n },\n \"subpages\": 1,\n \"subpage_target\": \"sources\",\n \"extras\": {\n \"links\": 1,\n \"image_links\": 1\n }\n },\n)\n\nprint(results)"
- lang: javascript
label: Advanced search with filters
source: "// npm install exa-js\nimport Exa from 'exa-js';\nconst exa = new Exa('YOUR_EXA_API_KEY');\n\nconst results = await exa.search('Latest research in LLMs', {\n type: 'auto',\n category: 'research paper',\n numResults: 10,\n moderation: true,\n contents: {\n text: true,\n summary: {\n query: 'Main developments'\n },\n subpages: 1,\n subpageTarget: 'sources',\n extras: {\n links: 1,\n imageLinks: 1\n }\n }\n});\n\nconsole.log(results);"
- lang: python
label: Deep search with query variations
source: "# pip install exa-py\nfrom exa_py import Exa\nexa = Exa(api_key='YOUR_EXA_API_KEY')\n\nresults = exa.search(\n \"Who is the CEO of OpenAI?\",\n additional_queries=[\n \"OpenAI CEO current\",\n \"OpenAI leadership official source\"\n ],\n type=\"deep\",\n system_prompt=\"Prefer official sources and avoid duplicate results\",\n output_schema={\n \"type\": \"object\",\n \"properties\": {\n \"leader\": {\"type\": \"string\"},\n \"title\": {\"type\": \"string\"},\n \"source_count\": {\"type\": \"number\"}\n },\n \"required\": [\"leader\", \"title\"]\n },\n contents={\"text\": True}\n)\n\nprint(results)"
- lang: javascript
label: Deep search with query variations
source: "// npm install exa-js\nimport Exa from 'exa-js';\nconst exa = new Exa('YOUR_EXA_API_KEY');\n\nconst results = await exa.search('Who is the CEO of OpenAI?', {\n additionalQueries: [\n 'OpenAI CEO current',\n 'OpenAI leadership official source'\n ],\n type: 'deep',\n systemPrompt: 'Prefer official sources and avoid duplicate results',\n outputSchema: {\n type: 'object',\n properties: {\n leader: { type: 'string' },\n title: { type: 'string' },\n sourceCount: { type: 'number' }\n },\n required: ['leader', 'title']\n },\n contents: {\n text: true\n }\n});\n\nconsole.log(results);"
- lang: bash
label: Streaming synthesized output
source: "curl --no-buffer --request POST \\\n --url https://api.exa.ai/search \\\n --header 'x-api-key: <token>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"query\": \"Summarize the latest AI chip launches\",\n \"type\": \"fast\",\n \"stream\": true,\n \"outputSchema\": {\n \"type\": \"text\",\n \"description\": \"A short grounded summary in 3 bullets\"\n }\n }'"
- lang: bash
label: Instant search (lowest latency)
source: "curl --request POST \\\n --url https://api.exa.ai/search \\\n --header 'x-api-key: <token>' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"query\": \"What is the capital of France?\",\n \"type\": \"instant\",\n \"numResults\": 10,\n \"contents\": {\n \"highlights\": true\n }\n }'"
- lang: python
label: Instant search (lowest latency)
source: "# pip install exa-py\nfrom exa_py import Exa\nexa = Exa(api_key='YOUR_EXA_API_KEY')\n\nresults = exa.search(\n \"What is the capital of France?\",\n type=\"instant\",\n num_results=10,\n contents={\"highlights\": True}\n)\n\nprint(results)"
- lang: javascript
label: Instant search (lowest latency)
source: "// npm install exa-js\nimport Exa from 'exa-js';\nconst exa = new Exa('YOUR_EXA_API_KEY');\n\nconst results = await exa.search(\n 'What is the capital of France?',\n {\n type: 'instant',\n numResults: 10,\n contents: { highlights: true }\n }\n);\n\nconsole.log(results);"
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
responses:
'200':
description: OK
content:
application/json:
example:
requestId: b5947044c4b78efa9552a7c89b306d95
results:
- title: A Comprehensive Overview of Large Language Models
url: https://arxiv.org/pdf/2307.06435.pdf
publishedDate: '2023-11-16T01:36:32.547Z'
author: Humza Naveed, University of Engineering and Technology (UET), Lahore, Pakistan
id: https://arxiv.org/abs/2307.06435
image: https://arxiv.org/pdf/2307.06435.pdf/page_1.png
favicon: https://arxiv.org/favicon.ico
text: Abstract Large Language Models (LLMs) have recently demonstrated remarkable capabilities...
highlights:
- Such requirements have limited their adoption...
highlightScores:
- 0.4600165784358978
summary: This overview paper on Large Language Models (LLMs) highlights key developments...
subpages:
- 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, yzhuang@zju.edu.cn, 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, yzhuang@zju.edu.cn 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:
links: []
resolvedSearchType: ''
context: <string>
output:
content: <string>
grounding:
- field: <string>
citations:
- url: <string>
title: <string>
confidence: high
costDollars:
total: 0.007
search:
neural: 0.007
schema:
$ref: '#/components/schemas/SearchResponse'
text/event-stream:
schema:
$ref: '#/components/schemas/SearchStreamChunk'
tags:
- Search
components:
schemas:
CostDollarsOutput:
type: object
properties:
total:
description: Estimated total dollar cost for the completed request. This response value is not an invoice record.
example: 0.007
format: float
type: number
search:
description: Endpoint-dependent estimated search cost breakdown by retrieval mode. Instant, fast, and auto search responses may include neural search cost. Deep search modes may be reflected only in total.
type: object
properties:
neural:
description: Cost of neural search operations.
example: 0.007
format: float
type: number
additionalProperties: false
additionalProperties: false
description: Endpoint-dependent estimated dollar cost breakdown for the completed request. Billing is computed from usage counters rather than this response object.
SearchResponse:
oneOf:
- type: object
properties:
requestId:
type: string
description: Unique identifier for the request.
example: b5947044c4b78efa9552a7c89b306d95
results:
type: array
items:
$ref: '#/components/schemas/SearchResultOutput'
description: A list of search results containing title, URL, published date, and author.
resolvedSearchType:
description: Deprecated legacy field. Current production responses may return an empty string; clients should not branch on this value.
example: ''
deprecated: true
type: string
context:
type: string
description: Deprecated. Combined context string from search results. Use highlights or text instead.
deprecated: true
costDollars:
$ref: '#/components/schemas/CostDollarsOutput'
output:
$ref: '#/components/schemas/SearchSynthesisOutputOutput'
required:
- results
- output
additionalProperties: false
- type: object
properties:
requestId:
type: string
description: Unique identifier for the request.
example: b5947044c4b78efa9552a7c89b306d95
results:
type: array
items:
$ref: '#/components/schemas/SearchResultOutput'
description: A list of search results containing title, URL, published date, and author.
resolvedSearchType:
description: Deprecated legacy field. Current production responses may return an empty string; clients should not branch on this value.
example: ''
deprecated: true
type: string
context:
type: string
description: Deprecated. Combined context string from search results. Use highlights or text instead.
deprecated: true
costDollars:
$ref: '#/components/schemas/CostDollarsOutput'
required:
- results
additionalProperties: false
SearchSynthesisOutputOutput:
type: object
properties:
content:
description: Synthesized content. String by default, or object when outputSchema is provided.
oneOf:
- type: string
- type: object
propertyNames:
type: string
additionalProperties:
$ref: '#/components/schemas/JsonValue'
grounding:
type: array
items:
type: object
properties:
field:
type: string
description: Field path in output.content, for example content or companies[0].funding.
citations:
type: array
items:
type: object
properties:
url:
type: string
format: uri
description: Source URL.
title:
type: string
description: Source title.
required:
- url
- title
additionalProperties: false
description: Sources supporting this output field.
confidence:
type: string
enum:
- low
- medium
- high
description: Model-reported reliability for this field.
required:
- field
- citations
- confidence
additionalProperties: false
description: Field-level grounding for synthesized output.
required:
- content
- grounding
additionalProperties: false
description: Synthesized output. Returned when outputSchema is provided.
ContentsOptions:
type: object
properties:
text:
anyOf:
- description: Text extraction options for each result.
oneOf:
- type: boolean
title: Simple text retrieval
description: If true, returns full page text with default settings. If false, disables text return.
default: false
- type: object
properties:
maxCharacters:
anyOf:
- type: integer
minimum: 1
maximum: 10000
description: Maximum character limit for the full page text. Useful for controlling response size and API costs. Maximum supported value is 10000.
example: 1000
- type: 'null'
includeHtmlTags:
anyOf:
- type: boolean
description: 'If true, include lightweight HTML tags in returned text instead of plain markdown-style text. Use maxAgeHours: 0 when you need this applied to freshly fetched content.'
example: false
default: false
- type: 'null'
verbosity:
anyOf:
- type: string
enum:
- compact
- standard
- full
description: 'Controls text rendering verbosity. compact focuses on main content, standard includes more surrounding page context, and full requests the most complete rendered text. Some pages may produce identical standard and full output. Use maxAgeHours: 0 when you need this applied to freshly fetched content.'
example: standard
default: compact
- type: 'null'
includeSections:
anyOf:
- type: array
items:
type: string
enum:
- header
- navigation
- banner
- body
- sidebar
- footer
- metadata
description: 'Best-effort. Only include content classified into these semantic page sections. Section classification may be unavailable or incomplete for some pages; validate output if strict filtering is required. Use maxAgeHours: 0 when you need this applied to freshly fetched content.'
example:
- body
- header
- type: 'null'
excludeSections:
anyOf:
- type: array
items:
type: string
enum:
- header
- navigation
- banner
- body
- sidebar
- footer
- metadata
description: 'Exclude content classified into these semantic page sections. Section classification is best-effort. Use maxAgeHours: 0 when you need this applied to freshly fetched content.'
example:
- navigation
- footer
- sidebar
- type: 'null'
title: Advanced text options
description: Advanced options for controlling text extraction. Use this when you need to limit text length or include HTML structure.
- type: 'null'
highlights:
anyOf:
- description: Text snippets the LLM identifies as most relevant from each page.
oneOf:
- type: boolean
title: Simple highlights retrieval
description: If true, returns highlights with default settings. If false, disables highlights.
default: false
- type: object
properties:
query:
anyOf:
- type: string
description: Custom query that guides which highlights the LLM picks.
example: Key advancements
- type: 'null'
maxCharacters:
anyOf:
- type: integer
minimum: 1
maximum: 10000
description: Maximum number of characters to return for highlights. Controls the total length of highlight text returned per URL. Maximum supported value is 10000.
example: 2000
- type: 'null'
numSentences:
anyOf:
- type: integer
minimum: 1
description: 'Deprecated and will be removed in a future release. Currently mapped to a character budget of about 1333 characters per sentence. Pass highlights: true for default highlights, or { query } to guide selection with your own query.'
example: 1
deprecated: true
- type: 'null'
highlightsPerUrl:
anyOf:
- type: integer
minimum: 1
description: 'Deprecated and will be removed in a future release. Currently ignored. Pass highlights: true for default highlights, or { query } to guide selection with your own query.'
example: 1
deprecated: true
- type: 'null'
title: Advanced highlights options
description: 'Advanced options for steering highlight extraction. Pass highlights: true for the highest-quality default; supply this object only when you need to guide selection with your own query.'
- type: 'null'
summary:
anyOf:
- type: object
properties:
query:
anyOf:
- type: string
description: Custom query for the LLM-generated summary.
example: Main developments
- type: 'null'
schema:
anyOf:
- type: object
propertyNames:
type: string
additionalProperties:
$ref: '#/components/schemas/JsonValue'
description: JSON schema for structured output from summary. See https://json-schema.org/overview/what-is-jsonschema for JSON Schema documentation.
example:
$schema: http://json-schema.org/draft-07/schema#
title: Title
type: object
properties:
Property 1:
type: string
description: Description
Property 2:
type: string
enum:
- option 1
- option 2
- option 3
description: Description
required:
- Property 1
- type: 'null'
description: Summary of the webpage.
- type: 'null'
extras:
anyOf:
- type: object
properties:
links:
anyOf:
- type: integer
minimum: 0
maximum: 1000
description: Number of URLs to return from each webpage.
example: 1
default: 0
- type: 'null'
imageLinks:
anyOf:
- type: integer
minimum: 0
maximum: 1000
description: Number of images to return for each result.
example: 1
default: 0
- type: 'null'
richImageLinks:
anyOf:
- type: integer
minimum: 0
maximum: 1000
description: Number of rich image links to return for each result.
default: 0
- type: 'null'
richLinks:
anyOf:
- type: integer
minimum: 0
maximum: 1000
description: Number of rich links to return for each result.
default: 0
- type: 'null'
codeBlocks:
anyOf:
- type: integer
minimum: 0
maximum: 1000
description: Number of code blocks to return for each result.
default: 0
- type: 'null'
description: Extra parameters to pass.
- type: 'null'
context:
anyOf:
- description: 'Deprecated: Use highlights or text instead. Returns page contents as a combined context string.'
deprecated: true
oneOf:
- type: boolean
description: 'Deprecated: Use highlights or text instead. Returns page contents as a combined context string.'
example: true
deprecated: true
- type: object
properties:
maxCharacters:
type: integer
minimum: 1
maximum: 10000
description: Deprecated. Maximum character limit for the context string. Maximum supported value is 10000.
example: 10000
description: 'Deprecated: Use highlights or text instead. Returns page contents as a combined context string.'
deprecated: true
- type: 'null'
livecrawl:
anyOf:
- type: string
enum:
- never
- always
- fallback
- preferred
description: 'Deprecated: Use maxAgeHours instead for content freshness control. livecrawl does not guarantee freshly fetched parser output and may be served according to server freshness policy. Do not send livecrawl and maxAgeHours together.'
example: preferred
deprecated: true
- type: 'null'
livecrawlTimeout:
anyOf:
- type: integer
exclusiveMinimum: 0
maximum: 90000
description: The timeout for livecrawling in milliseconds.
example: 1000
default: 10000
- type: 'null'
maxAgeHours:
anyOf:
- type: integer
minimum: -1
maximum: 720
description: Maximum age of cached content in hours. Positive values use cached content if it is less than this many hours old; 0 fetches fresh content and is the supported way to apply text rendering options to newly fetched pages; -1 always uses cache; omitted uses fallback fetching when cached content is unavailable. Maximum supported value is 720 hours.
example: 24
- type: 'null'
subpages:
anyOf:
- type: integer
minimum: 0
maximum: 100
description: The number of subpages to crawl. The actual number crawled may be limited by system constraints.
example: 1
default: 0
- type: 'null'
subpageTarget:
anyOf:
- description: Term to find specific subpages of search results. Can be a single string or an array of strings.
example: sources
oneOf:
- type: string
minLength: 1
maxLength: 100
- minItems: 0
maxItems: 100
type: array
items:
type: string
minLength: 1
maxLength: 100
- type: 'null'
SearchRequest:
type: object
properties:
includeDomains:
anyOf:
- maxItems: 1200
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
- type: 'null'
excludeDomains:
anyOf:
- maxItems: 1200
type: array
items:
type: string
description: List of domains to exclude from search results. If specified, no results will be returned from these domains.
- type: 'null'
startCrawlDate:
anyOf:
- type: string
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-01T00:00:00.000Z'
format: date-time
- type: 'null'
endCrawlDate:
anyOf:
- type: string
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-31T00:00:00.000Z'
format: date-time
- type: 'null'
startPublishedDate:
anyOf:
- type: string
description: Only links with a published date after this will be returned. Must be specified in ISO 8601 format.
example: '2023-01-01T00:00:00.000Z'
format: date-time
- type: 'null'
endPublishedDate:
anyOf:
- type: string
description: Only links with a published date before this will be returned. Must be specified in ISO 8601 format.
example: '2023-12-31T00:00:00.000Z'
format: date-time
- type: 'null'
numResults:
anyOf:
- type: integer
minimum: 1
maximum: 100
description: Number of results to return. Limits vary by search type. The maximum public limit is 100 results. Contact sales (hello@exa.ai) to discuss higher limits.
example: 10
default: 10
- type: 'null'
context:
anyOf:
- description: 'Deprecated: Use highlights or text instead. Returns page contents as a combined context string.'
deprecated: true
oneOf:
- type: boolean
description: 'Deprecated: Use highlights or text instead. Returns page contents as a combined context string.'
example: true
deprecated: true
- type: object
properties:
maxCharacters:
type: integer
minimum: 1
maximum: 10000
description: Deprecated. Maximum character limit for the context string. Maximum supported value is 10000.
example: 10000
description: 'Deprecated: Use highlights or text instead. Returns page contents as a combined context string.'
deprecated: true
- type: 'null'
moderation:
anyOf:
- type: boolean
description: Enable content moderation to filter unsafe content from search results.
example: true
default: false
- type: 'null'
contents:
anyOf:
- description: Content options for text, highlights, summary, extras, and freshness controls.
$ref: '#/components/schemas/ContentsOptions'
- type: 'null'
query:
type: string
minLength: 1
description: The query string for
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/exa-ai/refs/heads/main/openapi/exa-ai-search-api-openapi.yml