Quickstart

Route Tools has two ways to route tools. Use tool selection to ask the router which tool to use: web search is always You.com, and everything else is chosen from the candidates your agent supplies, preferring the cheapest and local-first. Use routed execution when you want Route Tools to call a provider for you.

1. Get an API key

Sign up at route.tools/dashboard — new accounts include $2 of free credits. Create a key; it looks like rt_live_....

2. Select a tool (zero-cost default)

Send the task and the tools your agent can use. The response tells you which tool to run:

curl https://api.route.tools/v1/route \
  -H "Authorization: Bearer rt_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "browser",
    "query": "Read a public documentation page",
    "candidates": [{
      "id": "my-local-browser",
      "description": "Read pages in a local browser",
      "capabilities": ["browser"],
      "location": "local",
      "available": true,
      "cost_usd": 0
    }]
  }'

{
  "execution": "caller",
  "strategy": "capability",
  "tool": "my-local-browser",
  "query": "Read a public documentation page",
  "location": "local",
  "estimated_tool_cost_usd": 0
}

Selection never executes anything and never debits credits. The default max_cost_usd is 0, so paid candidates are excluded unless you opt in.

Search is pinned to You.com. Any request with tool: "search" returns the You.com free MCP route (https://api.you.com/mcp?profile=free) instead of choosing from candidates. You.com documents 100 queries per day on that profile; when the allowance runs out the router never silently switches to a paid provider. Your client receives You.com’s quota response when it executes the selected MCP tool, not during selection, and can retry after the reset. See the full contract for operator setup and execution responsibilities.

3. Suitability is handled automatically

No assessment setting is needed. Search is fixed to You.com, and a single eligible tool takes the capability-only fast path. When multiple tools survive availability, capability, and budget checks, the router assesses task suitability before choosing the cheapest. Local wins equal-price ties.

If assessment fails or no tool fits, you get an error—not an unchecked fallback. A single-tool match trusts your capability label rather than verifying suitability. See the routing contract for advanced overrides, data sharing, and operator setup. Internal assessment may incur costs for the service operator; it does not debit caller credits or execute a tool.

4. Make a routed execution call (legacy, may bill credits)

curl https://api.route.tools/v1/tools/search \
  -H "Authorization: Bearer rt_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "cloudflare durable objects pricing",
    "max_results": 5,
    "routing": { "sort": "price" }
  }'

{
  "id": "req_01...",
  "category": "search",
  "provider": "you",
  "result": {
    "results": [
      { "title": "...", "url": "https://...", "snippet": "..." }
    ]
  },
  "usage": { "price": 0.0012, "latency_ms": 642, "units": 1 },
  "routing": {
    "sort": "price",
    "attempted": [{ "provider": "you", "status": "ok", "latency_ms": 642 }]
  }
}

The routing.attempted array shows exactly which providers were tried, in order — if the first choice failed, you’ll see the failover chain.

5. Pick a legacy execution routing dimension

routing.sort	Behavior
price	Cheapest available provider first (default)
latency	Fastest provider by live p50, measured over the last 5 minutes
quality	Highest-quality provider for the category

Don’t want to pass routing on every call? Save per-category defaults once — including a manual priority provider order and per-provider off switches — in the dashboard’s Routing panel or via PUT /v1/routing. Details in Routing.

Tool categories

Category	Endpoint	What it does
Search	POST /v1/tools/search	Web search
Scrape	POST /v1/tools/scrape	URL → markdown/html/text
Parse	POST /v1/tools/parse	Documents (PDF, images) → markdown
Image	POST /v1/tools/image	Text → image
Video	POST /v1/tools/video	Text → short video clips
Speech	POST /v1/tools/speech	Text → spoken audio
Transcribe	POST /v1/tools/transcribe	Audio → text
Embed	POST /v1/tools/embed	Text → vectors
Code	POST /v1/tools/code	Sandboxed code execution

Discover live availability and pricing programmatically with GET /v1/tools.

Using an MCP client instead of raw HTTP? See MCP setup.