API reference

tokenroute exposes two surfaces:

OpenAI-compatible (/v1/*)

Drop-in replacement for api.openai.com/v1. Same request/response shapes, just point your SDK at https://api.tokenroute.io/v1 and use an sk-tr-* key. See Quickstart for SDK snippets.

Management API (/api/v1/*)

Account, key, balance, and top-up management. Two auth modes:

• Logto JWT (Bearer) — for user-facing endpoints (/api/v1/me, /api/v1/balance, /api/v1/topup, /api/v1/me/keys). Obtained via tokenroute login (OAuth device-flow).
• X-Internal-Secret — for the admin endpoints used by paradigx storefront / partner bridge. Not for end users.

The live OpenAPI schema is at https://api.tokenroute.io/openapi.json.

Tags (cost allocation)

Attach tags to any chat request to break spend down by project / team / environment, then view it in your dashboard Usage page (filter by tag, "by tag" breakdown, per-row tag chips). Two ways:

# 1. HTTP header — comma-separated
curl https://api.tokenroute.io/v1/chat/completions \
  -H "Authorization: Bearer sk-tr-..." \
  -H "x-tokenroute-tags: project:alpha,team:mktg" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'

// 2. In the request body metadata
{
  "model": "gpt-4o-mini",
  "messages": [{ "role": "user", "content": "hi" }],
  "metadata": { "tags": ["project:alpha", "team:mktg"] }
}

• Up to 20 tags per request, each ≤ 64 chars; duplicates dropped; whitespace trimmed.
• Recorded on both successful and failed calls.
• A request's cost counts toward each of its tags — so the sum across tags can exceed the total when requests are multi-tagged.
• Convention is key:value (e.g. project:alpha, env:prod) but any string works.

Discovery for agents

If you need to bootstrap OIDC without the CLI:

curl https://api.tokenroute.io/api/v1/auth/discovery

Returns {issuer, client_id, device_authorization_endpoint, token_endpoint, scopes, resource} — enough to run RFC 8628 device-flow yourself.

Rate limits

• Burst: 10 RPS / key
• Sustained: depends on tier (see tokenroute models for per-model pricing & limits)
• Hitting the limit returns HTTP 429 with a Retry-After header — back off and retry after that many seconds. An upstream-provider 429 is surfaced the same way.
• On Anthropic models, cached prompt prefixes don't count toward the input-token rate limit — see Prompt caching to raise your effective throughput.

Errors

OpenAI-style error envelope:

{
  "error": {
    "message": "...",
    "type": "authentication_error",
    "code": 401
  }
}