Tavily Port

Purpose

This is the reference integration for Harbor http_api Action Model authoring for Tavily.

Use it when:

• building Tavily actions in Harbor
• extending the Dock / Hub Tavily entry
• teaching Codex or OpenClaw how to map a retrieval API into Harbor Ports and Harbor Actions

Harbor Port worksheet

Product

• Product: Tavily API
• Publisher slug: tavily
• Publisher name: Tavily
• Category: AI
• Tags: tavily, search, retrieval, extract, crawl

Safe Harbor Port metadata

• Kind: http_api
• Label: Tavily API
• Description: Tavily API connection managed locally through Harbor.
• Base URL: https://api.tavily.com
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Bearer

Hidden local config

• authToken

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

Harbor action design notes

Tavily is a good Harbor fit because its search and extraction APIs are already explicit JSON endpoints designed for agent workflows.

Good Harbor Tavily actions:

• fixed POST routes like /search, /extract, and /crawl
• requestBodyMode: "json" for all starter actions
• resultMode: "json_summary" for all starter actions
• approval on deeper extraction and crawl behaviors when they can fan out across many pages

Avoid for now:

• unbounded wide crawls without operator review
• turning Tavily into a generic browsing proxy
• automatic high-credit retrieval patterns without policy

Starter Tavily actions

Approval-friendly actions

• search -> POST /search
• extract -> POST /extract
• crawl -> POST /crawl

Why these actions

These routes fit Harbor's Action Model well because they:

• stay under one fixed Tavily API origin
• use explicit JSON request bodies rather than arbitrary hidden configuration
• align directly with named agent-search capabilities
• can be reviewed as separate search, extraction, and crawl privileges
• keep hidden auth entirely local to Harbor Node

Suggested operator workflow

1. Import the Tavily Dock entry from Dock / Hub.
2. Configure the local Tavily API key in Harbor Node.
3. Validate search first with narrow queries.
4. Review credit, latency, and breadth implications before enabling extract or crawl broadly.
5. Keep all three starter actions on require_approval unless your Harbor Guard policy explicitly permits those retrieval patterns.

Suggested agent workflow

1. Inspect the existing Tavily Harbor Port.
2. Inspect live actions and drafts.
3. Keep queries, URLs, and crawl limits explicit and bounded.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored API key
• widen Tavily into a generic arbitrary HTTP proxy
• run broad crawling behavior without policy and approval

Current update strategy

For now, Tavily updates are manual:

• update the Dock / Hub integration document in apps/hub/catalog/integrations/tavily/tavily-api.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Official reference starting points

• Tavily API search: https://docs.tavily.com/documentation/api-reference/endpoint/search
• Tavily API extract: https://docs.tavily.com/documentation/api-reference/endpoint/extract
• Tavily API crawl: https://docs.tavily.com/documentation/api-reference/endpoint/crawl