ToolRouter REST API Reference: Auth, Tools, Billing, and Providers

Base URL: https://api.toolrouter.com

All requests and responses use JSON. Authenticated endpoints require a Bearer token in the Authorization header.

How does authentication work?

All authenticated endpoints require a Bearer token: Authorization: Bearer YOUR_API_KEY. Keys are created via the dashboard or CLI. The same key works for REST, MCP, and CLI.

Authorization: Bearer YOUR_API_KEY

API keys are created via the dashboard or CLI (toolrouter keys create). The same key works for REST, MCP, and CLI.

How do I discover tools?

GET /v1/tools

List all available tools.

bash

curl https://api.toolrouter.com/v1/tools

json

{
  "tools": [
    {
      "name": "seo",
      "displayName": "SEO Analyzer",
      "description": "On-page SEO analysis...",
      "version": "1.0.0",
      "categories": ["marketing"],
      "skills": [{ "name": "analyze_page", "displayName": "Analyze Page", ... }]
    }
  ]
}

GET /v1/tools/search?q={query}

Search tools by keyword.

bash

curl "https://api.toolrouter.com/v1/tools/search?q=screenshot"

GET /v1/tools/:tool

Get detailed information about a specific tool including all skills, input/output schemas, examples, and pricing.

bash

curl https://api.toolrouter.com/v1/tools/seo

json

{
  "name": "seo",
  "displayName": "SEO Analyzer",
  "description": "On-page SEO analysis, meta tag auditing, and content optimization",
  "version": "1.0.0",
  "categories": ["marketing"],
  "skills": [
    {
      "name": "analyze_page",
      "displayName": "Analyze Page",
      "description": "Full SEO audit of a URL",
      "input": { "type": "object", "properties": { "url": { "type": "string" } }, "required": ["url"] },
      "examples": [{ "description": "Analyze a page", "input": { "url": "https://example.com" } }],
      "returns": "SEO audit with scores, issues, and recommendations"
    }
  ]
}

How do I get an API key?

POST /v1/auth/provision

Create a free API key instantly. No signup needed. Rate-limited per IP.

bash

curl -X POST https://api.toolrouter.com/v1/auth/provision

json

{
  "api_key": "tr_live_fb8c6a1a78551d0f...",
  "key_prefix": "tr_live_fb8c...7a83",
  "claim_url": "https://toolrouter.com/claim?token=53a3d78f...",
  "account_id": "prov_15b7271a...",
  "message": "Your API key is ready. Free tools work immediately. To unlock premium tools and billing, have your user visit the claim URL."
}

The returned api_key works immediately for free tools. To link the key to a full account and add credits, the user should visit claim_url.

How do I execute tools?

POST /v1/tools/call

Execute a tool skill.

bash

curl -X POST https://api.toolrouter.com/v1/tools/call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "seo",
    "skill": "analyze_page",
    "input": { "url": "https://example.com" }
  }'

Response:

json

{
  "id": "call_abc123",
  "status": "success",
  "output": { "title": "Example Domain", "score": 72, ... },
  "usage": {
    "cost": 0.0105,
    "currency": "USD",
    "credits_remaining": 9.99,
    "raw_cost": 0.01,
    "markup": 1.05
  },
  "meta": {
    "tool": "seo",
    "skill": "analyze_page",
    
    "latency_ms": 1234
  }
}

BYOK headers — pass your own provider keys to get reduced 5% billing:

bash

curl -X POST https://api.toolrouter.com/v1/tools/call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Provider-Key-Serper: sp_xxx" \
  -d '{ "tool": "seo", "skill": "analyze_page", "input": { "url": "https://example.com" } }'

POST /v1/tools/call (dry run)

Validate a call without executing. No credits consumed.

bash

curl -X POST https://api.toolrouter.com/v1/tools/call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "tool": "seo",
    "skill": "analyze_page",
    "input": { "url": "https://example.com" },
    "dry_run": true
  }'

Response:

json

{
  "valid": true,
  "input_valid": true,
  "input_errors": [],
  "credentials_ok": true,
  "missing_credentials": [],
  "billing": { "balance_usd": 9.99, "sufficient": true },
  "rate_limit": { "remaining": 58, "limit": 60 }
}

POST /v1/tools/call (streaming)

Stream results via Server-Sent Events.

bash

curl -N -X POST https://api.toolrouter.com/v1/tools/call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  -d '{ "tool": "seo", "skill": "check_meta", "input": { "url": "https://example.com" } }'

Events: started → progress (handler logs) → rate_limit → result (or error).

POST /v1/tools/batch

Run up to 10 tool calls concurrently.

bash

curl -X POST https://api.toolrouter.com/v1/tools/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "calls": [
      { "tool": "dns-domain", "skill": "lookup_dns", "input": { "domain": "a.com" } },
      { "tool": "dns-domain", "skill": "check_ssl", "input": { "domain": "b.com" } }
    ]
  }'

Response: { "results": [...] } — same shape as individual calls, in order.

How do I manage billing?

GET /v1/billing/balance

Get current credit balance.

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.toolrouter.com/v1/billing/balance

json

{ "available_usd": 9.99 }

POST /v1/billing/checkout

Create a Stripe checkout session to purchase credits.

