TokenRail API documentation

Quick start

Create an account, purchase credits, generate an API key, then send your first request.

curl https://api.tokenrail.cloud/v1/chat/completions \
  -H "Authorization: Bearer $TOKENRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sample/chat-standard",
    "messages": [{"role": "user", "content": "Summarise this ticket."}]
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://api.tokenrail.cloud/v1",
    api_key=os.environ["TOKENRAIL_API_KEY"],
)

resp = client.chat.completions.create(
    model="sample/chat-standard",
    messages=[{"role": "user", "content": "Hello"}],
)

{
  "id": "chatcmpl_sample_123",
  "object": "chat.completion",
  "model": "sample/chat-standard",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "..." }, "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 412, "completion_tokens": 96, "total_tokens": 508 },
  "tokenrail": { "routed_model": "sample/chat-standard", "fallback_used": false, "charged_eur": 0.000378 }
}

Authentication

Authenticate every request with a Bearer token in the Authorization header. Requests without a valid key return 401. Never expose keys in client-side code.

API keys

Create multiple keys per project, for example one per environment or customer. Each key can be scoped to specific endpoints and model categories, given its own spending limit, and rotated or revoked at any time. Usage is reported per key.

Endpoints

• POST/v1/chat/completionsOpenAI-compatible chat completions
• POST/v1/responsesResponses-style generation
• POST/v1/embeddingsVector embeddings
• GET/v1/modelsList models available to your key
• GET/v1/usageUsage by period, endpoint, model and key
• GET/v1/creditsCurrent prepaid credit balance

Credits and billing

Usage is deducted from your prepaid credit balance as requests complete. Each charge equals the model's catalog rate for recorded input and output tokens plus a 5% routing fee. Failed requests are not charged. When the balance reaches zero, requests return 402 insufficient_credits.

GET https://api.tokenrail.cloud/v1/credits

{ "balance_eur": 412.57, "low_balance_threshold_eur": 50.00, "currency": "EUR" }

Rate limits

Limits apply per API key, as requests per minute and tokens per minute. Current limits are returned in x-ratelimit-* response headers. Exceeding a limit returns 429 with a retry-after header. Contact support to discuss higher limits.

Errors and retries

Errors follow the OpenAI error format. Retry 429 and 5xx responses with exponential backoff and jitter; do not retry 400, 401, 402 or 403.

{
  "error": {
    "type": "insufficient_credits",
    "message": "Credit balance is too low to process this request.",
    "status": 402
  }
}

Routing and fallback policies

Pass an optional tokenrail object to choose a routing policy and an ordered list of compatible fallbacks. The model that actually served the request is returned in the response and recorded in usage.

{
  "model": "sample/chat-standard",
  "messages": [...],
  "tokenrail": {
    "policy": "lowest-cost",          // lowest-cost | lowest-latency | priority
    "fallbacks": ["sample/chat-fast", "sample/chat-large"],
    "max_cost_eur": 0.01
  }
}

Usage exports

Query usage grouped by period, endpoint, model or API key, or export CSV from the dashboard. Values match the consumption statement attached to your invoice.

GET https://api.tokenrail.cloud/v1/usage?from=2026-09-01&to=2026-09-30&group_by=endpoint,model

{
  "period": { "from": "2026-09-01", "to": "2026-09-30" },
  "data": [
    { "endpoint": "/v1/chat/completions", "model": "sample/chat-standard",
      "requests": 42180, "input_tokens": 31250000, "output_tokens": 9840000, "amount_eur": 30.39 }
  ]
}

Low-balance notifications

Set a balance threshold in the dashboard. When your balance crosses it, TokenRail sends an email and, if configured, a signed webhook to your endpoint. Verify the signature before acting on the event.

POST https://your-app.example/webhooks/tokenrail
X-TokenRail-Signature: t=1790000000,v1=...

{
  "type": "credits.low_balance",
  "data": { "balance_eur": 48.12, "threshold_eur": 50.00 }
}