Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 65 additions & 0 deletions connectors/tavily/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# Tavily

Community submission (`owner: community`), not submitted by Tavily.

## Docs

- Headers and authentication: https://docs.tavily.com/documentation/api-headers.
Base URL `https://api.tavily.com`, `Authorization: Bearer tvly-...`. The
optional `X-Project-ID`, `X-Session-Id` and `X-Human-Id` headers are not
forwarded.
- Probe: `GET /usage`, https://docs.tavily.com/documentation/api-reference/endpoint/usage.
Returns `{"key": {"usage", "limit", ...}, "account": {"current_plan", ...}}`
and is the only documented key-information endpoint. It spends no credits
(the credits page lists costs for search, extract, crawl, map and research
only). Tavily limits it to 10 requests per 10 minutes, which is plenty for a
key check but means a user hammering "Test" will see a 429. Asserts `key`
and `account` are objects, `key.usage` is an integer, `account.current_plan`
is a non-empty string and `detail` (the error wrapper) is absent. The
alternative, a one-result `POST /search`, costs a credit per check.
- Routes, one page per endpoint under
https://docs.tavily.com/documentation/api-reference/endpoint/: `search`,
`extract`, `crawl`, `map`, `research` (POST, returns 201 with a
`request_id`), `research-get` (`GET /research/{request_id}`) and `usage`.
Research ids are UUIDs and fit the default `:param` rule.
Tavily's crawl timeout defaults to 150 seconds. Sprites waits 120 seconds
for the response headers, so the crawl example sets Tavily's `timeout` to
90 seconds. See https://docs.tavily.com/documentation/api-reference/endpoint/crawl#body-timeout.
- Credits: https://docs.tavily.com/documentation/api-credits. Rate limits:
https://docs.tavily.com/documentation/rate-limits (per account; 100 RPM on
the free Researcher plan, 1,000 or more on paid plans; `/crawl` and `/map`
100 RPM, `/research` 20 RPM, `/usage` 10 per 10 minutes). 429 carries
`Retry-After`, which is forwarded; there is no request-id response header
(the id is in the body as `request_id`). Setting `instructions` raises the
mapping charge from 1 to 2 credits per 10 successful pages. A crawl also
incurs extraction charges.
- Errors are `{"detail": {"error": "..."}}` with 400, 401, 403 (crawl/map
only), 429, 432 (plan or key limit), 433 (pay-as-you-go limit), 434 (flex
tier) and 500; a 422 on search lists the invalid fields under `detail` and
echoes the offending input value. A wrong key is 401, so no `errors` rule
is needed.
- Left out on purpose: the enterprise key-management endpoints (generate,
deactivate and inspect keys, organization usage), `GET /logs`,
`POST /feedback` and keyless access mode (`X-Tavily-Access-Mode: keyless`,
a different auth scheme for `/search` and `/extract` only).

## Verification

On 2026-11-19 `node scripts/probe.mjs tavily --key-env BOGUS` with a made-up
key returned HTTP 401 `{"detail": {"error": "Unauthorized: missing or invalid
API key."}}` and was classified `invalid_api_key`. Each `POST` route
(`/search`, `/extract`, `/crawl`, `/map`, `/research`) and
`GET /research/:request_id` also answered 401 to the made-up key, confirming
the paths exist; `GET /search` is 405. The probe has not been run with a real
key; the assertions follow the documented usage response.
`node scripts/check-connectors.mjs tavily` and the ajv schema check pass.

## Icons

