Tokeen API reference

Private beta. Base URL: `https://api.usetokeen.com` (during the beta, also `https://www.usetokeen.com/api`). JSON in, JSON out, UTF-8.

Tokeen removes tokens from a prompt before you send it to your model. You make one HTTPS call, get the same prompt back shorter, and pass it to your provider as usual. Nothing else in your code changes, and you are billed only on the tokens removed.

Authentication

Send your key in the Authorization header:

Authorization: Bearer tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Create and revoke keys in the portal at https://www.usetokeen.com/app (sign-in by email link, for the addresses invited by your organization). Keys are meant for servers. Do not ship one in a browser or a mobile app; anyone who sees it can spend your credits. If a key leaks, revoke it in the portal and create a new one.

POST /v1/compress

Request body:

{ "text": "…the prompt, or the part of it to compress…", "rate": 0.8 }

Field	Type	Notes
`text`	string	Required. Up to 131,072 tokens and 2 MB by default (adjustable per organization).
`rate`	number	Optional, default `0.8`. Share of tokens to keep, from `0.30` to `0.95`. `0.8` removes about 20 %.

Response 200:

{
  "id": "req_01k2agb8pvp6wn7q3zwk0v84wc",
  "text": "…the same prompt with tokens removed…",
  "tokens_in": 8900,
  "tokens_out": 7115,
  "tokens_removed": 1785,
  "billed_tokens": 1785
}

Response headers: X-Request-Id (quote it when you write to us), X-Tokeen-Engine (engine version), X-Tokeen-Credits-Remaining (tokens), X-RateLimit-Limit, X-RateLimit-Remaining.

What you can rely on:

text contains only tokens of your input, in order. Nothing is added, nothing is rewritten.
Same text and same rate give the same output for a given engine version. Your provider's prompt cache keeps working.
Inputs under 64 tokens come back unchanged, with tokens_removed: 0.
billed_tokens equals tokens_removed. If we remove nothing, you pay nothing.

Token counts use the o200k_base tokenizer. Other providers count a few percent differently; the difference is in your favour for models whose tokenizers produce more tokens for the same text.

GET /v1/me

What your key can see about itself. No side effects.

{
  "organization": { "name": "Acme", "status": "active" },
  "key": { "name": "production", "prefix": "tk_live_a1b2c3d4", "created_at": "2026-09-12T09:48:39.630Z" },
  "credits": { "billing_mode": "metered", "balance_tokens": 48215000, "price_per_m_tokens_usd": 0.2 },
  "limits": { "rate_limit_rpm": 60, "max_tokens_in": 131072 }
}

Errors

Every error has the same shape:

{ "error": { "code": "insufficient_credits", "message": "…", "request_id": "req_…" } }

Status	`code`	Meaning	Charged
400	`invalid_request`	Bad JSON, missing `text`, `rate` out of range	no
401	`invalid_api_key`	Missing or unknown key	no
402	`insufficient_credits`	Your balance is at zero. Write to us to add credits.	no
403	`key_revoked`, `organization_suspended`	The key or the organization is disabled	no
413	`text_too_large`	Over your token or size limit	no
429	`rate_limited`	Over your per-minute limit; `Retry-After` says when	no
500	`internal_error`	Our bug; send us the `request_id`	no
503	`engine_unavailable`, `service_unavailable`	We are down or saturated; `Retry-After` is set	no

Only 200 responses are ever charged, and only for what was removed.

Recommended integration

Keep a fallback to the original prompt. Tokeen being unavailable must never break your product:

import requests

def compress(prompt: str, rate: float = 0.8) -> str:
    try:
        r = requests.post(
            "https://api.usetokeen.com/v1/compress",
            headers={"Authorization": f"Bearer {TOKEEN_API_KEY}"},
            json={"text": prompt, "rate": rate},
            timeout=10,
        )
        if r.status_code == 200:
            return r.json()["text"]
    except requests.RequestException:
        pass
    return prompt  # any error: send the original, pay nothing to Tokeen

async function compress(prompt: string, rate = 0.8): Promise<string> {
  try {
    const res = await fetch("https://api.usetokeen.com/v1/compress", {
      method: "POST",
      headers: { Authorization: `Bearer ${process.env.TOKEEN_API_KEY}`, "Content-Type": "application/json" },
      body: JSON.stringify({ text: prompt, rate }),
      signal: AbortSignal.timeout(10_000),
    });
    if (res.ok) return (await res.json()).text;
  } catch {}
  return prompt;
}

What to compress: the part of the prompt that is long and read once (a document, a scrape, a tool result, an old turn of a conversation). What not to compress: short instructions, code, and anything you need verbatim. Start at rate: 0.8; go lower only where your evaluation says the answers hold.

Rates and credits

$0.20 per million removed tokens. Credits are prepaid or invoiced monthly, in removed tokens, and visible in the portal and in GET /v1/me. When the balance reaches zero the API answers 402 and your fallback sends the original prompt; ask for more from the portal's Credits page.

Where the data goes

Your prompt is processed in memory on servers in the European Union and never stored: not the text, not a hash of it. We keep counts and timings per request for billing. Details on request at hello@usetokeen.com.

Versioning

The path carries the version (/v1). Fields are only ever added. A breaking change would be a /v2, announced in advance.