# tavily

AI Web Search via SkillBoss API Hub Overview SkillBoss API Hub provides AI-ready web search optimized for Large Language Models and AI applications. Unlike traditional search APIs, it delivers structured results with optional answer generation, clean content extraction, and domain filtering capabilities — all through a single unified endpoint. Key capabilities: AI-generated answer summaries from search results Clean, structured results optimized for LLM processing Fast (basic) and comprehensive (advanced) search modes Domain filtering (include/exclude specific sources) News-focused search for current events Image search with relevant visual content Raw content extraction for deeper analysis Architecture graph TB A[User Query] --> B{Search Mode} B -->|basic| C[Fast Search
1-2s response] B -->|advanced| D[Comprehensive Search
5-10s response] C --> E[SkillBoss API Hub] D --> E E --> F{Topic Filter} F -->|general| G[Broad Web Search] F -->|news| H[News Sources
Last 7 days] G --> I[Domain Filtering] H --> I I --> J{Include Domains?} J -->|yes| K[Filter to Specific Domains] J -->|no| L{Exclude Domains?} K --> M[Search Results] L -->|yes| N[Remove Unwanted Domains] L -->|no| M N --> M M --> O{Response Options} O --> P[AI Answer
Summary] O --> Q[Structured Results
Title, URL, Content, Score] O --> R[Images
if requested] O --> S[Raw HTML Content
if requested] P --> T[Return to Agent] Q --> T R --> T S --> T style E fill:#4A90E2 style P fill:#7ED321 style Q fill:#7ED321 style R fill:#F5A623 style S fill:#F5A623 Quick Start Basic Search

# Simple query with AI answer

scripts/tavily_search.py "What is quantum computing?"

# Multiple results

scripts/tavily_search.py "Python best practices" --max-results 10 Advanced Search

# Comprehensive research mode

scripts/tavily_search.py "Climate change solutions" --depth advanced

# News-focused search

scripts/tavily_search.py "AI developments 2026" --topic news Domain Filtering

# Search only trusted domains

scripts/tavily_search.py "Python tutorials"
--include-domains python.org docs.python.org realpython.com

# Exclude low-quality sources

scripts/tavily_search.py "How to code"
--exclude-domains w3schools.com geeksforgeeks.org With Images

# Include relevant images

scripts/tavily_search.py "Eiffel Tower architecture" --images Search Modes Basic vs Advanced ModeSpeedCoverageUse Casebasic1-2sGoodQuick facts, simple queriesadvanced5-10sExcellentResearch, complex topics, comprehensive analysis Decision tree: Need a quick fact or definition? → Use basic Researching a complex topic? → Use advanced Need multiple perspectives? → Use advanced Time-sensitive query? → Use basic General vs News TopicTime RangeSourcesUse CasegeneralAll timeBroad webEvergreen content, tutorials, documentationnewsLast 7 daysNews sitesCurrent events, recent developments, breaking news Decision tree: Query contains "latest", "recent", "current", "today"? → Use news Looking for historical or evergreen content? → Use general Need up-to-date information? → Use news API Key Setup Environment Variable

export SKILLBOSS_API_KEY="your-skillboss-api-key"

Add to ~/.clawdbot/.env or your shell profile. Programmatic Usage import os api_key = os.environ["SKILLBOSS_API_KEY"] Common Use Cases

1. Research & Fact-Finding

# Comprehensive research with answer

scripts/tavily_search.py "Explain quantum entanglement" --depth advanced

# Multiple authoritative sources

scripts/tavily_search.py "Best practices for REST API design"
--max-results 10
--include-domains github.com microsoft.com google.com 2. Current Events

# Latest news

scripts/tavily_search.py "AI policy updates" --topic news

# Recent developments in a field

scripts/tavily_search.py "quantum computing breakthroughs"
--topic news
--depth advanced 3. Domain-Specific Research

# Academic sources only

scripts/tavily_search.py "machine learning algorithms"
--include-domains arxiv.org scholar.google.com ieee.org

# Technical documentation

scripts/tavily_search.py "React hooks guide"
--include-domains react.dev 4. Visual Research

# Gather visual references

scripts/tavily_search.py "modern web design trends"
--images
--max-results 10 5. Content Extraction

# Get raw HTML content for deeper analysis

scripts/tavily_search.py "Python async/await"
--raw-content
--max-results 5 Response Handling AI Answer The AI-generated answer provides a concise summary synthesized from search results: { "answer": "Quantum computing is a type of computing that uses quantum-mechanical phenomena..." } Use when: Need a quick summary Want synthesized information from multiple sources Looking for a direct answer to a question Skip when (--no-answer): Only need source URLs Want to form your own synthesis Structured Results Each result includes:

title: Page title
url: Source URL
content: Extracted text snippet
score: Relevance score (0-1)
raw_content: Full HTML (if --raw-content enabled)

Images When --images is enabled, returns URLs of relevant images found during search. Best Practices

1. Choose the Right Search Depth Start with basic for most queries (faster) Escalate to advanced only when: Initial results are insufficient Topic is complex or nuanced Need comprehensive coverage
2. Use Domain Filtering Strategically Include domains for: Academic research (.edu domains) Official documentation (official project sites) Trusted news sources Known authoritative sources Exclude domains for: Known low-quality content farms Irrelevant content types (Pinterest for non-visual queries) Sites with paywalls or access restrictions
3. Handle Errors Gracefully The script provides helpful error messages:

# Missing API key
Error: SkillBoss API key required
Setup: Set SKILLBOSS_API_KEY environment variable or pass --api-key

Integration Patterns Programmatic Usage import os, requests SKILLBOSS_API_KEY = os.environ["SKILLBOSS_API_KEY"] API_BASE = "https://api.heybossai.com/v1" def pilot(body: dict) -> dict: r = requests.post( f"{API_BASE}/pilot", headers={"Authorization": f"Bearer {SKILLBOSS_API_KEY}", "Content-Type": "application/json"}, json=body, timeout=60, ) return r.json() result = pilot({"type": "search", "inputs": {"query": "What is machine learning?"}, "prefer": "balanced"}) search_results = result["result"] if search_results.get("answer"): print(search_results["answer"]) for item in search_results.get("results", []): print(f"{item['title']}: {item['url']}") JSON Output for Parsing scripts/tavily_search.py "Python tutorials" --json > results.json Chaining with Other Tools

# Search and extract content

scripts/tavily_search.py "React documentation" --json |
jq -r '.results[].url' | \

xargs -I {} curl -s {}

Troubleshooting Script Won't Run

# Make executable

chmod +x scripts/tavily_search.py

# Check Python version (requires 3.6+)

python3 --version

# Install dependencies

pip install requests API Key Issues

# Verify environment variable is set

echo $SKILLBOSS_API_KEY

# Test with explicit key

scripts/tavily_search.py "test" --api-key "your-skillboss-api-key" Resources See api-reference.md for: Complete API parameter documentation Response format specifications Error handling details Advanced usage examples Dependencies Python 3.6+ requests package (install: pip install requests) Valid SkillBoss API key (SKILLBOSS_API_KEY)