build-with-exa

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Build with Exa

使用Exa构建应用

Scope

适用范围

Included by default:

Core retrieval APIs: search endpoint, contents endpoint, answer endpoint, context endpoint
Long-running research workflows: Agent API (
```
/agent
```
)
Async and recurring workflows: Monitors API
Legacy surface: Websets API (existing integrations only; new collection-building work uses the Agent API)
SDK guidance: Python
```
exa-py
```
, TypeScript
```
exa-js
```

Note on data retention:
/search
,
/answer
, and
/agent/
offer Zero Data Retention (ZDR). Websets and Monitors are not ZDR. If a use case requires ZDR, stay on the ZDR surfaces or contact Exa.

默认包含以下内容：

核心检索API：搜索端点、内容提取端点、问答端点、上下文端点
长期运行的研究工作流：Agent API（
```
/agent
```
）
异步与周期性工作流：Monitors API
旧版接口：Websets API（仅适用于现有集成；新的集合构建工作请使用Agent API）
SDK指南：Python
```
exa-py
```
、TypeScript
```
exa-js
```

数据保留说明：
/search
、
/answer
和
/agent/
支持零数据保留（ZDR）。Websets和Monitors不支持ZDR。如果您的使用场景需要ZDR，请使用支持ZDR的接口，或联系Exa。

Installation

安装

bash

undefined

bash

undefined

Python

pip install exa-py

TypeScript / JavaScript

npm install exa-js


Install the latest SDK release with the package manager so it resolves the latest release and all SDK surfaces will be available.

npm install exa-js


通过包管理器安装最新版本的SDK，这样可以获取最新版本的所有SDK功能。

Authentication

身份验证

bash

export EXA_API_KEY="your_api_key_here"

Exa accepts either the

x-api-key

header or

Authorization: Bearer <key>

The recommended Exa search request is the query plus token-efficient content extraction, and nothing else. Content extraction is a recommendation, not a server default: omit

contents

and results carry only metadata (title, URL, dates), no page content.

json

{
  "query": "latest developments in LLMs",
  "type": "auto",
  "contents": { "highlights": true }
}

Every other request field is gated: add it only when the user's task explicitly requires it. Do not restate server defaults, and do not add controls because they seem plausibly useful. In particular:

```
type
```
defaults to
```
auto
```
; stating
```
type: "auto"
```
explicitly is fine, but do not send another mode unless the task requires it (for example a latency-critical UX or deep synthesis).
```
numResults
```
defaults to 10; omit
```
numResults
```
unless the task requires a different number of results. Set it only as an intentional product decision, not as boilerplate.
Omit
```
category
```
. Use it only when the user explicitly asks for category-constrained retrieval.
```
includeDomains
```
and
```
excludeDomains
```
should be set only when the user explicitly requests a hard allowlist or blocklist and supplies or approves its contents. Express source preferences through query phrasing or
```
systemPrompt
```
instead.
```
maxAgeHours
```
should be set only when extracted page content must be current. It caps cache age before a live crawl; it is not a publication-recency filter.
For "recent stories" tasks, express the window in the query or use
```
startPublishedDate
```
/
```
endPublishedDate
```
. Do not reach for
```
maxAgeHours
```
.
```
highlights
```
should be set to
```
true
```
by default for all tasks unless otherwise specified. Do not add
```
maxCharacters
```
or other highlight options without an explicit budget requirement in the task.

bash

export EXA_API_KEY="your_api_key_here"

Exa支持通过

x-api-key

请求头或

Authorization: Bearer <key>

进行身份验证。

推荐的Exa搜索请求格式为：查询语句加上高效的内容提取参数，无需其他额外内容。内容提取是推荐配置，而非服务器默认值：如果省略

contents

参数，结果将仅包含元数据（标题、URL、日期），不包含页面内容。

json

{
  "query": "latest developments in LLMs",
  "type": "auto",
  "contents": { "highlights": true }
}

所有其他请求字段均为可选：仅当用户任务明确需要时才添加。 不要重复说明服务器默认值，也不要添加看似有用但非必需的控制参数。特别注意：

