Agent Toolbox Documentation
Everything you need to give your AI agents real-world superpowers. From first API call to production in under 2 minutes.
Quick Start
Get from zero to your first API call in 3 steps:
1. Get your API key (free)
curl -X POST https://api.toolboxlite.com/v1/auth/register \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]"}'Response:
{
"success": true,
"data": {
"apiKey": "atb_a1b2c3d4e5f6...",
"plan": "free",
"limits": { "monthly": 1000 }
}
}2. Make your first call
curl -X POST https://api.toolboxlite.com/v1/search \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "best AI frameworks 2025"}'import httpx
resp = httpx.post(
"https://api.toolboxlite.com/v1/search",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"query": "best AI frameworks 2025"}
)
print(resp.json())const resp = await fetch("https://api.toolboxlite.com/v1/search", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({ query: "best AI frameworks 2025" }),
});
const data = await resp.json();
console.log(data);3. You're done! 🎉
Free tier includes 1,000 requests/month. No credit card required.
Authentication
All data endpoints require a Bearer token in the Authorization header:
Authorization: Bearer atb_your_api_key_here
Public endpoints (no auth): /health, /v1/docs, /v1/auth/register, /playground, /docs
Errors & Rate Limits
Error Format
All errors return a consistent JSON structure:
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Query is required"
},
"meta": {
"requestId": "abc-123",
"endpoint": "/v1/search"
}
}Error Codes
| Code | HTTP | Description |
|---|---|---|
UNAUTHORIZED | 401 | Missing or invalid API key |
VALIDATION_ERROR | 400 | Invalid request parameters |
RATE_LIMITED | 429 | Rate limit exceeded |
QUOTA_EXCEEDED | 429 | Monthly quota exhausted |
QUEUE_FULL | 408 | Too many concurrent requests |
TIMEOUT | 504 | Request timed out (30s limit) |
INTERNAL_ERROR | 500 | Unexpected server error |
Rate Limits
| Plan | Requests/min | Requests/month | Concurrent Playwright |
|---|---|---|---|
| Free | 60 | 1,000 | 3 |
| Builder | 60 | Unlimited | 3 |
| Pro | 120 | 50,000 | 3 |
| Scale | 300 | 500,000 | 3 |
Rate limit headers are included in responses: X-RateLimit-Limit, X-RateLimit-Remaining.
POST /v1/search
Search the web via DuckDuckGo. Returns titles, URLs, and snippets.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Search query |
count | integer | No | Results (1-10, default 5) |
lang | string | No | Language code (default "en") |
curl -X POST https://api.toolboxlite.com/v1/search \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "OpenAI GPT-5", "count": 3}'import httpx
resp = httpx.post("https://api.toolboxlite.com/v1/search",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"query": "OpenAI GPT-5", "count": 3})
results = resp.json()["data"]
for r in results:
print(f"{r['title']} — {r['url']}")const resp = await fetch("https://api.toolboxlite.com/v1/search", {
method: "POST",
headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
body: JSON.stringify({ query: "OpenAI GPT-5", count: 3 })
});
const { data } = await resp.json();
data.forEach(r => console.log(r.title, r.url));Response
{
"success": true,
"data": [
{
"title": "OpenAI GPT-5 Release Details",
"url": "https://example.com/gpt5",
"snippet": "GPT-5 brings significant improvements..."
}
],
"meta": { "requestId": "abc", "latencyMs": 420, "endpoint": "/v1/search" }
}POST /v1/extract
Extract readable content from any web page. Powered by Playwright + Readability.
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | URL to extract from |
format | string | No | "markdown" (default), "text", or "json" |
curl -X POST https://api.toolboxlite.com/v1/extract \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com", "format": "markdown"}'resp = httpx.post("https://api.toolboxlite.com/v1/extract",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"url": "https://example.com", "format": "markdown"})
print(resp.json()["data"]["content"])const { data } = await fetch("https://api.toolboxlite.com/v1/extract", {
method: "POST",
headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
body: JSON.stringify({ url: "https://example.com" })
}).then(r => r.json());
console.log(data.content);POST /v1/screenshot
Capture a screenshot of any web page. Returns base64 PNG.
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | URL to capture |
width | integer | No | Viewport width (default 1280, max 1920) |
height | integer | No | Viewport height (default 720, max 1080) |
fullPage | boolean | No | Full page screenshot (default false) |
curl -X POST https://api.toolboxlite.com/v1/screenshot \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://news.ycombinator.com", "width": 1280, "height": 720}'import base64
resp = httpx.post("https://api.toolboxlite.com/v1/screenshot",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"url": "https://news.ycombinator.com"})
img_b64 = resp.json()["data"]["base64"]
with open("screenshot.png", "wb") as f:
f.write(base64.b64decode(img_b64))const { data } = await fetch("https://api.toolboxlite.com/v1/screenshot", {
method: "POST",
headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
body: JSON.stringify({ url: "https://news.ycombinator.com" })
}).then(r => r.json());
// data.base64 contains the PNG image
fs.writeFileSync("screenshot.png", Buffer.from(data.base64, "base64"));POST /v1/weather
Current weather and forecast from Open-Meteo. Free, no API key needed on our side.
| Field | Type | Required | Description |
|---|---|---|---|
location | string | Yes | City name or location |
curl -X POST https://api.toolboxlite.com/v1/weather \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"location": "San Francisco"}'resp = httpx.post("https://api.toolboxlite.com/v1/weather",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"location": "San Francisco"})
w = resp.json()["data"]["current"]
print(f"{w['temperature']}°C, {w['description']}")const { data } = await fetch("https://api.toolboxlite.com/v1/weather", {
method: "POST",
headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
body: JSON.stringify({ location: "San Francisco" })
}).then(r => r.json());
console.log(data.current.temperature + "°C");POST /v1/finance
Stock quotes and currency exchange rates via Yahoo Finance.
| Field | Type | Required | Description |
|---|---|---|---|
symbol | string | For quotes | Stock ticker (e.g. "AAPL") |
type | string | No | "quote" (default) or "exchange" |
from | string | For exchange | Source currency (e.g. "USD") |
to | string | For exchange | Target currency (e.g. "EUR") |
amount | number | No | Amount to convert (default 1) |
curl -X POST https://api.toolboxlite.com/v1/finance \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"symbol": "AAPL", "type": "quote"}'curl -X POST https://api.toolboxlite.com/v1/finance \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"from": "USD", "to": "EUR", "amount": 100}'resp = httpx.post("https://api.toolboxlite.com/v1/finance",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"symbol": "AAPL", "type": "quote"})
q = resp.json()["data"]
print(f"AAPL: {q['price']} ({q['changePercent']}%)")POST /v1/validate-email
Validate email: syntax, MX records, SMTP handshake, disposable domain detection. Zero cost.
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Email address to validate |
curl -X POST https://api.toolboxlite.com/v1/validate-email \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]"}'resp = httpx.post("https://api.toolboxlite.com/v1/validate-email",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"email": "[email protected]"})
v = resp.json()["data"]
print(f"Verdict: {v['verdict']}, Score: {v['score']}, Disposable: {v['is_disposable']}")const { data } = await fetch("https://api.toolboxlite.com/v1/validate-email", {
method: "POST",
headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
body: JSON.stringify({ email: "[email protected]" })
}).then(r => r.json());
console.log(data.verdict, data.score);Verdicts: deliverable | risky | undeliverable | invalid
POST /v1/translate
Translate text between 100+ languages. Auto-detection, Markdown preservation, glossary support, batch mode.
| Field | Type | Required | Description |
|---|---|---|---|
text | string | Yes* | Text to translate (single mode) |
texts | string[] | Yes* | Array of texts (batch mode, max 20) |
target | string | Yes | Target language (ISO 639-1: zh, ja, es, fr...) |
source | string | No | Source language (default "auto") |
glossary | object | No | Term mapping, e.g. {"API": "API"} |
* Provide either text or texts, not both.
curl -X POST https://api.toolboxlite.com/v1/translate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Hello, how are you?", "target": "zh"}'resp = httpx.post("https://api.toolboxlite.com/v1/translate",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"text": "The API endpoint returns JSON data.",
"target": "zh",
"glossary": {"API": "API", "JSON": "JSON", "endpoint": "端点"}
})
print(resp.json()["data"]["translation"])
# API 端点 返回 JSON 数据。const { data } = await fetch("https://api.toolboxlite.com/v1/translate", {
method: "POST",
headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
body: JSON.stringify({ texts: ["Hello", "Goodbye"], target: "ja" })
}).then(r => r.json());
data.translations.forEach(t => console.log(t.translation));
// こんにちは
// さようならPOST /v1/news
Search and aggregate news articles from Google News. Filter by language, country, and category.
| Field | Type | Required | Description |
|---|---|---|---|
query | string | Yes | News search query |
language | string | No | Language code (default "en") |
country | string | No | Country code (default "us") |
category | string | No | business, technology, science, health, sports, entertainment, general |
limit | integer | No | Results count (1-50, default 10) |
curl -X POST https://api.toolboxlite.com/v1/news \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "artificial intelligence", "category": "technology", "limit": 5}'resp = httpx.post("https://api.toolboxlite.com/v1/news",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"query": "artificial intelligence", "category": "technology", "limit": 5})
for article in resp.json()["data"]["results"]:
print(f"{article['source']}: {article['title']}")const { data } = await fetch("https://api.toolboxlite.com/v1/news", {
method: "POST",
headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
body: JSON.stringify({ query: "artificial intelligence", category: "technology", limit: 5 })
}).then(r => r.json());
data.results.forEach(a => console.log(a.source + ": " + a.title));MCP Server Integration
Use Agent Toolbox as an MCP server in Claude Desktop, Cursor, Windsurf, or any MCP client.
Install
npm install -g agent-toolbox-mcp
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"agent-toolbox": {
"command": "agent-toolbox-mcp",
"env": {}
}
}
}Cursor
Add to .cursor/mcp.json:
{
"mcpServers": {
"agent-toolbox": {
"command": "agent-toolbox-mcp"
}
}
}Available MCP Tools
| Tool | Description |
|---|---|
search | Web search |
extract | Page content extraction |
screenshot | Page screenshot |
weather | Weather & forecast |
finance | Stocks & exchange |
validate_email | Email validation |
translate | Text translation |
news | News article search |
LangChain Integration
pip install langchain-agent-toolbox
import os
os.environ["AGENT_TOOLBOX_API_KEY"] = "atb_your_key"
from langchain_agent_toolbox import (
AgentToolboxSearchTool,
AgentToolboxWeatherTool,
AgentToolboxTranslateTool,
)
# Use directly
search = AgentToolboxSearchTool()
result = search.invoke({"query": "LangChain agents", "count": 3})
print(result)
# Use with an agent
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_core.prompts import ChatPromptTemplate
tools = [AgentToolboxSearchTool(), AgentToolboxWeatherTool(), AgentToolboxTranslateTool()]
llm = ChatOpenAI(model="gpt-4o")
prompt = ChatPromptTemplate.from_messages([
("system", "You are a helpful assistant with web tools."),
("human", "{input}"),
("placeholder", "{agent_scratchpad}"),
])
agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools)
print(executor.invoke({"input": "Weather in Tokyo, translated to French"}))LlamaIndex Integration
pip install llamaindex-agent-toolbox
import os
os.environ["AGENT_TOOLBOX_API_KEY"] = "atb_your_key"
from llamaindex_agent_toolbox import AgentToolboxSearchTool, AgentToolboxWeatherTool
# Use directly
search = AgentToolboxSearchTool()
result = search.call(query="LlamaIndex agents", count=3)
print(result.content)
# Use with ReActAgent
from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI
tools = [AgentToolboxSearchTool(), AgentToolboxWeatherTool()]
agent = ReActAgent.from_tools(tools, llm=OpenAI(model="gpt-4o"), verbose=True)
response = agent.chat("What's the weather in Berlin?")
print(response)Caching
Responses are cached server-side for identical requests. Cache behavior:
| Endpoint | Cache TTL |
|---|---|
| search, extract | 5 minutes |
| weather, finance | 15 minutes |
| screenshot, validate-email, translate | 1 hour |
Check the X-Cache response header: HIT (cached) or MISS (fresh).
To bypass cache, send Cache-Control: no-cache header.
Pricing
| Plan | Price | Requests/mo | Rate Limit |
|---|---|---|---|
| Free | $0 | 1,000 | 60/min |
| Builder | $0.005/call | Unlimited | 60/min |
| Pro | $29/mo | 50,000 | 120/min |
| Scale | $99/mo | 500,000 | 300/min |