Use this skill for web search, extraction, mapping, crawling, and research via Tavily’s REST API when web searches are needed and no built-in tool is available, or when Tavily’s LLM-friendly format is beneficial.
npxskills add intellectronica/agent-skills--skill tavilyLoading…
Provide a curl-based interface to Tavily’s REST API for web search, extraction, mapping, crawling, and optional research. Return structured results suitable for LLM workflows and multi-step investigations.
TAVILY_API_KEY in the environment.TAVILY_API_KEY is missing, prompt the user to provide the API key before proceeding.https://api.tavily.comAuthorization: Bearer $TAVILY_API_KEYContent-Type: application/jsonX-Project-ID: <project-id> if project attribution is needed.Use for web search with optional answer and content extraction.
Recommended minimal request:
curl -sS -X POST "https://api.tavily.com/search" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TAVILY_API_KEY" \
-d '{
"query": "<query>",
"search_depth": "basic",
"max_results": 5,
"include_answer": true,
"include_raw_content": false,
"include_images": false
}'
Key parameters (all optional unless noted):
query (required): search textsearch_depth: basic | advanced | fast | ultra-fastchunks_per_source: 1–3 (advanced only)max_results: 0–20topic: general | news | financeExpected response fields:
answer (if requested), results[] with title, url, content, score, raw_content (optional), favicon (optional)response_time, usage, request_idUse for extracting content from specific URLs.
curl -sS -X POST "https://api.tavily.com/extract" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TAVILY_API_KEY" \
-d '{
"urls": ["https://example.com/article"],
"query": "<optional intent for reranking>",
"chunks_per_source": 3,
"extract_depth": "basic",
"format": "markdown",
"include_images": false,
"include_favicon": false
}'
Key parameters:
urls (required): array of URLsquery: rerank chunks by intentchunks_per_source: 1–5 (only when query provided)extract_depth: basic | advancedformat: markdown | texttimeout: 1–60 secondsExpected response fields:
results[] with url, raw_content, images, faviconfailed_results[], response_time, usage, request_idUse for generating a site map (URL discovery only).
curl -sS -X POST "https://api.tavily.com/map" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TAVILY_API_KEY" \
-d '{
"url": "https://docs.tavily.com",
"max_depth": 1,
"max_breadth": 20,
"limit": 50,
"allow_external": true
}'
Key parameters:
url (required)instructions: natural language guidance (raises cost)max_depth: 1–5max_breadth: 1+limit: 1+select_paths, select_domains, exclude_paths, exclude_domains: arrays of regex stringsallow_external: booleantimeout: 10–150 secondsExpected response fields:
base_url, results[] (list of URLs), response_time, usage, request_idUse for site traversal with built-in extraction.
curl -sS -X POST "https://api.tavily.com/crawl" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TAVILY_API_KEY" \
-d '{
"url": "https://docs.tavily.com",
"instructions": "Find all pages about the Python SDK",
"max_depth": 1,
"max_breadth": 20,
"limit": 50,
"extract_depth": "basic",
"format": "markdown",
"include_images": false
}'
Key parameters:
url (required)instructions: optional; raises cost and enables chunks_per_sourcechunks_per_source: 1–5 (only with instructions)max_depth, max_breadth, limit: same as mapextract_depth: basic | advancedExpected response fields:
base_url, results[] with url, raw_content, faviconresponse_time, usage, request_idUse when a query needs multi-step analysis and citations.
curl -sS -X POST "https://api.tavily.com/research" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TAVILY_API_KEY" \
-d '{
"input": "<research question>",
"model": "auto",
"stream": false,
"citation_format": "numbered"
}'
Expected response fields:
request_id, created_at, status (pending), input, model, response_timecurl -sS -X GET "https://api.tavily.com/research/<request_id>" \
-H "Authorization: Bearer $TAVILY_API_KEY"
Expected response fields:
status: completedcontent: report text or structured objectsources[]: { title, url, favicon }Set "stream": true in the POST body and use curl with -N to stream events:
curl -N -X POST "https://api.tavily.com/research" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $TAVILY_API_KEY" \
-d '{"input":"<question>","stream":true,"model":"pro"}'
Handle SSE events (tool calls, tool responses, content chunks, sources, done).
search, extract, map, and crawl as the primary endpoints for discovery and content retrieval.search_depth: basic, max_results: 5) unless deeper recall is needed.TAVILY_API_KEY.max_depth/limit or use search_depth: basic.max_results or chunks_per_source.time_range: day|week|month|year|d|w|m|ystart_date, end_date: YYYY-MM-DDinclude_answer: false | true | basic | advancedinclude_raw_content: false | true | markdown | textinclude_images: booleaninclude_image_descriptions: booleaninclude_favicon: booleaninclude_domains, exclude_domains: string arrayscountry: country name (general topic only)auto_parameters: booleaninclude_usage: booleaninclude_usage: booleaninclude_usage: booleanformat: markdown | textinclude_images, include_favicon, allow_externaltimeout: 10–150 secondsinclude_usage: boolean
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).