```
type
```
默认值为
```
auto
```
；显式声明
```
type: "auto"
```
是可以的，但除非任务需要，否则不要使用其他模式（例如对延迟敏感的用户体验场景或深度合成需求）。
```
numResults
```
默认值为10；除非任务需要不同数量的结果，否则省略该参数。仅将其作为有意的产品决策设置，而非模板代码。
省略
```
category
```
参数。仅当用户明确要求按类别限制检索时才使用它。
```
includeDomains
```
和
```
excludeDomains
```
仅当用户明确要求严格的允许列表或阻止列表，并提供或确认列表内容时才设置。优先通过查询语句或
```
systemPrompt
```
表达对来源的偏好。
```
maxAgeHours
```
仅当提取的页面内容必须是最新的时才设置。它用于限制缓存的有效期，超过后将触发实时爬取；它不是发布时间过滤器。
对于“最新资讯”类任务，在查询语句中表达时间范围，或使用
```
startPublishedDate
```
/
```
endPublishedDate
```
参数。不要使用
```
maxAgeHours
```
。
除非另有说明，否则所有任务默认将
```
highlights
```
设置为
```
true
```
。除非任务中有明确的预算要求，否则不要添加
```
maxCharacters
```
或其他高亮选项。

API Decision Workflow

API选择工作流

Before picking an endpoint, decide which workflow shape fits:

Raw web content for your own LLM or agent: use
```
/search
```
with the recommended request above
Synthesized structured output: use
```
/search
```
and add
```
outputSchema
```
(and
```
systemPrompt
```
if behavior guidance is needed)
Long-running multi-step research, list-building, or enrichment with structured output: use the Agent API (
```
/agent
```
)

Default to the search endpoint. Use the search endpoint (

/search

) for most new integrations, then move to a more specialized Exa surface only when the task shape clearly calls for it.

Need general semantic web retrieval, synthesized output, or content extraction from search results: use the search endpoint (
```
/search
```
)
Already know the URLs and need clean page extraction or freshness controls: use the contents endpoint (
```
/contents
```
)
Need pages related to a known seed URL: use the search endpoint (
```
/search
```
) with a query derived from the page (for example title, topic, or text from
```
/contents
```
)
Need a grounded answer with citations and no LLM of your own doing generation: use the answer endpoint (
```
/answer
```
). If the product already has a chat LLM, give it
```
/search
```
as a tool instead.
Need code-focused retrieval from repos, docs, and Stack Overflow: use the context endpoint (
```
/context
```
)
Need OpenAI SDK drop-in compatibility for chat or responses clients: use the OpenAI-compatible endpoints (
```
/chat/completions
```
,
```
/responses
```
)
Need asynchronous multi-step research, list-building, enrichment, or follow-up questions over prior research: use the Agent API (
```
/agent
```
)
Need scheduled recurring search with webhook delivery: use the Monitors API (
```
/monitors
```
)
Maintaining an existing Websets integration: see the migration guide (
```
references/migrate-websets-to-agent.md
```
) and transition to the Agent API (
```
references/agent.md
```
). Do not use Websets for new work; use the Agent API instead.

在选择端点之前，请确定哪种工作流类型符合需求：

为您自己的LLM或Agent获取原始网页内容：使用上述推荐格式的
```
/search
```
端点
需要结构化的合成输出：使用
```
/search
```
端点并添加
```
outputSchema
```
（如果需要行为指导，可同时添加
```
systemPrompt
```
）
需要长期运行的多步骤研究、列表构建或带结构化输出的信息补全：使用Agent API（
```
/agent
```
）

优先使用搜索端点。 大多数新集成应使用搜索端点（

/search

），仅当任务类型明确需要时，才切换到更专业的Exa接口。

需要通用语义网络检索、合成输出或从搜索结果中提取内容：使用搜索端点（
```
/search
```
）
已知URL，需要提取干净的页面内容或控制内容新鲜度：使用内容提取端点（
```
/contents
```
）
需要与已知种子URL相关的页面：使用搜索端点（
```
/search
```
），并基于该页面生成查询语句（例如标题、主题或从
```
/contents
```
获取的文本）
需要带引用的可靠答案，且不想自行使用LLM生成内容：使用问答端点（
```
/answer
```
）。如果产品已集成聊天LLM，应将
```
/search
```
作为工具提供给它。
需要从代码仓库、文档和Stack Overflow中检索代码相关内容：使用上下文端点（
```
/context
```
）
需要兼容OpenAI SDK的聊天或响应客户端：使用兼容OpenAI的端点（
```
/chat/completions
```
、
```
/responses
```
）
需要异步多步骤研究、列表构建、信息补全或基于已有研究进行后续提问：使用Agent API（
```
/agent
```
）
需要定期执行搜索并通过Webhook交付结果：使用Monitors API（
```
/monitors
```
）
维护现有Websets集成：查看迁移指南（
```
references/migrate-websets-to-agent.md
```
）并过渡到Agent API（
```
references/agent.md
```
）。不要在新工作中使用Websets；请改用Agent API。

Quick Start

快速开始

For more complete examples, see the relevant reference file in the table below.

