Docs › API reference

API reference

Base URL https://api.tokenctr.com/v1. OpenAI-compatible, so existing SDKs work by changing the base URL and key.

Basics

Endpoints

Chat completions

OpenAI-compatible chat. Send the same body you would send to OpenAI or OpenRouter; the response comes back in the standard chat-completion shape.

curl https://api.tokenctr.com/v1/chat/completions \
  -H "Authorization: Bearer $TOKENCENTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistralai/ministral-3b-2512",
    "messages": [{"role": "user", "content": "Say hello in five words."}],
    "max_tokens": 100
  }'

# pip install openai
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.tokenctr.com/v1",
    api_key=os.environ["TOKENCENTER_API_KEY"],
)

resp = client.chat.completions.create(
    model="mistralai/ministral-3b-2512",
    messages=[{"role": "user", "content": "Say hello in five words."}],
    max_tokens=100,
)
print(resp.choices[0].message.content)
print(resp.usage)

// npm install openai   (Node 18+, ES modules)
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.tokenctr.com/v1",
  apiKey: process.env.TOKENCENTER_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "mistralai/ministral-3b-2512",
  messages: [{ role: "user", content: "Say hello in five words." }],
  max_tokens: 100,
});
console.log(resp.choices[0].message.content);
console.log(resp.usage);

// No SDK: plain fetch (Node 18+ or any server runtime)
const res = await fetch("https://api.tokenctr.com/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.TOKENCENTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "mistralai/ministral-3b-2512",
    messages: [{ role: "user", content: "Say hello in five words." }],
    max_tokens: 100,
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error?.code}: ${data.error?.message}`);
console.log(data.choices[0].message.content);
console.log("Balance after call:", res.headers.get("x-cosmos-credit-balance"));

Request body

Response

The body is the provider’s chat-completion object. Read the reply from choices[0].message.content, or choices[0].message.tool_calls when the model calls a tool. This example is illustrative; IDs, text and numbers will differ.

{
  "id": "gen-…",
  "object": "chat.completion",
  "created": 1792310400,
  "model": "mistralai/ministral-3b-2512",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello there, nice to meet!" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 9,
    "total_tokens": 23,
    "cost": 0.0000023
  }
}

usage.prompt_tokens and usage.completion_tokens are what you’re billed for. usage.cost, when present, is the provider’s own measured cost; if it’s higher than the token math, that’s what is charged. See how a call is priced.

Response headers

With the Python SDK, read headers through with_raw_response:

raw = client.chat.completions.with_raw_response.create(
    model="mistralai/ministral-3b-2512",
    messages=[{"role": "user", "content": "Hi"}],
    max_tokens=50,
)
print(raw.headers.get("x-cosmos-credit-balance"))
resp = raw.parse()   # the normal ChatCompletion object

Models

Lists every model your key can call, with its current prices. Prices are US dollars per million tokens. For one model, put its full ID in the path, for example /v1/models/mistralai/ministral-3b-2512.

curl https://api.tokenctr.com/v1/models \
  -H "Authorization: Bearer $TOKENCENTER_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "mistralai/ministral-3b-2512",
      "object": "model",
      "prompt_per_m_usd": 0.1,
      "completion_per_m_usd": 0.1,
      "stocked": true,
      "owned_by": "cosmos",
      "price_per_m_usd": null,
      "cogs_per_m_usd": null
    }
  ]
}

An unknown ID on /v1/models/{id} or in a chat request returns 404 model_not_found.

Usage today

Your balance and today’s usage (UTC day), grouped by model.

{
  "day": "2026-10-18",
  "credits_face_usd": 4.9999977,
  "free_used_face_usd": 0.0,
  "free_quota_face_usd": 0.0,
  "rollup": [
    { "lane": "A", "model": "mistralai/ministral-3b-2512",
      "runs": 1, "tokens_in": 14, "tokens_out": 9, "measured_usd": 0.0000023 }
  ]
}

Account

Returns account (an anonymised ID), plan (free, verified_free or founding), credits_face_usd (balance), and keys: one entry per key with a short key_hash fingerprint, label, created_at, revoked and daily_cap_usd. Full keys are never returned. The response also includes settings and promises fields, which you can ignore.

Usage log

Your most recent events, newest first. Optional query parameters: limit (default 100), model (exact model ID). Logs never contain prompt or reply text.

curl "https://api.tokenctr.com/v1/logs?limit=20&model=mistralai/ministral-3b-2512" \
  -H "Authorization: Bearer $TOKENCENTER_API_KEY"

Response: {"object": "list", "data": [ …events ]}. Each event has these fields:

Statements

Add ?period=YYYY-MM (default: the current UTC month). /v1/statement returns credit_events, the purchases and credit grants for that month. /v1/statement/export downloads every event for the month as CSV with the columns at, event, lane, model, measured_usd, event_id.

curl -o statement.csv "https://api.tokenctr.com/v1/statement/export?period=2026-10" \
  -H "Authorization: Bearer $TOKENCENTER_API_KEY"

Data export

/v1/export returns all your events as {"object": "export", "events": [ … ]}. /v1/export/full adds your plan, balance, key list and settings.

Checkout

Starts a Stripe checkout for a credit pack. Send pack_id: mini ($5), maker ($19) or studio ($59). Prices are set by the server; if you also send amount_usd, it must match the pack price exactly or you get 400 amount_mismatch. Optional success_url and cancel_url must be pages on tokenctr.com.

curl -X POST https://api.tokenctr.com/v1/credits/purchase \
  -H "Authorization: Bearer $TOKENCENTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pack_id": "maker"}'

Response: {"checkout": {"id": "cs_…", "url": "https://checkout.stripe.com/…"}, "pack_id": "maker", "amount_usd": 19.0}. Send the buyer to checkout.url. Credit is added to the account that owns the key once Stripe confirms the payment, not when the session is created.

Send tier: paid (Founding membership, $10, adds $20 credit) or verified (card verification, $1, adds $1 credit). An account that already holds the tier gets 409 already_founding. The response has the same checkout object.

Founding seats: {"sold": 0, "cap": 500, "remaining": 500}.

Health

Returns {"ok": true, …} while the API is up. Useful for uptime monitors.