bash

curl -X POST https://api.toolrouter.com/v1/billing/checkout \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "amount_usd": 10 }'

json

{
  "url": "https://checkout.stripe.com/c/pay/...",
  "credit_usd": 10.00,
  "fee_usd": 0.80,
  "total_usd": 10.80
}

POST /v1/billing/portal

Get a Stripe billing portal link for managing payment methods and viewing invoices.

bash

curl -X POST https://api.toolrouter.com/v1/billing/portal \
  -H "Authorization: Bearer YOUR_API_KEY"

json

{ "url": "https://billing.stripe.com/p/session/..." }

GET /v1/billing/preferences

Get auto-reload and budget limit settings.

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.toolrouter.com/v1/billing/preferences

json

{
  "autoReloadEnabled": true,
  "autoReloadThreshold": 5,
  "autoReloadAmount": 20,
  "budgetLimit": 100
}

PUT /v1/billing/preferences

Update auto-reload and budget limit settings. Only include fields you want to change.

bash

curl -X PUT https://api.toolrouter.com/v1/billing/preferences \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "autoReloadEnabled": true,
    "autoReloadThreshold": 5,
    "autoReloadAmount": 20,
    "budgetLimit": 100
  }'

autoReloadEnabled — enable/disable auto-reload (boolean)
autoReloadThreshold — balance (USD) that triggers a reload
autoReloadAmount — amount (USD) to add per reload ($1–$500)
budgetLimit — monthly spending cap in USD, or null to remove

How do I manage API keys?

POST /v1/keys

Create a new API key.

bash

curl -X POST https://api.toolrouter.com/v1/keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "name": "My App", "credits": 10 }'

POST /v1/keys/:id/credits

Add credits to a key.

bash

curl -X POST https://api.toolrouter.com/v1/keys/key_abc/credits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "amount": 5 }'

How do I manage async jobs?

Long-running tool calls (30+ seconds) return a 202 with a job_id instead of an inline result. Poll for completion.

GET /v1/jobs/:jobId

Get the status and result of an async job.

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.toolrouter.com/v1/jobs/job_abc123

json

{
  "job_id": "job_abc123",
  "status": "completed",
  "tool": "deep-research",
  "skill": "research",
  "output": { "summary": "..." },
  "elapsed_seconds": 45
}

Status values: pending, running, completed, failed, cancelled.

POST /v1/jobs/:jobId/cancel

Cancel a running async job.

bash

curl -X POST https://api.toolrouter.com/v1/jobs/job_abc123/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

json

{ "cancelled": true, "job_id": "job_abc123" }

How do I manage credentials (BYOK)?

Save your own provider API keys to override platform defaults. All tools work without this — BYOK is optional.

GET /v1/account/requirements

List all saved provider keys.

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.toolrouter.com/v1/account/requirements

PUT /v1/account/requirements/:name

Save or update a provider key.

bash

curl -X PUT https://api.toolrouter.com/v1/account/requirements/openai \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "value": "sk-xxx", "label": "My OpenAI Key" }'

DELETE /v1/account/requirements/:name

Remove a saved provider key.

bash

curl -X DELETE https://api.toolrouter.com/v1/account/requirements/openai \
  -H "Authorization: Bearer YOUR_API_KEY"

How do I submit reviews?

POST /v1/reviews

Rate a tool 1-5 stars with optional feedback. Free, no credits charged. One review per tool (re-submitting updates it).

bash

curl -X POST https://api.toolrouter.com/v1/reviews \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "tool": "web-search", "rating": 4, "review": "Fast and reliable" }'

Assets

GET /v1/assets/:assetId

Download a file produced by a tool call (screenshots, exports).

Default limits per API key are 60 requests per minute, 1,000 per hour, and 5 concurrent. Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included on every response.

Default limits per API key:

Window	Limit
Per minute	60 requests
Per hour	1,000 requests
Concurrent	5 requests

Response headers on every request:

X-RateLimit-Limit — requests allowed in the current window
X-RateLimit-Remaining — requests remaining
X-RateLimit-Reset — seconds until the window resets

What do error responses look like?

All errors return a consistent JSON shape with code, type, message, and resolution_hint. Agents can branch on stable error types like auth, billing, rate_limit, validation, provider, and not_found.

All errors follow a consistent shape:

json

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "type": "billing",
    "message": "Not enough credits for this call",
    "resolution_hint": "Add credits at toolrouter.com/billing or via toolrouter keys add-credits"
  }
}

HTTP	Type	Codes	When
404	`not_found`	TOOL_NOT_FOUND, SKILL_NOT_FOUND	Bad tool/skill reference
400	`validation`	INVALID_INPUT	Missing or malformed params
401	`auth`	AUTH_REQUIRED, AUTH_FAILED	Missing or invalid API key
401	`auth`	MISSING_CREDENTIALS	Tool credential not configured
402	`billing`	INSUFFICIENT_CREDITS	Out of credits
429	`rate_limit`	RATE_LIMIT_EXCEEDED	Too many requests
429	`rate_limit`	SPENDING_LIMIT_EXCEEDED	Period limit exceeded
502	`provider`	HANDLER_ERROR	Handler error

All errors include resolution_hint — agents can read this to self-recover.