build-with-exa

On Activation

1. Confirm EXA_API_KEY is available for any live API call. SDK examples assume the key is set.
2. Default new integrations to POST /search with type: "auto" and contents.highlights: true. Escalate to Agent API only for multi-step research / list-building.
3. Load only the references/*.md file needed for the current endpoint - do not dump the whole tree into context.
4. For agent-native marketing research inside mktg projects, prefer exa-search, company-research, or lead-generation over inventing a custom integration.

Build with 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, Websets API
• SDK guidance: Python exa-py, TypeScript exa-js

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

Installation

# Python
pip install exa-py

# TypeScript / JavaScript
npm install exa-js

Authentication

export EXA_API_KEY="your_api_key_here"

Exa accepts either the x-api-key header or Authorization: Bearer <key>.

API Decision Workflow

Before picking an endpoint, decide which workflow shape fits:

• Raw web content for your own LLM or agent: start with /search using type: "auto" and contents: { highlights: true }
• Synthesized structured output: start with /search using the search type that fits your latency and reasoning needs, then add outputSchema and systemPrompt
• 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.

1. Need general semantic web retrieval, synthesized output, filters, or content extraction from search results: use the search endpoint (/search)
2. Already know the URLs and need clean page extraction or freshness controls: use the contents endpoint (/contents)
3. 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)
4. Need a grounded answer with citations from Exa-managed search: use the answer endpoint (/answer)
5. Need code-focused retrieval from repos, docs, and Stack Overflow: use the context endpoint (/context)
6. Need OpenAI SDK drop-in compatibility for chat or responses clients: use the OpenAI-compatible endpoints (/chat/completions, /responses)
7. Need asynchronous multi-step research, list-building, enrichment, or follow-up questions over prior research: use the Agent API (/agent)
8. Need scheduled recurring search with webhook delivery: use the Monitors API (/monitors)
9. Need async verified and enriched entity collection workflows: use the Websets API (/websets/v0)

Quick Start

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

Python (/search):

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):

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):

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
    }
  }'

Anti-Patterns

• 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 by default. Do not stack them unless the use case truly needs multiple views of the same page.
• numSentences and highlightsPerUrl are deprecated highlight knobs. Prefer highlights: true, or set maxCharacters only when you have a fixed budget.
• Prefer maxAgeHours for freshness guidance. Older livecrawl examples still exist, but maxAgeHours is the normative control for new integrations.
• Stick to the documented category set and do not invent categories like github, documentation, qa, or pdf. Specialized categories such as people and company also restrict which filters are valid; check the search reference before combining categories with domain or date filters.
• 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. Consider using it over websets or deep where appropriate.
• Treat /research/v1 as legacy. Do not present it as the default for new work.
• Treat /findSimilar as deprecated. Prefer /search (optionally after /contents on the seed URL) for related-page discovery.

Reference Files

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

Attribution

Ported from exa-labs/agent-skills - adapted for mktg's drop-in contract on 2026-07-18.

Upstream commit: 390ffee2d7e1d0dce2ed8efe4994c2b3c1c0173b

Drift detection: if the upstream skill changes, re-run mktg-steal https://github.com/exa-labs/agent-skills to evaluate the diff.