Tavily REST API

Overview

Tavily provides LLM-optimized web search, content extraction, site mapping, and crawling via REST. Responses include summaries, chunks, and citations ready for downstream processing.

Quick Reference

When to Use

• Task requires live web information
• Built-in search tools are unavailable
• You need structured output (summaries, chunks, sources)
• Task requires site discovery or content extraction

When NOT to Use

• Built-in web search tool exists and works
• Task needs only cached/historical data
• API key is missing from keyring (check first)

Authentication

API key stored in macOS keyring. Retrieve with:

chezmoi secret keyring get --service=tavily --user=api_key

Base Configuration

Base URL: https://api.tavily.com
Auth:     Authorization: Bearer $(chezmoi secret keyring get --service=tavily --user=api_key)
Content:  Content-Type: application/json
Optional: X-Project-ID: <project-id>

Endpoints

1. Search — POST /search

Web search with optional AI-generated answer.

curl -sS -X POST "https://api.tavily.com/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(chezmoi secret keyring get --service=tavily --user=api_key)" \
  -d '{
    "query": "<query>",
    "search_depth": "basic",
    "max_results": 5,
    "include_answer": true,
    "include_raw_content": false,
    "include_images": false
  }'

Key parameters:

Response: answer, results[] (title, url, content, score), response_time, usage

2. Extract — POST /extract

Pull content from specific URLs.

curl -sS -X POST "https://api.tavily.com/extract" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(chezmoi secret keyring get --service=tavily --user=api_key)" \
  -d '{
    "urls": ["https://example.com/article"],
    "format": "markdown"
  }'

Key parameters:

Response: results[] (url, raw_content), failed_results[], response_time

3. Map — POST /map

Discover URLs on a domain (no content extraction).

curl -sS -X POST "https://api.tavily.com/map" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(chezmoi secret keyring get --service=tavily --user=api_key)" \
  -d '{
    "url": "https://docs.example.com",
    "max_depth": 1,
    "limit": 50
  }'

Key parameters:

Response: base_url, results[] (list of URLs), response_time

4. Crawl — POST /crawl

Map a site and extract content in one call.

curl -sS -X POST "https://api.tavily.com/crawl" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(chezmoi secret keyring get --service=tavily --user=api_key)" \
  -d '{
    "url": "https://docs.example.com",
    "max_depth": 1,
    "limit": 50,
    "format": "markdown"
  }'

Key parameters: Same as Map, plus:

Response: base_url, results[] (url, raw_content), response_time

5. Research — POST /research

Multi-step analysis with citations. Async workflow.

Start research:

curl -sS -X POST "https://api.tavily.com/research" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(chezmoi secret keyring get --service=tavily --user=api_key)" \
  -d '{
    "input": "<research question>",
    "model": "auto",
    "stream": false,
    "citation_format": "numbered"
  }'

Response: request_id, status (pending)

Check status:

curl -sS -X GET "https://api.tavily.com/research/<request_id>" \
  -H "Authorization: Bearer $(chezmoi secret keyring get --service=tavily --user=api_key)"

Response: status (completed), content (report), sources[]

Streaming: Set "stream": true and use curl -N for SSE events.

Defaults

Use conservative defaults unless deeper recall is needed:

• search_depth: basic
• max_results: 5
• include_raw_content: false

Error Handling