> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.auxiliar.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.auxiliar.ai/_mcp/server.

# Tavily

Proxies [Tavily](https://tavily.com)'s AI-search API. The gateway exposes Tavily's sibling endpoints under `/tavily`, all on the single host `api.tavily.com`:

```
POST /tavily/<endpoint>   → https://api.tavily.com/<endpoint>
```

`POST` only — the method Tavily's action endpoints document. Every control travels in the JSON body and is forwarded unchanged.

## Endpoints

The gateway accepts exactly this whitelist; any other subpath returns the gateway's `404` without reaching Tavily.

| Endpoint  | Purpose                   |
| --------- | ------------------------- |
| `search`  | AI web search             |
| `extract` | Extract content from URLs |
| `crawl`   | Crawl a site              |
| `map`     | Map a site's URLs         |

Tavily's `/usage` endpoint (account-wide credit/limit metadata) is **deliberately not exposed** — per-client tokens have no business reading the shared account's usage.

## What the gateway injects and strips

Tavily authenticates with the `Authorization: Bearer` header — the **same** header you use for your gateway token. So the gateway **overwrites** it with the injected Tavily key:

* **The `Authorization` header is overwritten** with the secret Tavily key. Your gateway token is consumed by the gateway and never reaches Tavily.
* Tavily has no query-param spelling of the key, so nothing is dropped from the query string.

## Examples

```bash
curl -X POST "$GATEWAY/tavily/search" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "latest cloudflare workers features"}'
```

```bash
curl -X POST "$GATEWAY/tavily/extract" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com"]}'
```

The response is Tavily's JSON, returned unchanged. For request and response fields, follow [Tavily's documentation](https://docs.tavily.com) — the gateway does not alter them.