{"openapi":"3.1.0","info":{"title":"Tavily API","description":"Pay-per-call access to the Tavily web search and content extraction API. No accounts, no subscriptions — pay per request with x402 or MPP.","version":"1.0.0","x-guidance":"POST /api/search with { \"query\": string } to run a web search. POST /api/extract with { \"urls\": string | string[] } to extract page content. GET /api/health is unprotected. See /openapi.json for full request/response schemas.","guidance":"POST /api/search with { \"query\": string } to run a web search. POST /api/extract with { \"urls\": string | string[] } to extract page content. GET /api/health is unprotected. See /openapi.json for full request/response schemas."},"servers":[{"url":"http://localhost:3000"}],"tags":[{"name":"Crawl"},{"name":"Extract"},{"name":"Health"},{"name":"Map"},{"name":"Search"}],"paths":{"/api/search":{"post":{"operationId":"search","summary":"Tavily Search — run a web search and get relevance-ranked results, optionally with an LLM-generated answer, images, and raw page content.","tags":["Search"],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0","max":"0.02"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"description":"The search query to execute."},"search_depth":{"description":"Latency vs. relevance tradeoff. Default: basic.","type":"string","enum":["basic","advanced","fast","ultra-fast"]},"topic":{"description":"Search category. Default: general.","type":"string","enum":["general","news","finance"]},"chunks_per_source":{"description":"Max relevant snippets per source (advanced depth only).","type":"integer","minimum":1,"maximum":3},"max_results":{"description":"Maximum number of results to return. Default: 5.","type":"integer","minimum":0,"maximum":20},"time_range":{"description":"Filter results by publish/update date range.","type":"string","enum":["day","week","month","year","d","w","m","y"]},"start_date":{"description":"Only return results after this date (YYYY-MM-DD).","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end_date":{"description":"Only return results before this date (YYYY-MM-DD).","type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"include_answer":{"description":"Include an LLM-generated answer to the query.","anyOf":[{"type":"boolean"},{"type":"string","enum":["basic","advanced"]}]},"include_raw_content":{"description":"Include cleaned page content for each result.","anyOf":[{"type":"boolean"},{"type":"string","enum":["markdown","text"]}]},"include_images":{"description":"Include query-related images.","type":"boolean"},"include_image_descriptions":{"description":"Add descriptive text for each returned image.","type":"boolean"},"include_favicon":{"description":"Include a favicon URL for each result.","type":"boolean"},"include_domains":{"description":"Restrict results to these domains.","maxItems":300,"type":"array","items":{"type":"string"}},"exclude_domains":{"description":"Exclude results from these domains.","maxItems":150,"type":"array","items":{"type":"string"}},"country":{"description":"Boost results from a specific country.","type":"string"},"auto_parameters":{"description":"Let Tavily auto-configure search parameters.","type":"boolean"},"exact_match":{"description":"Return only exact phrase matches.","type":"boolean"},"include_usage":{"description":"Include credit usage information in the response.","type":"boolean"}},"required":["query"]}}}},"responses":{"200":{"description":"Successful response"},"402":{"description":"Payment Required"}}}},"/api/extract":{"post":{"operationId":"extract","summary":"Tavily Extract — pull cleaned content (markdown or text) from one or more URLs, optionally with images and favicons.","tags":["Extract"],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0","max":"0.08"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"urls":{"anyOf":[{"type":"string","format":"uri"},{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","format":"uri"}}],"description":"A single URL or list of URLs (max 20) to extract content from."},"query":{"description":"User intent used to rerank extracted content chunks.","type":"string"},"chunks_per_source":{"description":"Max relevant chunks per source (only applies with `query`).","type":"integer","minimum":1,"maximum":5},"extract_depth":{"description":"Extraction scope. Advanced retrieves tables/embedded content.","type":"string","enum":["basic","advanced"]},"include_images":{"description":"Include images extracted from the URLs.","type":"boolean"},"include_favicon":{"description":"Include a favicon URL for each result.","type":"boolean"},"format":{"description":"Content format. Default: markdown.","type":"string","enum":["markdown","text"]},"timeout":{"description":"Seconds to wait before timing out per URL.","type":"number","minimum":1,"maximum":60},"include_usage":{"description":"Include credit usage information in the response.","type":"boolean"}},"required":["urls"]}}}},"responses":{"200":{"description":"Successful response"},"402":{"description":"Payment Required"}}}},"/api/crawl":{"post":{"operationId":"crawl","summary":"Tavily Crawl — crawl a site from a root URL following links, returning cleaned content for each page reached.","tags":["Crawl"],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0","max":"0.48"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The root URL to begin from."},"instructions":{"description":"Natural language instructions for the crawler. Doubles the mapping cost (2 credits per 10 pages instead of 1).","type":"string"},"max_depth":{"description":"How far from the root URL to explore. Default: 1.","type":"integer","minimum":1,"maximum":5},"max_breadth":{"description":"Max links to follow per page level. Default: 20.","type":"integer","minimum":1,"maximum":500},"limit":{"description":"Total number of links to process before stopping. Default: 50. Determines the price (see pricing).","type":"integer","minimum":1,"maximum":80},"select_paths":{"description":"Regex patterns — only include URLs with matching paths.","type":"array","items":{"type":"string"}},"select_domains":{"description":"Regex patterns — restrict crawling to matching domains.","type":"array","items":{"type":"string"}},"exclude_paths":{"description":"Regex patterns — exclude URLs with matching paths.","type":"array","items":{"type":"string"}},"exclude_domains":{"description":"Regex patterns — exclude matching domains.","type":"array","items":{"type":"string"}},"allow_external":{"description":"Include external-domain links in the results. Default: true.","type":"boolean"},"timeout":{"description":"Max seconds to wait before timing out. Default: 150.","type":"number","minimum":10,"maximum":150},"include_usage":{"description":"Include credit usage information in the response.","type":"boolean"},"chunks_per_source":{"description":"Max relevant chunks returned per source. Default: 3.","type":"integer","minimum":1,"maximum":5},"include_images":{"description":"Include images in the crawl results.","type":"boolean"},"extract_depth":{"description":"Extraction scope. Advanced retrieves tables/embedded content.","type":"string","enum":["basic","advanced"]},"format":{"description":"Content format. Default: markdown.","type":"string","enum":["markdown","text"]},"include_favicon":{"description":"Include a favicon URL for each result.","type":"boolean"}},"required":["url"]}}}},"responses":{"200":{"description":"Successful response"},"402":{"description":"Payment Required"}}}},"/api/map":{"post":{"operationId":"map","summary":"Tavily Map — traverse a site from a root URL and return its link structure (a list of discovered URLs), without extracting page content.","tags":["Map"],"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0","max":"0.16"},"protocols":[{"x402":{}}]},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The root URL to begin from."},"instructions":{"description":"Natural language instructions for the crawler. Doubles the mapping cost (2 credits per 10 pages instead of 1).","type":"string"},"max_depth":{"description":"How far from the root URL to explore. Default: 1.","type":"integer","minimum":1,"maximum":5},"max_breadth":{"description":"Max links to follow per page level. Default: 20.","type":"integer","minimum":1,"maximum":500},"limit":{"description":"Total number of links to process before stopping. Default: 50. Determines the price (see pricing).","type":"integer","minimum":1,"maximum":80},"select_paths":{"description":"Regex patterns — only include URLs with matching paths.","type":"array","items":{"type":"string"}},"select_domains":{"description":"Regex patterns — restrict crawling to matching domains.","type":"array","items":{"type":"string"}},"exclude_paths":{"description":"Regex patterns — exclude URLs with matching paths.","type":"array","items":{"type":"string"}},"exclude_domains":{"description":"Regex patterns — exclude matching domains.","type":"array","items":{"type":"string"}},"allow_external":{"description":"Include external-domain links in the results. Default: true.","type":"boolean"},"timeout":{"description":"Max seconds to wait before timing out. Default: 150.","type":"number","minimum":10,"maximum":150},"include_usage":{"description":"Include credit usage information in the response.","type":"boolean"}},"required":["url"]}}}},"responses":{"200":{"description":"Successful response"},"402":{"description":"Payment Required"}}}},"/api/health":{"get":{"operationId":"health","summary":"health","tags":["Health"],"responses":{"200":{"description":"Successful response"}}}}}}