# Exa Web Search API

API key: `a7b64b9e-da0b-40da-89a0-0aff5a51a8c7`

Base URL: `https://api.exa.ai`

## Quick search (cURL)

```bash
export CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt

curl -s -X POST 'https://api.exa.ai/search' \
  -H 'x-api-key: a7b64b9e-da0b-40da-89a0-0aff5a51a8c7' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "your search query",
    "type": "auto",
    "numResults": 10,
    "contents": {"highlights": true}
  }'
```

## Structured / synthesized search (outputSchema)

`outputSchema` works on every search type. Pass a JSON schema and Exa returns a synthesized answer as structured JSON in `output.content`, with field-level citations in `output.grounding`.

```bash
curl -s -X POST 'https://api.exa.ai/search' \
  -H 'x-api-key: a7b64b9e-da0b-40da-89a0-0aff5a51a8c7' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "your search query",
    "type": "deep-lite",
    "systemPrompt": "Prefer official sources, collapse duplicate reporting, and keep the output grounded.",
    "outputSchema": {
      "type": "object",
      "required": ["summary", "items"],
      "properties": {
        "summary": {"type": "string", "description": "Overview of findings"},
        "items": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["title", "source"],
            "properties": {
              "title": {"type": "string"},
              "date": {"type": "string"},
              "source": {"type": "string"},
              "detail": {"type": "string"}
            }
          }
        }
      }
    },
    "numResults": 10,
    "contents": {"highlights": true}
  }'
```

### Schema controls
- `type`, `description`, `required`, `properties`, `items`
- Max nesting depth 2, max total properties 10
- Do NOT add citation or confidence fields — `/search` returns grounding data automatically

### Response shape (with outputSchema)
- `output.content` — structured JSON matching your schema
- `output.grounding` — array of `{field, citations: [{url, title}], confidence}` entries

## Search types

| Type | Latency | Best For |
|------|---------|----------|
| `auto` | ~1s | Most queries (default) |
| `fast` | ~450ms | Latency-sensitive |
| `instant` | ~250ms | Chat, autocomplete |
| `deep-lite` | ~4s | Cheaper synthesis |
| `deep` | 4-15s | Research, thorough results |
| `deep-reasoning` | 12-40s | Complex multi-step reasoning |

## Content modes

| Mode | Config | Best For |
|------|--------|----------|
| Highlights | `"highlights": true` | Token-efficient excerpts (preferred for agents) |
| Text | `"text": {"maxCharacters": 20000}` | Full content extraction, RAG |
| Summary | `"summary": true` or `{"query": "..."}` | LLM-written summary per result |

### Text tuning
- `text.verbosity`: `"compact"` (default) | `"full"`
- `text.includeHtmlTags`: boolean (default false)
- `text.maxCharacters`: hard cap on extracted text

## Freshness (maxAgeHours)

| Value | Behavior |
|-------|----------|
| `24` | Livecrawl if cache > 24h old |
| `0` | Always livecrawl (real-time data) |
| `-1` | Never livecrawl (cache only) |
| omit | Default (livecrawl as fallback) |

## Domain filtering

```json
{
  "includeDomains": ["arxiv.org", "github.com"],
  "excludeDomains": ["pinterest.com"]
}
```

## Other endpoints

| Endpoint | Use |
|----------|-----|
| `/contents` | Get clean content for known URLs |
| `/answer` | Grounded answer with citations (question-first UI) |

### /contents example

```bash
curl -s -X POST 'https://api.exa.ai/contents' \
  -H 'x-api-key: a7b64b9e-da0b-40da-89a0-0aff5a51a8c7' \
  -H 'Content-Type: application/json' \
  -d '{
    "urls": ["https://example.com/article"],
    "highlights": true
  }'
```

## Common mistakes to avoid

- ❌ `useAutoprompt` — deprecated, remove it
- ❌ `includeUrls` / `excludeUrls` — use `includeDomains` / `excludeDomains`
- ❌ Top-level `text`, `summary`, `highlights` on `/search` — must be inside `contents`
- ❌ `numSentences`, `highlightsPerUrl` — deprecated
- ❌ `tokensNum` — use `contents.text.maxCharacters`
- ❌ `livecrawl: "always"` — use `contents.maxAgeHours: 0`

## Resources

- Docs: https://exa.ai/docs
- Dashboard: https://dashboard.exa.ai
- API Status: https://status.exa.ai