Tavily publishes no brand page in its docs. Both icons are the square mark
from the logo Tavily serves on its documentation site
(https://mintlify.s3.us-west-1.amazonaws.com/tavilyai/logo/light.svg, the
first path of the file, cropped to `viewBox="0 0 110 109"`; the wordmark
paths are dropped). `icon.svg` keeps the original ink `#1F1E1E`; `mark.svg` is
the same path in `currentColor`. The logo is Tavily's trademark, used here to
identify the service; no licence is claimed.
117 changes: 117 additions & 0 deletions connectors/tavily/connector.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
{
"$schema": "https://raw.githubusercontent.com/superfly/sprites-connectors/main/v1/schema.json",
"format_version": 1,
"name": "tavily",
"display_name": "Tavily",
"tier": "community",
"owner": "community",
"base_url": "https://api.tavily.com",
"description": "Web search, page extraction, site crawling and mapping, and deep research for agents",
"long_description": "Bring a Tavily API key; the gateway keeps it off your Sprite and sends it as a bearer token. Saving, replacing or testing the key reads the key's usage counters (GET /usage), which costs no credits. A Sprite can then search the web, extract page content, crawl and map sites, start a research task and poll its result, and read usage. Every search, extract, crawl, map and research request uses your Tavily credits (1,000 are free each month on the Researcher plan). API key management, organization usage, logs and feedback endpoints are not forwarded.",
"website_url": "https://app.tavily.com/home",
"auth": "bearer",
"allowed_paths": [
{"methods": ["POST"], "pattern": "/search"},
{"methods": ["POST"], "pattern": "/extract"},
{"methods": ["POST"], "pattern": "/crawl"},
{"methods": ["POST"], "pattern": "/map"},
{"methods": ["POST"], "pattern": "/research"},
{"methods": ["GET"], "pattern": "/research/:request_id"},
{"methods": ["GET"], "pattern": "/usage"}
],
"forward_response_headers": ["retry-after"],
"probe": {
"method": "GET",
"path": "/usage",
"label": "key usage",
"expect": [
["key", "map"],
["key.usage", "integer"],
["account", "map"],
["account.current_plan", "text"],
["detail", "absent"]
]
},
"examples": [
{
"title": "Search the web (1 credit)",
"method": "POST",
"path": "/search",
"json": {"query": "Fly.io Sprites", "max_results": 5, "search_depth": "basic", "include_answer": true},
"notes": ["`search_depth: \"advanced\"` costs 2 credits and returns better-ranked content chunks; `topic` can be `general`, `news` or `finance`."]
},
{
"title": "Extract the content of up to 20 pages as Markdown (1 credit per 5 URLs)",
"method": "POST",
"path": "/extract",
"json": {"urls": ["https://fly.io/sprites"], "format": "markdown"},
"notes": ["Check `failed_results` as well as `results`; a 200 can carry both."]
},
{
"title": "Map the URLs of a site (1 credit per 10 successful pages)",
"method": "POST",
"path": "/map",
"json": {"url": "https://fly.io/docs", "max_depth": 1, "limit": 20}
},
{
"title": "Crawl a site and extract each page (mapping plus extraction credits)",
"method": "POST",
"path": "/crawl",
"json": {"url": "https://fly.io/docs/sprites", "max_depth": 1, "limit": 10, "instructions": "Pages about running agents in Sprites", "timeout": 90},
"notes": ["With instructions, mapping costs 2 credits per 10 successful pages, plus extraction credits. The 90-second Tavily timeout leaves time for the response to reach the gateway."]
},
{
"title": "Start a research task (4 to 250 credits depending on model and length)",
"method": "POST",
"path": "/research",
"json": {"input": "What are the trade-offs between persistent sandboxes and ephemeral containers for AI coding agents?", "model": "mini", "output_length": "short"},
"notes": ["Returns 201 with a `request_id` and `status: pending`; poll `GET /research/REQUEST_ID` until `status` is `completed` or `failed`."]
},
{
"title": "Poll a research task; replace REQUEST_ID",
"path": "/research/REQUEST_ID?include_usage=true"
},
{
"title": "Read the key's and account's usage",
"path": "/usage",
"notes": ["Tavily allows 10 usage requests per 10 minutes; the key check uses one."]
}
],
"messages": {
"400": "Tavily rejected the request (%{status}); check the body's detail.error",
"422": "Tavily could not validate the request parameters; see detail for the field",
"429": "Tavily rate limit reached; wait for the Retry-After header and retry",
"432": "Tavily plan or key usage limit exceeded; raise the limit or upgrade at app.tavily.com",
"433": "Tavily pay-as-you-go limit exceeded; raise it at app.tavily.com",
"434": "Tavily live content fetching (max_age_hours) is unavailable on this plan right now; retry without it",
"provider_unreachable": "Could not reach Tavily; retry later"
},
"discovery": {
"categories": ["search", "web-scraping"],
"keywords": ["tavily", "web search", "search", "extract", "crawl", "site map", "research", "page contents", "retrieval"]
},
"icon_svg": {"file": "icon.svg"},
"icon_bg_class": "bg-neutral-500/20",
"presentation": {
"tagline": "Search, extract, crawl and research the web from a Sprite without putting your Tavily key on it.",
"setup": "Sign in at app.tavily.com, open the home page's API Keys section and create a key (it starts with `tvly-`). The free Researcher plan includes 1,000 credits a month.",
"key_label": "API key",
"key_placeholder": "tvly-...",
"notices": [
{
"title": "Billing",
"body": "Saving or testing the key reads `GET /usage` and spends no credits. Basic search costs 1 credit and advanced search costs 2. Extract costs 1 credit per 5 successful URLs, or 2 with `extract_depth: \"advanced\"`. Map costs 1 credit per 10 successful pages, or 2 with `instructions`. Crawl adds the mapping and extraction costs. Research costs 4 to 110 credits with `mini` and 15 to 250 with `pro`. Add `include_usage: true` where supported to see what the request cost. Pay-as-you-go is $0.008 per credit."
},
{
"title": "Scope",
"body": "Only `POST /search`, `POST /extract`, `POST /crawl`, `POST /map`, `POST /research`, `GET /research/:request_id` and `GET /usage` are forwarded. API key management, organization usage, request logs and feedback are not. Tavily's rate limits apply per account: 100 requests a minute on the free plan, 1,000 or more on paid plans, with `/crawl` and `/map` at 100 a minute, `/research` at 20 and `/usage` at 10 per 10 minutes."
}
],
"usage_notes": [
"For `POST /crawl`, set `timeout` below the gateway's 120-second response deadline. Tavily defaults to 150 seconds. Use a smaller `limit` or `max_depth` if a crawl takes too long.",
"Research runs in the background: `POST /research` returns 201 with a `request_id`, and `GET /research/:request_id` answers 202 while it is pending and 200 when it is complete or failed. Streaming (`stream: true`) sends Server-Sent Events on the same route.",
"Error bodies are `{\"detail\": {\"error\": \"...\"}}`; a 422 lists the invalid fields under `detail` instead. Tavily uses 432 and 433 for plan and pay-as-you-go limits, which the gateway passes through."
],
"mark_svg": {"file": "mark.svg"}
}
}
1 change: 1 addition & 0 deletions connectors/tavily/icon.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions connectors/tavily/mark.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.