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.

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

Errors

OpenAI-style error envelope:

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