diff --git a/connectors/tavily/README.md b/connectors/tavily/README.md new file mode 100644 index 0000000..9a25ad9 --- /dev/null +++ b/connectors/tavily/README.md @@ -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. diff --git a/connectors/tavily/connector.json b/connectors/tavily/connector.json new file mode 100644 index 0000000..ef143e4 --- /dev/null +++ b/connectors/tavily/connector.json @@ -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"} + } +} diff --git a/connectors/tavily/icon.svg b/connectors/tavily/icon.svg new file mode 100644 index 0000000..c1868af --- /dev/null +++ b/connectors/tavily/icon.svg @@ -0,0 +1 @@ + diff --git a/connectors/tavily/mark.svg b/connectors/tavily/mark.svg new file mode 100644 index 0000000..a9f6e23 --- /dev/null +++ b/connectors/tavily/mark.svg @@ -0,0 +1 @@ +