> ## Documentation Index
> Fetch the complete documentation index at: https://novita.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tavily Search

Tavily is a web data retrieval API designed for developers and AI applications. This document describes the Tavily passthrough endpoints exposed by the platform gateway. It is based on Tavily's Search API with platform route prefixes applied.

Base URL example: `https://api.novita.ai`

Search the internet by keyword or natural-language question and retrieve a list of matching results (title, URL, summary/snippet, etc.).

## Request Headers

All endpoints require platform API authentication.

<ParamField header="Content-Type" type="string" required>
  Use `application/json`.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Platform API key, formatted as `Bearer <api_key>`.
</ParamField>

## Request Body

<ParamField body="query" type="string" required>
  Search query. Minimum length is 1.
</ParamField>

<ParamField body="search_depth" type="string[]" required={false}>
  Search mode. Common values include `advanced`, `basic`, `fast`, `ultra-fast`. `basic` is set as the default value.
</ParamField>

<ParamField body="chunks_per_source" type="integer" required={false}>
  Max number of content snippets per source to return. Default is `3`; range is `1` to `3`. Available only when `search_depth` is `advanced`.
</ParamField>

<ParamField body="max_results" type="integer" required={false}>
  Max number of results to return. Default is `5`; supported public range is `1` to `20`.
</ParamField>

<ParamField body="topic" type="string[]" required={false}>
  Data category hint. Known values include `news`, `general`, and `finance`.
</ParamField>

<ParamField body="time_range" type="string[]" required={false}>
  Include links published or updated from the time range to now. Common values include `day`,`d`, `week`, `w`, `month`, `m`, `year`, and `y`.
</ParamField>

<ParamField body="start_date" type="string" required={false}>
  Include links published after this YYYY-MM-DD date-time.
</ParamField>

<ParamField body="end_date" type="string" required={false}>
  Include links published before this YYYY-MM-DD date-time.
</ParamField>

<ParamField body="include_answer" type="boolean | string[]" required={false}>
  Returns an LLM-generated answer. `basic` and `true` returns quick answers; `advanced` returns detailed answers.
</ParamField>

<ParamField body="include_raw_content" type="boolean | string[]" required={false}>
  Returns result in HTML content. `markdown` or `true` returns in markdown; `text` returns in plain text.
</ParamField>

<ParamField body="include_images" type="boolean " required={false}>
  Returns a list of images along with the response.
</ParamField>

<ParamField body="include_images_descriptions" type="boolean " required={false}>
  Includes a description to each image. Only works when `include_images` is `true`.
</ParamField>

<ParamField body="include_favicon" type="boolean " required={false}>
  Include favicon URL from result.
</ParamField>

<ParamField body="include_domains" type="string[] " required={false}>
  Restrict results to these domains. Maximum 300 domains.
</ParamField>

<ParamField body="exclude_domains" type="string[] " required={false}>
  Exclude results from these domains. Maximum 150 domains.
</ParamField>

<ParamField body="country" type="string[]" required={false}>
  Prioritize results from specified country. Only works when topic is `general`. Known values include `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`, `south africa`, `south korea`, `south sudan`, `spain`, `sri lanka`, `sudan`, `sweden`, `slovakia`, `slovenia`, `somalia`, `south africa`, `south korea`, `south sudan`, `spain`, `sri lanka`, `sudan`, `sweden`, `switzerland`, `syria`, `taiwan`, `tajikista`, `tanzania`, `thailand`, `togo`, `trinidad and tobago`, `tunisia`, `turkey`, `turkmenistan`, `uganda`, `ukraine`, `united arab emirates`, `united kingdom`, `united states`, `uruguay`, `uzbekistan`, `venezuela`, `vietnam`, `yemen`, `zambia`, and `zimbabwe`.
</ParamField>

<ParamField body="auto_parameters" type="boolean" required={false}>
  Automatically sets parameters for search. `include_answer`, `include_raw_content`,and `max_results` must be set manually if needed. `search_depth` may be set to `advanced` if `search_depth` is not explicitly set.
