> ## 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 Map

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 Map API with platform route prefixes applied.

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

Map a site starting from a root URL, following links to discover the structure of reachable pages and return their URLs.

## 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="url" type="string" required>
  Crawl root URL.
</ParamField>

<ParamField body="instructions" type="string" required={false}>
  Crawler instructions in natural language.
</ParamField>

<ParamField body="max_depth" type="integer" required={false}>
  Crawler depth limit. Default is `1`; range is `1` to `5`.
</ParamField>

<ParamField body="max_breadth" type="integer" required={false}>
  Max links per page. Default is `20`; range is `1` to `500`.
</ParamField>

<ParamField body="limit" type="integer" required={false}>
  Link processing limit for crawler. Default is `50`; minimum is `1`.
</ParamField>

<ParamField body="select_paths" type="string[]" required={false}>
  Restrict URL paths matching these regex patterns.
</ParamField>

<ParamField body="select_domains" type="string[]" required={false}>
  Restrict domains matching these regex patterns.
</ParamField>

<ParamField body="exclude_paths" type="string[]" required={false}>
  Exclude URL paths matching these regex patterns.
</ParamField>

<ParamField body="exclude_domains" type="string[]" required={false}>
  Exclude domains matching these regex patterns.
</ParamField>

<ParamField body="allow_external" type="boolean" required={false}>
  Include external domain links.
</ParamField>

<ParamField body="timeout" type="float" required={false}>
  Crawl operation time limit in seconds. Default is `150`; range is `10` to `150`.
</ParamField>

## Request Example

```bash theme={"system"}
curl -s -X POST 'https://api.novita.ai/v3/tavily/map' \
  -H 'Authorization: Bearer sk-123' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "docs.tavily.com",
    "instructions": "Find all pages about the Python SDK",
    "max_depth": 2,
    "max_breadth": 20,
    "limit": 50,
    "select_paths": ["/docs/.*"],
    "exclude_paths": ["/admin/.*"],
    "allow_external": false,
    "timeout": 60
  }'
```

## Response

<ResponseField name="base_url" type="string" required={false}>
  Crawl base URL.
</ResponseField>

<ResponseField name="results" type="string[]" required={false}>
  URLs discovered during mapping.
</ResponseField>

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

<ResponseField name="request_id" type="string" required={false}>
  Unique request identifier.
</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, or the URL is not supported.
</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 Map API reference](https://docs.tavily.com/documentation/api-reference/endpoint/map).