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

# Tavily

Fronts the AI-search API of [Tavily](https://tavily.com). Its sibling endpoints all live on the one host `api.tavily.com` and are mounted under `/tavily`:

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

Only `POST` is mounted — the method Tavily documents for its action endpoints. All controls live in the JSON body, which is relayed without modification.

## Endpoints

Exactly these endpoints are admitted; anything else is refused with the gateway's own `404` and never reaches Tavily.

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

The `/usage` endpoint — credit and limit metadata for the whole account — is **intentionally left unexposed**; a per-client token has no legitimate claim on usage data for the shared account.

## Credential handling

Tavily reads its key from `Authorization: Bearer` — the very header carrying your gateway token — so the gateway **replaces** that header with the Tavily key:

* **`Authorization` is overwritten with Tavily's secret key.** Your gateway token stops at the gateway and never travels upstream.
* No query-param form of the key exists on Tavily's side, so nothing gets removed from the query string.

## Examples

#### Search

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

#### Extract

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

Responses arrive as Tavily's JSON, untouched. Field-level request and response detail lives in [Tavily's documentation](https://docs.tavily.com); the gateway modifies neither.