API reference

Every request carries a rail key (tsr_...), issued in the product under Router. Both header forms work, so Anthropic-style and OpenAI-style clients authenticate without changes.

x-api-key: tsr_...
# or
Authorization: Bearer tsr_...

Keys are stored hashed, shown once at creation, and revoke instantly (no cache in the auth path).

Base URL https://api.tokenspend.dev

• POST /v1/messages — Anthropic Messages format
• POST /v1/chat/completions — OpenAI Chat Completions format
• POST /v1/messages/count_tokens — Anthropic models, unmetered
• GET /v1/health

Either format may target any model: send Anthropic-shaped requests and run GLM, or send OpenAI-shaped requests and run Claude. Streaming, tool calls, system prompts and images translate in both directions.

Prices are provider list price. We never mark up tokens: BYOK requests bill on your own provider account, and managed credits draw down at exactly these rates.

Claude Code

export ANTHROPIC_BASE_URL=https://api.tokenspend.dev
export ANTHROPIC_API_KEY=tsr_...
# optional: run an open model instead of Claude
export ANTHROPIC_MODEL=zai/glm-5.2

Cline, Kilo, aider, any OpenAI SDK

export OPENAI_BASE_URL=https://api.tokenspend.dev/v1
export OPENAI_API_KEY=tsr_...

Python

from openai import OpenAI

client = OpenAI(base_url="https://api.tokenspend.dev/v1", api_key="tsr_...")
resp = client.chat.completions.create(
    model="zai/glm-5.2",
    messages=[{"role": "user", "content": "Explain this repo's build step."}],
)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.tokenspend.dev/v1", apiKey: process.env.TOKENSPEND_RAIL_KEY });
const resp = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-5",
  messages: [{ role: "user", content: "Explain this repo's build step." }]
});

curl

curl https://api.tokenspend.dev/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: tsr_..." \
  -d '{"model":"zai/glm-5.2","max_tokens":256,"messages":[{"role":"user","content":"hello"}]}'

Send images in either dialect; the rail translates. Models without image support refuse with a 400 naming the model rather than silently ignoring the image. The Images column above is authoritative.

{"model":"anthropic/claude-sonnet-5","max_tokens":300,"messages":[
  {"role":"user","content":[
    {"type":"text","text":"What is in this screenshot?"},
    {"type":"image","source":{"type":"base64","media_type":"image/png","data":"<base64>"}}
  ]}
]}

Our refusals use codes your tools do not retry; upstream problems keep the provider's own status and body so existing retry behavior is unchanged.

• 400 — invalid request, or an image sent to a model without image support
• 401 — rail key invalid or revoked
• 402 — monthly spend cap reached, or managed credits exhausted
• 403— model blocked by your admin's allowlist, or no provider key connected
• 404 — unknown model id
• 429 — rate limit (100 requests per minute per key)
• 503 — router disabled; point your base URL back at the provider to bypass

Errors arrive in the caller's dialect: Anthropic envelopes for Anthropic clients, OpenAI envelopes for OpenAI clients.

100 requests per minute per rail key. Routing on your own provider keys is free; there is no request charge and no token markup. Free-tier use should look like a team coding, not a benchmark farm: sustained automated load, resale of access, or traffic that endangers our provider standing may be rate limited or suspended. Talk to us before you plan anything heavy and we will size it with you.

Prompts, responses and image bytes pass through and are never written to disk or logs. What we keep per request is metadata: engineer, model, token counts, latency, status and list-price cost. That metadata is what turns spend into a yield report; the content is never part of it.