Documentation

Build on one API.

CT Router exposes an OpenAI-compatible API. Any OpenAI SDK or tool works after you change the base URL and API key. An interactive OpenAPI reference is at /api/swagger.

Quickstart

  1. Create an account and add credits.
  2. Create an API key on the Keys page.
  3. Call any model by its ID, e.g. openai/gpt-5 or anthropic/claude-sonnet-5.5.
from openai import OpenAI

client = OpenAI(
    base_url="https://ctrouter.ai/api/v1",
    api_key="$API_KEY",
)

completion = client.chat.completions.create(
    model="openai/gpt-5-mini",
    messages=[{"role": "user", "content": "What is the meaning of life?"}],
    extra_headers={"HTTP-Referer": "https://your-app.com", "X-Title": "Your App"},  # optional
)
print(completion.choices[0].message.content)
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://ctrouter.ai/api/v1",
  apiKey: process.env.API_KEY,
});

const completion = await client.chat.completions.create({
  model: "openai/gpt-5-mini",
  messages: [{ role: "user", content: "What is the meaning of life?" }],
});
console.log(completion.choices[0].message.content);
curl https://ctrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-mini",
    "messages": [{"role": "user", "content": "What is the meaning of life?"}]
  }'

Authentication

Send your key as a bearer token:

Authorization: Bearer sk-lr-v1-…

Keys are shown once at creation and stored hashed. You can disable or delete a key at any time and set a per-key credit limit.

Base URL

https://ctrouter.ai/api/v1

Chat completions

POST/api/v1/chat/completions

Request and response bodies follow the OpenAI Chat Completions format. Provider-specific translation (Anthropic, Gemini, etc.) is handled for you.

FieldTypeDescription
modelstringRequired. Model ID from /models.
messagesarrayRequired. {role, content} objects. content may be a string or an array of text / image_url parts for vision models.
modelsstring[]Fallback models, tried in order if model fails. See fallbacks.
streambooleanStream tokens as server-sent events.
max_tokensintegerMaximum tokens to generate.
temperature, top_pnumberSampling controls.
stopstring | string[]Stop sequences.
tools, tool_choicearray, string | objectFunction calling, for models that support it.
response_formatobject{"type": "json_object"} or a JSON schema, where supported.
reasoning_effortstringlow | medium | high for reasoning models.
seed, user, …Other OpenAI parameters are passed through. Unsupported ones are dropped for that provider.

Response

{
  "id": "gen-3kN0…",
  "object": "chat.completion",
  "model": "openai/gpt-5-mini",
  "provider": "OpenAI",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "…"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 14, "completion_tokens": 120, "total_tokens": 134, "cost": 0.0002435}
}

usage.cost is the amount charged in USD. The id can be passed to /generation.

Streaming

Set "stream": true. Chunks are sent as data: {…} lines in OpenAI's chat.completion.chunk format and the stream ends with data: [DONE]. The last chunk before [DONE] has an empty choices array and the final usage with cost.

stream = client.chat.completions.create(
    model="anthropic/claude-haiku-5.5",
    messages=[{"role": "user", "content": "Write a haiku about routers"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

If you disconnect mid-stream you're billed for the tokens generated so far.

Model fallbacks

Pass a models array. If the primary model errors (provider outage, rate limit, context too long), the next one is tried. The response's model field tells you which one served the request.

{
  "model": "anthropic/claude-sonnet-5.5",
  "models": ["openai/gpt-5", "google/gemini-2.5-pro"],
  "messages": [{"role": "user", "content": "Hello"}]
}

With the OpenAI SDK, pass it as extra_body={"models": [...]}.

Tool calling

Use the standard OpenAI tools format. Tool calls come back in message.tool_calls for every provider.

{
  "model": "openai/gpt-5-mini",
  "messages": [{"role": "user", "content": "Weather in Paris?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
    }
  }]
}

Embeddings

POST/api/v1/embeddings

curl https://ctrouter.ai/api/v1/embeddings \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/text-embedding-3-small", "input": ["first text", "second text"]}'

List models

GET/api/v1/models   GET/api/v1/models/{id}

No authentication required. Filter with ?mode=chat or ?mode=embedding. Each entry includes context_length, pricing.prompt and pricing.completion (USD per token), modalities and supported_parameters.

{
  "object": "list",
  "data": [{
    "id": "openai/gpt-4o-mini",
    "object": "model",
    "name": "GPT-4o Mini",
    "context_length": 128000,
    "pricing": {"prompt": "0.00000015", "completion": "0.0000006"},
    "architecture": {"input_modalities": ["text", "image"], "output_modalities": ["text"]},
    "supported_parameters": ["max_tokens", "temperature", "tools", "…"]
  }]
}

API key info

GET/api/v1/key

Returns the calling key's label, usage and remaining limit.

{"data": {"label": "prod", "usage": 1.23, "limit": 50.0, "limit_remaining": 48.77, "disabled": false}}

Credits

GET/api/v1/credits

{"data": {"balance": 18.42, "total_usage": 6.58}}

Generation stats

GET/api/v1/generation?id=gen-…

Token counts, cost, latency and finish reason for a past request.

App attribution

Optional headers to label requests from your app in Activity:

HTTP-Referer: https://your-app.com
X-Title: Your App Name

Errors

Errors use the OpenAI shape:

{"error": {"message": "Insufficient credits…", "type": "insufficient_quota", "code": "insufficient_credits"}}
StatusMeaning
400Invalid request: bad JSON, unknown model, context too long.
401Missing or invalid API key.
402Out of credits, or the key reached its credit limit.
403Key disabled.
429Upstream rate limit. Retry with backoff or add fallbacks.
502 / 503 / 504Upstream provider error, unavailable, or timed out.

Rate limits

Placeholder: per-key request limits are not enforced yet. Upstream provider limits still apply.

Frameworks

LangChain

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="openai/gpt-5-mini", base_url="https://ctrouter.ai/api/v1", api_key="$API_KEY")

Vercel AI SDK

import { createOpenAI } from "@ai-sdk/openai";

const router = createOpenAI({ baseURL: "https://ctrouter.ai/api/v1", apiKey: process.env.API_KEY });
const model = router("anthropic/claude-sonnet-5.5");

Any OpenAI-compatible tool

Set the base URL to https://ctrouter.ai/api/v1 and the API key to your key.