exa-contents

Files (1)

• SKILL.md

SKILL.md (first lines)

## 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

```bash
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

```bash
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

```text
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

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `urls` | string[] | Yes | - | URLs to extract content from. Use this for known URLs. |
| `text` | boolean or object | No | - | Return full page text as markdown. Object form supports `maxCharacters`, `includeHtmlTags`, `verbosity`, `includeSections`, and `excludeSections`. |
| `highlights` | boolean or object | No | - | Return key excerpts. Prefer `true` for agent workflows unless a custom focus is needed. |
| `summary` | boolean or object | No | - | Return per-page LLM summaries. Use when the caller wants Exa-side compression or structured extraction. |
| `maxAgeHours` | integer | No | - | Freshness control. `0` always live crawls; `-1` uses cache only; omit for default cache-first behavior with crawl fallback. |
| `livecrawlTimeout` | integer | No | `10000` | Timeout for live crawling in milliseconds. Use `10000` to `15000` for most freshness-sensitive calls. |
| `subpages` | integer | No | `0` | Number of linked subpages to crawl from each URL. |
| `subpageTarget` | string or string[] | No | - | Terms used to prioritize which subpages matter, such as `["api", "reference", "pricing"]`. |
| `extras.links` | integer | No | `0` | Number of links to extract from each page. |
| `extras.imageLinks` | integer | No | `0` | Number of image URLs to extract from each page. |
| `compliance` | string | No | - | Enterprise-only compliance mode, such as `hipaa`, when enabled for the account. |

### Text object options

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `maxCharacters` | integer | - | Character limit for returned text. Use this instead of `tokensNum`. |
| `includeHtmlTags` | boolean | `false` | Preserve HTML tags in output. |
| `verbosity` | string | `compact` | `compact`, `standard`, or `full`. Pair fresh section-aware extraction with `maxAgeHours: 0`. |
| `includeSections` | string[] | - | Only include selected sections: `header`, `navigation`, `banner`, `body`, `sidebar`, `footer`, `metadata`. |
| `excludeSections` | string[] | - | Exclude selected sections from the same section list. |

### Highlights object options

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

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `query` | string | - | Custom query guiding which excerpts are returned. |
| `maxCharacters` | integer | - | Cap highlight characters per URL. Omit unless the caller has a strict budget. |

### Summary object options

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `query` | string | - | Custom query for the summary. |
| `schema` | object | - | JSON Schema for structured per-page summaries. |

## Content Modes

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

| Mode | Best for | Notes |
| --- | --- | --- |
| `text` | Deep analysis and broad page context | Use `maxCharacters` to keep payloads bounded. |
| `highlights` | Agent workflows and factual lookups | Most token-efficient default. Excerpts are grounded in the source page. |
| `summary` | Compression or structured per-page extraction | Adds Exa-side synthesis per page. |

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.

| Value | Behavior |
| --- | --- |
| omitted | Use default cache-first behavior with crawl fallback when needed. |
| positive integer | Use cache if it is less than N hours old, otherwise live crawl. |

From MoizIbnYousaf/marketing-cli, MIT.

More from MoizIbnYousaf/marketing-cli