Documentation sections
Send the first routed request.
Create and activate a Tokaroo key, keep it in a server-side secret store, and call the OpenAI-compatible endpoint with auto.
curl https://api.tokaroo.com/v1/chat/completions \
-H "Authorization: Bearer $TOKAROO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"messages": [
{"role": "user", "content": "Explain this error in plain language"}
]
}'max, pro, auto, fast, and basic. Start with auto unless you have a specific cost, latency, or quality objective.Use one Tokaroo key from a trusted runtime.
OpenAI-compatible and native REST calls accept Authorization: Bearer tok_.... Anthropic clients may send the same key in x-api-key. Gemini clients may use x-goog-api-key.
Load the key from an environment variable or secret manager.
Pass the key using the harness's provider credential setting.
Call your own backend or use a short-lived scoped credential. Never ship a permanent key in a public bundle.
Request the outcome Tokaroo should optimize.
The hardest and highest-stakes work where capability is the first requirement. Uses the measured frontier band and selects efficiently inside that elite group.
Serious daily technical, business, production, and customer-facing work. Chooses economically inside a substantially stronger measured quality band.
The default for applications that want Tokaroo to make the whole routing decision. Balances quality, cost, speed, reliability, tools, context, and escalation risk.
Rapid answers, edits, extraction, and interactive back-and-forth. Keeps an acceptable task-specific quality bar, then prioritizes measured speed.
Everyday questions and routine tasks where you need an answer, not a project. Selects the cheapest route that is working and appropriate for lightweight work.
Tokaroo evaluates candidate quality by task family. Select the outcome to optimize rather than maintaining provider-specific model rules.
Quality is measured separately for reasoning, code, math, reading, writing, tools, multilingual, and spatial work.
Fresh task-specific evaluations establish which candidates produce dependable results.
Only candidates meeting internal quality, format, context, and tool checks remain eligible.
Tokaroo then weighs speed, price, reliability, context, tools, and availability inside that basket.
Math and quantitative reasoning
Sep 4, 2026 | Fresh Tokaroo evaluation evidence
Reading and synthesis
Aug 28, 2026 | Fresh Tokaroo evaluation evidence
Writing and editing
Aug 28, 2026 | Fresh Tokaroo evaluation evidence
Structured data and tool decisions
Aug 31, 2026 | Fresh Tokaroo evaluation evidence
Multilingual work
Aug 30, 2026 | Fresh Tokaroo evaluation evidence
Evaluation evidence is limited to successful Tokaroo tests in the latest 30-day window; imported zero-sample signals are excluded. The concrete serving model, serving provider, and private settlement cost remain internal.
/v1/models/v1/pricing/v1/catalogChange the base URL, key, and model.
Existing OpenAI clients can use Tokaroo at https://api.tokaroo.com/v1. Chat Completions supports standard messages, tools, structured output fields, and streaming where the selected route is compatible.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKAROO_API_KEY"],
base_url="https://api.tokaroo.com/v1",
)
response = client.chat.completions.create(
model="auto",
messages=[{"role": "user", "content": "Review this function"}],
)
print(response.choices[0].message.content)/v1/chat/completions/v1/modelsPreserve Responses-native tool loops.
Use the Responses surface for clients such as Codex that rely on its native input, output, tool, and streaming event shapes.
curl https://api.tokaroo.com/v1/responses \
-H "Authorization: Bearer $TOKAROO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "pro",
"input": "Plan a safe database migration"
}'/v1/responsesUse Messages without changing its tool protocol.
The Anthropic-compatible surface accepts Messages requests, system content, tools, tool choice, streaming, and token counting. Set the base URL to https://api.tokaroo.com.
curl https://api.tokaroo.com/v1/messages \
-H "x-api-key: $TOKAROO_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "auto",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Summarize the incident"}
]
}'/v1/messages/v1/messages/count_tokensUse native GenerateContent routes.
Gemini clients can call GenerateContent, streamGenerateContent, countTokens, and the model list with a Tokaroo model ID in the path.
curl "https://api.tokaroo.com/v1beta/models/auto:generateContent" \
-H "x-goog-api-key: $TOKAROO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{
"role": "user",
"parts": [{"text": "Draft a release note"}]
}]
}'/v1beta/models/{model}:generateContent/v1beta/models/{model}:streamGenerateContent/v1beta/models/{model}:countTokensKeep the native wire for tool-heavy clients.
Set stream: true for server-sent events on compatible text routes. Keep tool definitions and tool results in the protocol the client already uses; Tokaroo evaluates model compatibility before scoring a route.
curl -N https://api.tokaroo.com/v1/chat/completions \
-H "Authorization: Bearer $TOKAROO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "fast",
"stream": true,
"messages": [{"role": "user", "content": "Give me three names"}]
}'Log the Tokaroo request without exposing the internal route.
Successful responses provide customer-safe usage fields. Concrete model selection, serving provider, upstream prices, internal margin, and failed candidate diagnostics remain private.
| Header | Meaning |
|---|---|
x-tokaroo-trace-id | An opaque identifier for support and usage correlation. |
x-tokaroo-requested-model | The requested Tokaroo mode. |
x-tokaroo-cost | The customer charge in USD. |
x-tokaroo-input-tokens | Recorded input tokens. |
x-tokaroo-output-tokens | Recorded output tokens. |
x-tokaroo-latency-ms | End-to-end runtime latency. |
x-tokaroo-cache | Cache status when that wire supports it. |
Agent systems may also send x-tokaroo-harness-ref with a supported profile ID so Tokaroo can apply tested harness compatibility preferences.
Retry only failures that can recover.
400Fix the request shape, unsupported field, or incompatible model requirement before retrying.
401Provide a valid Tokaroo key in the expected authentication header.
402Add credits or resolve the account's spend access before retrying.
429Respect retry-after, use exponential backoff, and add jitter.
503No compatible route is currently available. Respect retry-after and retry from a queue where possible.
Import the public contract.
The public specification covers Tokaroo's five model IDs, four compatible text formats, multimodal endpoints, customer-safe usage, and prepaid balance. It intentionally excludes private route selection and upstream commercial data.
Route more than text through the same account.
Tokaroo exposes compatible endpoints for embeddings, images, speech, transcription, video, realtime audio, and avatar workflows. Raspy supplies speech, transcription, realtime audio, and avatar capabilities; images and video use the broader compatible model network.
/v1/embeddings/v1/images/generations/v1/audio/speech/v1/audio/transcriptions/v1/videos/v1/realtime/transcriptions/v1/realtime/speech/v1/realtime/avatar/v1/avatars/v1/avatar/rendersConfigure the harness. Keep execution where it belongs.
Tokaroo publishes profiles for Codex, Claude Code, Hermes, OpenClaw, Kimi Code, DeepSeek Harness, Qwen Code, Gemini CLI, Grok Build, Goose, and OpenCode. The harness owns tools, files, and execution; Tokaroo owns the model route.
Open the integration directory