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
curl -X POST https://api.toolboxlite.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Response:

JSON
{
  "success": true,
  "data": {
    "apiKey": "atb_a1b2c3d4e5f6...",
    "plan": "free",
    "limits": { "monthly": 1000 }
  }
}

2. Make your first call

curl
Python
JavaScript
bash
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"}'
Python
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())
JavaScript
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.

💡 Pro tip: Try endpoints instantly in the API Playground — no setup needed.

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:

JSON
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Query is required"
  },
  "meta": {
    "requestId": "abc-123",
    "endpoint": "/v1/search"
  }
}

Error Codes

CodeHTTPDescription
UNAUTHORIZED401Missing or invalid API key
VALIDATION_ERROR400Invalid request parameters
RATE_LIMITED429Rate limit exceeded
QUOTA_EXCEEDED429Monthly quota exhausted
QUEUE_FULL408Too many concurrent requests
TIMEOUT504Request timed out (30s limit)
INTERNAL_ERROR500Unexpected server error

Rate Limits

PlanRequests/minRequests/monthConcurrent Playwright
Free601,0003
Builder60Unlimited3
Pro12050,0003
Scale300500,0003

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

FieldTypeRequiredDescription
querystringYesSearch query
countintegerNoResults (1-10, default 5)
langstringNoLanguage code (default "en")
curl
Python
JavaScript
bash
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}'
Python
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']}")
JavaScript
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

JSON
{
  "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

POST
/v1/extract

Extract readable content from any web page. Powered by Playwright + Readability.

FieldTypeRequiredDescription
urlstringYesURL to extract from
formatstringNo"markdown" (default), "text", or "json"
curl
Python
JavaScript
bash
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"}'
Python
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"])
JavaScript
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

POST
/v1/screenshot

Capture a screenshot of any web page. Returns base64 PNG.

FieldTypeRequiredDescription
urlstringYesURL to capture
widthintegerNoViewport width (default 1280, max 1920)
heightintegerNoViewport height (default 720, max 1080)
fullPagebooleanNoFull page screenshot (default false)
curl
Python
JavaScript
bash
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}'
Python
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))
JavaScript
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

POST
/v1/weather

Current weather and forecast from Open-Meteo. Free, no API key needed on our side.

FieldTypeRequiredDescription
locationstringYesCity name or location
curl
Python
JavaScript
bash
curl -X POST https://api.toolboxlite.com/v1/weather \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"location": "San Francisco"}'
Python
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']}")
JavaScript
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

POST
/v1/finance

Stock quotes and currency exchange rates via Yahoo Finance.

FieldTypeRequiredDescription
symbolstringFor quotesStock ticker (e.g. "AAPL")
typestringNo"quote" (default) or "exchange"
fromstringFor exchangeSource currency (e.g. "USD")
tostringFor exchangeTarget currency (e.g. "EUR")
amountnumberNoAmount to convert (default 1)
curl (stock)
curl (exchange)
Python
bash
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"}'
bash
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}'
Python
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

POST
/v1/validate-email

Validate email: syntax, MX records, SMTP handshake, disposable domain detection. Zero cost.

FieldTypeRequiredDescription
emailstringYesEmail address to validate
curl
Python
JavaScript
bash
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]"}'
Python
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']}")
JavaScript
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

POST
/v1/translate

Translate text between 100+ languages. Auto-detection, Markdown preservation, glossary support, batch mode.

FieldTypeRequiredDescription
textstringYes*Text to translate (single mode)
textsstring[]Yes*Array of texts (batch mode, max 20)
targetstringYesTarget language (ISO 639-1: zh, ja, es, fr...)
sourcestringNoSource language (default "auto")
glossaryobjectNoTerm mapping, e.g. {"API": "API"}

* Provide either text or texts, not both.

curl
Python (glossary)
JavaScript (batch)
bash
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"}'
Python
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 数据。
JavaScript
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

POST
/v1/news

Search and aggregate news articles from Google News. Filter by language, country, and category.

FieldTypeRequiredDescription
querystringYesNews search query
languagestringNoLanguage code (default "en")
countrystringNoCountry code (default "us")
categorystringNobusiness, technology, science, health, sports, entertainment, general
limitintegerNoResults count (1-50, default 10)
curl
Python
JavaScript
bash
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}'
Python
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']}")
JavaScript
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

bash
npm install -g agent-toolbox-mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

JSON
{
  "mcpServers": {
    "agent-toolbox": {
      "command": "agent-toolbox-mcp",
      "env": {}
    }
  }
}

Cursor

Add to .cursor/mcp.json:

JSON
{
  "mcpServers": {
    "agent-toolbox": {
      "command": "agent-toolbox-mcp"
    }
  }
}

Available MCP Tools

ToolDescription
searchWeb search
extractPage content extraction
screenshotPage screenshot
weatherWeather & forecast
financeStocks & exchange
validate_emailEmail validation
translateText translation
newsNews article search

LangChain Integration

bash
pip install langchain-agent-toolbox
Python
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

bash
pip install llamaindex-agent-toolbox
Python
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:

EndpointCache TTL
search, extract5 minutes
weather, finance15 minutes
screenshot, validate-email, translate1 hour

Check the X-Cache response header: HIT (cached) or MISS (fresh).

To bypass cache, send Cache-Control: no-cache header.

Pricing

PlanPriceRequests/moRate Limit
Free$01,00060/min
Builder$0.005/callUnlimited60/min
Pro$29/mo50,000120/min
Scale$99/mo500,000300/min
All plans include all 7 endpoints. No feature gating. The only difference is volume.