Python (

/search

python

from exa_py import Exa

exa = Exa(api_key="YOUR_EXA_API_KEY")
result = exa.search(
    "latest developments in LLMs",
    type="auto",
    contents={"highlights": True}
)

for item in result.results:
    print(item.title, item.url)

TypeScript (

/search

typescript

import Exa from "exa-js";

const exa = new Exa();
const result = await exa.search("latest developments in LLMs", {
  type: "auto",
  contents: { highlights: true }
});

for (const item of result.results) {
  console.log(item.title, item.url);
}

Raw HTTP (

/search

bash

curl -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "latest developments in LLMs",
    "type": "auto",
    "contents": {
      "highlights": true
    }
  }'

如需更完整的示例，请查看下表中的相关参考文件。

Python（

/search

）：

python

from exa_py import Exa

exa = Exa(api_key="YOUR_EXA_API_KEY")
result = exa.search(
    "latest developments in LLMs",
    type="auto",
    contents={"highlights": True}
)

for item in result.results:
    print(item.title, item.url)

TypeScript（

/search

）：

typescript

import Exa from "exa-js";

const exa = new Exa();
const result = await exa.search("latest developments in LLMs", {
  type: "auto",
  contents: { highlights: true }
});

for (const item of result.results) {
  console.log(item.title, item.url);
}

原生HTTP请求（

/search

）：

bash

curl -X POST "https://api.exa.ai/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "query": "latest developments in LLMs",
    "type": "auto",
    "contents": {
      "highlights": true
    }
  }'

Critical Pitfalls

常见误区

Do not decorate the recommended request without reason. Adding
```
category
```
, domain filters, boilerplate
```
numResults
```
, or freshness controls without an explicit task requirement is the most common integration mistake.
On the search endpoint,
```
text
```
,
```
highlights
```
, and
```
summary
```
belong inside
```
contents
```
, not at the top level.
On the contents endpoint,
```
text
```
,
```
highlights
```
, and
```
summary
```
are top-level fields, not nested inside
```
contents
```
.
Pick one of
```
highlights
```
,
```
text
```
, or
```
summary
```
. Do not stack them.
```
summary
```
requires an explicit user request for Exa-side per-result synthesis.
Almost all tasks should use bare
```
highlights: true
```
.
```
numSentences
```
and
```
highlightsPerUrl
```
are deprecated, and
```
maxCharacters
```
needs an explicit budget requirement.
List-building and enrichment workflows belong on the Agent API (
```
/agent
```
), not on
```
/search
```
with
```
category: "people"
```
or
```
category: "company"
```
. Those categories are only for retrieving raw people or company documents.
```
maxAgeHours
```
controls crawl/cache freshness (how old extracted page content may be before a live crawl), not publication recency. Do not use it as a "recent results" control; recency belongs in query phrasing or
```
startPublishedDate
```
/
```
endPublishedDate
```
.
Never invent category values like
```
github
```
,
```
documentation
```
,
```
qa
```
, or
```
pdf
```
. When a user does request category-constrained retrieval, check the search reference first: specialized categories such as
```
people
```
and
```
company
```
restrict which filters are valid.
OpenAI-compatible endpoints are for compatibility-first use cases. Prefer native Exa endpoints for new integrations when you want clearer request semantics.
Do not treat
```
/agent
```
as a drop-in replacement for
```
/search
```
. It is higher-latency and async, so use the dedicated Agent reference when that workflow shape is the real fit. Prefer it over Websets for new collection-building work.
Agent requests should always set
```
effort
```
explicitly, wait for a terminal status via polling or SSE and check how the run ended before reading
```
output
```
, and expose
```
output.grounding
```
when relevant in a product.
Treat
```
/findSimilar
```
as deprecated. Prefer
```
/search
```
(optionally after
```
/contents
```
on the seed URL) for related-page discovery.

不要无故修改推荐的请求格式。最常见的集成错误是在没有明确任务需求的情况下添加
```
category
```
、域名过滤器、模板化的
```
numResults
```
或新鲜度控制参数。
在搜索端点中，
```
text
```
、
```
highlights
```
和
```
summary
```
应嵌套在
```
contents
```
内，而非顶层字段。
在内容提取端点中，
```
text
```
、
```
highlights
```
和
```
summary
```
是顶层字段，而非嵌套在
```
contents
```
内。
选择
```
highlights
```
、
```
text
```
或
```
summary
```
中的一个，不要同时使用多个。
```
summary
```
需要用户明确请求Exa端进行单结果合成。
几乎所有任务都应使用
```
highlights: true
```
。
```
numSentences
```
和
```
highlightsPerUrl
```
已废弃，
```
maxCharacters
```
需要明确的预算要求。
列表构建和信息补全工作流应使用Agent API（
```
/agent
```
），而非使用
```
category: "people"
```
或
```
category: "company"
```
的
```
/search
```
端点。这些类别仅用于检索原始的人物或公司文档。
```
maxAgeHours
```
控制爬取/缓存的新鲜度（提取的页面内容在触发实时爬取前的最大允许时长），而非发布时间。不要将其用作“最新结果”控制；发布时间限制应通过查询语句或
```
startPublishedDate
```
/
```
endPublishedDate
```
设置。
不要自定义
```
github
```
、
```
documentation
```
、
```
qa
```
或
```
pdf
```
等类别值。当用户确实需要按类别限制检索时，请先查看搜索参考文档：
```
people
```
和
```
company
```
等特殊类别会限制可用的过滤器。
兼容OpenAI的端点适用于优先考虑兼容性的场景。如果希望获得更清晰的请求语义，新集成应优先使用Exa原生端点。
不要将
```
/agent
```
视为
```
/search
```
的直接替代品。它的延迟更高且是异步的，因此当工作流类型确实符合时，请参考专门的Agent文档。新的集合构建工作应优先使用它而非Websets。
Agent请求应始终显式设置
```
effort
```
参数，通过轮询或SSE等待终端状态，并在读取
```
output
```
前检查运行结果，同时在产品中相关场景下展示
```
output.grounding
```
。
将
```
/findSimilar
```
视为已废弃接口。优先使用
```
/search
```
（可选地先对种子URL调用
```
/contents
```
）来发现相关页面。

Reference Files

参考文件

File	Topics
references/search.md	Search endpoint request/response shape, search types, filters, nested contents, structured output
references/contents.md	Contents endpoint extraction, freshness, statuses, top-level content fields
references/answer.md	Grounded answer generation with citations and structured output
references/context.md	Code-focused retrieval with `tokensNum`
references/agent.md	Agent API for async multi-step research, enrichment, structured output, polling, and events
references/openai-compat.md	OpenAI-compatible endpoints, model routing, `extra_body` usage
references/monitors.md	Standalone Monitors API for scheduled recurring search
references/migrate-websets-to-agent.md	Migrate Websets to the Agent API: call-site classification, request mapping, delivery rewrite, verification
references/sdks.md	Python and TypeScript SDK naming, methods, and shape differences
references/http-requests.md	Minimal raw HTTP examples across major Exa surfaces
references/models-and-modes.md	Search type selection, answer/research model routing, latency tradeoffs
references/prompting-and-patterns.md	Durable query, prompting, freshness, and output-schema patterns
references/common-mistakes.md	Over-specification and parameter-shape corrections

文件	主题
references/search.md	搜索端点的请求/响应格式、搜索类型、过滤器、嵌套内容、结构化输出
references/contents.md	内容提取端点的提取功能、新鲜度控制、状态码、顶层内容字段
references/answer.md	带引用的答案生成与结构化输出
references/context.md	面向代码的检索与 `tokensNum` 参数
references/agent.md	用于异步多步骤研究、信息补全、结构化输出、轮询和事件的Agent API
references/openai-compat.md	兼容OpenAI的端点、模型路由、 `extra_body` 用法
references/monitors.md	用于定期执行搜索的独立Monitors API
references/migrate-websets-to-agent.md	将Websets迁移到Agent API：调用站点分类、请求映射、交付重写、验证
references/sdks.md	Python和TypeScript SDK的命名、方法与格式差异
references/http-requests.md	Exa主要接口的最简原生HTTP示例
references/models-and-modes.md	搜索类型选择、问答/研究模型路由、延迟权衡
references/prompting-and-patterns.md	可靠的查询、提示词、新鲜度和输出模式
references/common-mistakes.md	过度配置与参数格式修正

Canonical Docs

官方文档

Docs home:
```
https://exa.ai/docs
```
Documentation index:
```
https://exa.ai/docs/llms.txt
```
Search reference:
```
https://exa.ai/docs/reference/search
```

Agent API guide:

https://exa.ai/docs/reference/agent-api-guide

Exa Connect overview:

https://exa.ai/docs/reference/agent-api/connect/overview

Python SDK spec:

https://exa.ai/docs/sdks/python-sdk-specification

TypeScript SDK spec:

https://exa.ai/docs/sdks/typescript-sdk-specification

文档主页：
```
https://exa.ai/docs
```
文档索引：
```
https://exa.ai/docs/llms.txt
```
搜索参考文档：
```
https://exa.ai/docs/reference/search
```

Agent API指南：

https://exa.ai/docs/reference/agent-api-guide

Exa Connect概述：

https://exa.ai/docs/reference/agent-api/connect/overview

Python SDK规范：

https://exa.ai/docs/sdks/python-sdk-specification

TypeScript SDK规范：

https://exa.ai/docs/sdks/typescript-sdk-specification