Documentation Index
Fetch the complete documentation index at: https://usenaive.ai/docs/llms.txt
Use this file to discover all available pages before exploring further.
Research is the primitive that gives your agent eyes on the live web. Naive exposes three tools at different levels of depth and cost — web_search, read_url, and research — so the agent picks the right one for the job: a quick fact lookup, a single-page extract, or a multi-step synthesis with citations. Use the lightest tool that meets your needs to keep latency and cost low.
CLI First
# Web search
naive search "AI agent frameworks comparison 2026"
# Read a specific URL
naive search url https://example.com --extract "Main takeaways"
# Deep research
naive search research "Compare top AI agent frameworks in 2026" --depth thorough --wait
| Tool | Type | Description | Speed | Cost |
|---|
web_search | Core | Search the web for current information — returns ranked results with snippets | Fast (~1s) | 1 credit |
read_url | Core | Fetch a URL and extract main text content with optional AI focus | Fast (~2s) | 1 credit |
research | Core | Multi-step deep research — search, fetch, and synthesize with citations | Slow (~10-90s) | 3-8 credits |
web_search
Real-time web search. Returns titles, URLs, and snippets — no page fetching.
curl -X POST https://api.usenaive.ai/v1/search \
-H "Authorization: Bearer nv_sk_your_key" \
-H "Content-Type: application/json" \
-d '{
"query": "AI agent frameworks comparison 2026",
"count": 5
}'
{
"results": [
{
"title": "The Best AI Agent Frameworks in 2026 - TechReview",
"url": "https://techreview.com/ai-agent-frameworks-2026",
"snippet": "We compared the top 10 AI agent frameworks across performance, ecosystem, and developer experience..."
},
{
"title": "LangChain vs CrewAI vs AutoGen: A Developer's Guide",
"url": "https://dev.to/comparison-langchain-crewai-autogen",
"snippet": "After building production agents with all three frameworks..."
}
],
"credits_used": 1
}
Parameters
| Param | Type | Required | Default | Description |
|---|
query | string | Yes | — | Search query |
count | number | No | 5 | Number of results (1-20) |
When to use
- Quick fact checks
- Finding URLs to read in detail
- Getting recent news or pricing
- Time-sensitive information your training data might not cover
read_url
Fetch a webpage and extract the main text content. Optionally uses AI to focus on a specific topic.
curl -X POST https://api.usenaive.ai/v1/search/url \
-H "Authorization: Bearer nv_sk_your_key" \
-H "Content-Type: application/json" \
-d '{
"url": "https://techreview.com/ai-agent-frameworks-2026",
"extract": "pricing and free tiers"
}'
{
"url": "https://techreview.com/ai-agent-frameworks-2026",
"content": "# AI Agent Frameworks Pricing\n\nLangChain: Open source, free...\nCrewAI: Free tier available, Pro at $49/mo...",
"credits_used": 1
}
Parameters
| Param | Type | Required | Default | Description |
|---|
url | string | Yes | — | URL to fetch and extract |
extract | string | No | — | Focus question — AI extracts relevant sections only |
When to use
- Reading a specific article after
web_search
- Extracting structured data from a known URL
- Getting documentation or pricing from a product page
Local and private URLs (localhost, 127., 10., 192.168.*) are blocked for security.
research
Multi-step deep research: searches the web, fetches top results, and synthesizes a comprehensive answer with inline citations. This is the heavyweight tool — use it when you need a thorough, multi-source answer.
curl -X POST https://api.usenaive.ai/v1/search/research \
-H "Authorization: Bearer nv_sk_your_key" \
-H "Content-Type: application/json" \
-d '{
"query": "What are the most effective go-to-market strategies for AI developer tools in 2026?",
"depth": "thorough"
}'
Depth Levels
| Depth | Behavior | Credits | Time |
|---|
quick | Inline response (search + synthesis) | 3 | ~5s |
thorough | Async job, more sources | 5 | ~45s |
exhaustive | Async job, max sources | 8 | ~90s |
thorough and exhaustive, you’ll get a 202 response with a job ID:
{
"job_id": "job-uuid",
"status": "processing",
"estimated_seconds": 45,
"hint": "Poll GET /v1/jobs/job-uuid for results."
}
{
"summary": "Based on analysis of current market trends...\n\n1. **Developer-first content marketing** — [1][2]\n2. **Open-source core with managed cloud** — [3]\n3. **Community-driven growth** — [4][5]",
"sources": [
{ "title": "GTM Playbook for Dev Tools", "url": "https://a16z.com/gtm-dev-tools" },
{ "title": "How Dev Tools Scale to $3B", "url": "https://techcrunch.com/dev-tools-growth" }
]
}
Use web_search → scan snippets for the answer.POST /v1/search { "query": "OpenAI API pricing 2026" }
Use web_search → read_url on the best result.POST /v1/search { "query": "Stripe API changelog" }
→ Found: https://docs.example.com/changelog
POST /v1/search/url { "url": "...", "extract": "May 2026 changes" }
Use research for end-to-end synthesis.POST /v1/search/research {
"query": "How are B2B SaaS companies using AI agents for support in 2026?",
"depth": "thorough"
}
Error Handling
| Error | Cause | Recovery |
|---|
insufficient_credits | Not enough credits | Check balance with GET /v1/status |
url_blocked | Target is a private/local address | Use a public URL |
fetch_failed | Could not reach the target URL | Try a different URL or use web_search |
provider_error | Search provider error | Retry after a few seconds |
Start with web_search. If snippets aren’t enough, follow up with read_url. Only use research when you need a synthesized multi-source answer — it’s significantly more expensive but produces better results for complex questions.
Typical Workflow
Agent receives task: "Research competitor pricing for our Q3 strategy"
│
├─ POST /v1/search → Find relevant sources
│ { query: "competitor SaaS pricing 2026" }
│ → 5 results with URLs
│
├─ POST /v1/search/url → Deep dive on best result
│ { url: "https://competitor.com/pricing",
│ extract: "pricing tiers and features" }
│ → Extracted pricing details
│
└─ POST /v1/search/research → Comprehensive analysis
{ query: "How does our pricing compare?",
depth: "thorough" }
→ Synthesized report with citations