</ParamField>

<ParamField body="exact_match" type="boolean" required={false}>
  Returns results containing the exact quoted phrase(s) from the query. Punctuation is ignored.
</ParamField>

## Request Example

```bash theme={"system"}
curl -s -X POST 'https://api.novita.ai/v3/tavily/search' \
  -H 'Authorization: Bearer sk-123' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Who is Leo Messi?",
    "auto_parameters": false,
    "topic": "general",
    "search_depth": "basic",
    "chunks_per_source": 3,
    "max_results": 5,
    "include_answer": false,
    "include_raw_content": false,
    "include_images": false
  }'
```

## Response

<ResponseField name="query" type="string" required={false}>
  Executed search query.
</ResponseField>

<ResponseField name="answer" type="string" required={false}>
  LLM-generated answer only when `include_answer`is requested.
</ResponseField>

<ResponseField name="images" type="object[]" required={false}>
  List of images from image search. Returned if `include_images` is `true`. Image `url` and `description` are included if `include_image_description` is `true`. See [Images Output Object](#images-output-object).
</ResponseField>

<ResponseField name="results" type="object[]" required={false}>
  Search results.
</ResponseField>

<ResponseField name="response_time" type="float" required={false}>
  Request duration in seconds.
</ResponseField>

<ResponseField name="auto_parameters" type="object" required={false}>
  Dictionary of automatically set parameters. Included if `auto_parameters` is `true`.
</ResponseField>

<ResponseField name="request_id" type="string" required={false}>
  Unique request identifier.
</ResponseField>

### Images Output Object

<ResponseField name="url" type="string" required={false}>
  Image URL.
</ResponseField>

<ResponseField name="description" type="string" required={false}>
  Image Description.
</ResponseField>

### Result Object

<ResponseField name="title" type="string" required={false}>
  Result title.
</ResponseField>

<ResponseField name="url" type="string" required={false}>
  Result URL.
</ResponseField>

<ResponseField name="content" type="string" required={false}>
  Result short snippet.
</ResponseField>

<ResponseField name="score" type="float" required={false}>
  Result relevance score.
</ResponseField>

<ResponseField name="raw_content" type="string" required={false}>
  Result HTML content. Returned if `include_raw_content` is `true`.
</ResponseField>

<ResponseField name="favicon" type="string" required={false}>
  Site favicon URL.
</ResponseField>

<ResponseField name="images" type="object[]" required={false}>
  List of images from search results. Returned if `include_images` is `true`. Image `url` and `description` are included if `include_image_description` is `true`. See [Images Output Object](#images-output-object).
</ResponseField>

## Errors

The platform may return standard HTTP errors before forwarding the request, and Tavily may return upstream errors after forwarding.

<ResponseField name="400" type="status" required={false}>
  Invalid request body or unsupported parameter value.
</ResponseField>

<ResponseField name="401" type="status" required={false}>
  Missing or invalid API key.
</ResponseField>

<ResponseField name="403" type="status" required={false}>
  Access denied by platform or upstream provider.
</ResponseField>

<ResponseField name="404" type="status" required={false}>
  Route or requested resource not found.
</ResponseField>

<ResponseField name="429" type="status" required={false}>
  Rate limit exceeded.
</ResponseField>

<ResponseField name="500" type="status" required={false}>
  Internal server error.
</ResponseField>

<ResponseField name="502" type="status" required={false}>
  Upstream provider error.
</ResponseField>

<ResponseField name="503" type="status" required={false}>
  Service unavailable.
</ResponseField>

## Notes

* All request bodies are JSON.
* Extra Tavily parameters not listed here may be passed through.
* Response shapes can vary depending on request options.
* This document intentionally omits billing-related fields.

## References

For more details, see the [Tavily Search API reference](https://docs.tavily.com/documentation/api-reference/endpoint/search).