API documentation

Overview

The Trimml API lives at https://api.trimml.com. It has one job: take a prompt, strike the tokens it never needed, and hand it back. The output is a strict subsequence of your input — every output token is one of your input tokens, in order — so nothing is paraphrased, reordered, or invented. All endpoints accept and return JSON.

Using Claude Code or Codex? The trimml CLI routes them through this API automatically — install, sign in, and every request is compressed in flight, with no code changes.

curl -fsSL https://trimml.com/install.sh | bash
trimml login
trimml on

Authentication

Issue keys in the console's API keys page. A key looks like dk- followed by 48 hex characters, and the secret is shown exactly once at creation — we store only a hash and the first 8 characters for display. Send it as a bearer token on every request:

Authorization: Bearer dk-9f2c41a8…

Requests without the header, or with a revoked or unknown key, get 401. Keys are account-scoped bearer credentials — treat them like passwords and revoke them in the console if they leak.

POST /v1/compress

Compress one prompt. Request body:

Response — 200:

Example:

curl https://api.trimml.com/v1/compress \
  -H "Authorization: Bearer $TRIMML_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "input": "Please carefully review the following information and provide a detailed summary...",
    "aggressiveness": "balanced"
  }'

{
  "output": "review the following information summary...",
  "original_input_tokens": 23,
  "output_tokens": 9,
  "tokens_saved": 14,
  "compression_ms": 38.2
}

Short-input pass-through: inputs under 64 tokens are returned unchanged with tokens_saved: 0 — they're too small to be worth touching, and a request that saves nothing costs nothing.

GET /v1/usage

Lifetime usage totals for the key making the request — handy for reconciling your own metering against ours. (The console shows the same numbers across all your keys, broken down by day.)

curl https://api.trimml.com/v1/usage \
  -H "Authorization: Bearer $TRIMML_API_KEY"

{
  "requests": 18234,
  "original_tokens": 9120440,
  "output_tokens": 4163810,
  "tokens_saved": 4956630
}

GET /v1/health

Unauthenticated liveness check. Returns {"status": "ok"}.

Errors

Errors are JSON with a detail field, following standard HTTP semantics:

Limits & latency

• Rate limits: none enforced today. If your sustained volume is large enough to worry about, email support@trimml.com and we'll provision for it. Per-key limits may be introduced later and will be announced first.
• Latency: p95 added latency is 41ms (internal benchmark — measured on our internal corpus; your prompt sizes and network path will vary). Compression is a single forward pass, not an LLM call.
• Input floor: inputs under 64 tokens pass through unchanged (see above).

Code samples

The same compress call in two languages. Send your raw prompt, then forward output to your model.

import os
import requests

resp = requests.post(
    "https://api.trimml.com/v1/compress",
    headers={"Authorization": f"Bearer {os.environ['TRIMML_API_KEY']}"},
    json={
        "model": "claude-sonnet-4-5",
        "input": prompt,                 # your raw prompt
        "aggressiveness": "balanced",    # optional
    },
    timeout=10,
)
resp.raise_for_status()
data = resp.json()

compressed_prompt = data["output"]       # forward this to your model
print(f"saved {data['tokens_saved']} tokens "
      f"in {data['compression_ms']}ms")

Billing

You pay 20% of measured savings, and nothing else. Each request's tokens_saved is valued at a transparent blended rate of $3.00 per million input tokens; your monthly invoice is 20% of the total — reproducible from the same per-request metering shown in your console. See the Terms of Service for the formal version.