exa-contents

On Activation

1. Read brand/competitors.md / brand/landscape.md if present for URL shortlists. Optional.
2. Confirm Exa auth (MCP or EXA_API_KEY) via mktg doctor if unsure.
3. Prefer MCP web_fetch_exa when available; otherwise use the cURL examples below.
4. If the page is auth-walled (X/Twitter login stub), route to mktg-x instead.

Exa Contents

Requires API key: Get one at https://dashboard.exa.ai/api-keys

Header: x-api-key: $EXA_API_KEY

Use POST https://api.exa.ai/contents when the agent already knows the URLs and needs clean, LLM-ready extraction without running a new search. Start with one content mode: highlights for compact agent context, text for broad page context, or summary for Exa-side compression.

Quick Start (cURL)

Basic text extraction

curl -sS -X POST "https://api.exa.ai/contents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "urls": ["https://example.com"],
    "text": true
  }'

Highlights with freshness control

curl -sS -X POST "https://api.exa.ai/contents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "urls": ["https://arxiv.org/abs/2307.06435"],
    "highlights": {
      "query": "methodology and results"
    },
    "maxAgeHours": 24,
    "livecrawlTimeout": 12000
  }'

Endpoint

POST https://api.exa.ai/contents

Authentication: x-api-key: <API_KEY> header. Exa also accepts Authorization: Bearer <API_KEY>, but prefer x-api-key in cURL examples for consistency.

Use this endpoint for known-URL extraction. If the agent needs discovery or ranking first, use POST /search.

Parameters

Core request parameters

Text object options

Highlights object options

Prefer highlights: true for the highest-quality default. Only use object form when the agent needs a custom focus or budget.

Summary object options

Content Modes

On /contents, text, highlights, and summary are top-level request fields.

Avoid requesting multiple modes unless the caller truly needs multiple views of the same page.

Freshness and Crawling

Use maxAgeHours as the normative freshness control.

Set livecrawlTimeout when live crawling should not block past a fixed budget.

Subpages and extras

Use subpages and subpageTarget when linked pages matter.

curl -sS -X POST "https://api.exa.ai/contents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "urls": ["https://docs.example.com"],
    "text": {
      "maxCharacters": 5000
    },
    "subpages": 10,
    "subpageTarget": ["api", "reference", "guide"],
    "extras": {
      "links": 10,
      "imageLinks": 5
    }
  }'

Start with subpages around 5 to 10, then increase only when the caller needs broader site coverage.

Response Fields and Statuses

Inspect statuses even when the HTTP status is 200. The endpoint can succeed for one URL and fail for another in the same request.

curl -sS -X POST "https://api.exa.ai/contents" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $EXA_API_KEY" \
  -d '{
    "urls": ["https://example.com", "https://bad.example"],
    "highlights": true
  }' | jq '{results, statuses}'

Common per-URL error tags include CRAWL_NOT_FOUND, CRAWL_TIMEOUT, CRAWL_LIVECRAWL_TIMEOUT, SOURCE_NOT_AVAILABLE, UNSUPPORTED_URL, and CRAWL_UNKNOWN_ERROR.

Anti-Patterns

• Keep text, highlights, and summary at the top level on /contents.
• Do not wrap extraction options in a contents object; that nesting belongs to /search.
• Do not assume HTTP 200 means every URL succeeded; inspect statuses.
• Do not send stream: true; /contents is not a streaming endpoint.
• Do not send tokensNum; use text.maxCharacters to cap extracted text.
• Do not use useAutoprompt, numSentences, highlightsPerUrl, or older livecrawl string values in new requests.
• Prefer maxAgeHours for freshness and pair it with livecrawlTimeout when crawl latency matters.
• Use subpageTarget with subpages; otherwise subpage selection is best effort.
• Pick one of highlights, text, or summary by default. Stack modes only when the caller truly needs multiple views of each page.

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.