@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Tavily Search and Extract API
@base https://api.tavily.com/
@version 1.0.0
@auth Bearer bearer
@endpoints 7
@toc search(1), extract(1), crawl(1), map(1), research(2), usage(1)

@group search
@endpoint POST /search
@required {query: str}
@optional {search_depth: str(advanced/basic/fast/ultra-fast)=basic, chunks_per_source: int=3, max_results: int=5, topic: str(general/news/finance)=general, time_range: str(day/week/month/year/d/w/m/y)=null, start_date: str=null, end_date: str=null, include_answer: any=false, include_raw_content: any=false, include_images: bool=false, include_image_descriptions: bool=false, include_favicon: bool=false, include_domains: [str]=, exclude_domains: [str]=, country: str(afghanistan/albania/algeria/andorra/angola/argentina/armenia/australia/austria/azerbaijan/bahamas/bahrain/bangladesh/barbados/belarus/belgium/belize/benin/bhutan/bolivia/bosnia and herzegovina/botswana/brazil/brunei/bulgaria/burkina faso/burundi/cambodia/cameroon/canada/cape verde/central african republic/chad/chile/china/colombia/comoros/congo/costa rica/croatia/cuba/cyprus/czech republic/denmark/djibouti/dominican republic/ecuador/egypt/el salvador/equatorial guinea/eritrea/estonia/ethiopia/fiji/finland/france/gabon/gambia/georgia/germany/ghana/greece/guatemala/guinea/haiti/honduras/hungary/iceland/india/indonesia/iran/iraq/ireland/israel/italy/jamaica/japan/jordan/kazakhstan/kenya/kuwait/kyrgyzstan/latvia/lebanon/lesotho/liberia/libya/liechtenstein/lithuania/luxembourg/madagascar/malawi/malaysia/maldives/mali/malta/mauritania/mauritius/mexico/moldova/monaco/mongolia/montenegro/morocco/mozambique/myanmar/namibia/nepal/netherlands/new zealand/nicaragua/niger/nigeria/north korea/north macedonia/norway/oman/pakistan/panama/papua new guinea/paraguay/peru/philippines/poland/portugal/qatar/romania/russia/rwanda/saudi arabia/senegal/serbia/singapore/slovakia/slovenia/somalia/south africa/south korea/south sudan/spain/sri lanka/sudan/sweden/switzerland/syria/taiwan/tajikistan/tanzania/thailand/togo/trinidad and tobago/tunisia/turkey/turkmenistan/uganda/ukraine/united arab emirates/united kingdom/united states/uruguay/uzbekistan/venezuela/vietnam/yemen/zambia/zimbabwe)=null, auto_parameters: bool=false, exact_match: bool=false, include_usage: bool=false, safe_search: bool=false}
@returns(200) {query: str, answer: str, images: [map], results: [map], auto_parameters: map, response_time: num(float), usage: map, request_id: str}
@errors {400, 401, 429, 432, 433, 500}

@endgroup

@group extract
@endpoint POST /extract
@required {urls: any}
@optional {query: str, chunks_per_source: int=3, extract_depth: str(basic/advanced)=basic, include_images: bool=false, include_favicon: bool=false, format: str(markdown/text)=markdown, timeout: num(float)=None, include_usage: bool=false}
@returns(200) {results: [map], failed_results: [map], response_time: num(float), usage: map, request_id: str}
@errors {400, 401, 429, 432, 433, 500}

@endgroup

@group crawl
@endpoint POST /crawl
@required {url: str}
@optional {instructions: str, chunks_per_source: int=3, max_depth: int=1, max_breadth: int=20, limit: int=50, select_paths: [str]=null, select_domains: [str]=null, exclude_paths: [str]=null, exclude_domains: [str]=null, allow_external: bool=true, include_images: bool=false, extract_depth: str(basic/advanced)=basic, format: str(markdown/text)=markdown, include_favicon: bool=false, timeout: num(float)=150, include_usage: bool=false}
@returns(200) {base_url: str, results: [map], response_time: num(float), usage: map, request_id: str}
@errors {400, 401, 403, 429, 432, 433, 500}

@endgroup

@group map
@endpoint POST /map
@required {url: str}
@optional {instructions: str=null, max_depth: int=1, max_breadth: int=20, limit: int=50, select_paths: [str]=null, select_domains: [str]=null, exclude_paths: [str]=null, exclude_domains: [str]=null, allow_external: bool=true, timeout: num(float)=150, include_usage: bool=false}
@returns(200) {base_url: str, results: [str], response_time: num(float), usage: map, request_id: str}
@errors {400, 401, 403, 429, 432, 433, 500}

@endgroup

@group research
@endpoint POST /research
@required {input: str}
@optional {model: str(mini/pro/auto)=auto, stream: bool=false, output_schema: map{properties: map, required: [str]}=null, citation_format: str(numbered/mla/apa/chicago)=numbered}
@returns(201) {request_id: str, created_at: str, status: str, input: str, model: str, response_time: int}
@errors {400, 401, 429, 432, 433, 500}

@endpoint GET /research/{request_id}
@required {request_id: str}
@returns(200)
@returns(202) {request_id: str, status: str, response_time: int}
@errors {401, 404, 500}

@endgroup

@group usage
@endpoint GET /usage
@optional {X-Project-ID: str}
@returns(200) {key: map{usage: int, limit: int, search_usage: int, extract_usage: int, crawl_usage: int, map_usage: int, research_usage: int}, account: map{current_plan: str, plan_usage: int, plan_limit: int, paygo_usage: int, paygo_limit: int, search_usage: int, extract_usage: int, crawl_usage: int, map_usage: int, research_usage: int}}
@errors {401, 429}

@endgroup

@end