TrustedRouter / API guide

Strict Budget API Guide

Create API keys with opt-in strict budget admission. Understand USD limits, in-flight estimates, UTC resets, concurrency bounds, and retry handling.

Provider routing reference

Two hosts: inference and account management

Use the attested gateway for inference and the control plane for key management. Both accept Authorization: Bearer <API key>; key management requires a management key.

Host	What it serves
`https://api.trustedrouter.com/v1`	Inference: `POST /v1/chat/completions`, `/v1/responses`, `/v1/messages`, `/v1/embeddings`, images, and videos. Also `GET /v1/models` and `GET /v1/key` (inspect the current key).
`https://trustedrouter.com/v1`	Account management: `POST /v1/keys` and `GET /v1/keys`; `GET`, `PATCH`, and `DELETE /v1/keys/{hash}`; credits, activity, and workspaces. `GET /v1/key` also works here.

Management calls to the inference host return 404. For example, list your keys on the control plane:

curl https://trustedrouter.com/v1/keys \
  -H "Authorization: Bearer $TR_MANAGEMENT_KEY"

Keep management keys on your server. Use an inference key in your model client.

Spend controls overview

Create a key with a deliberate budget

Use a management key with POST https://trustedrouter.com/v1/keys. limit, limit_daily, limit_weekly, and limit_monthly are USD amounts. budget_strict is off by default and immutable after creation.

import os
import httpx

response = httpx.post(
    "https://trustedrouter.com/v1/keys",
    headers={"Authorization": "Bearer " + os.environ["TR_MANAGEMENT_KEY"]},
    json={
        "name": "Research agent",
        "limit_daily": 5,
        "limit_monthly": 100,
        "budget_strict": True,
        "budget_alert_only": False,
    },
    timeout=30,
)
response.raise_for_status()
# Store the returned key securely. Keep it out of logs.

Use the new key for inference at https://api.trustedrouter.com/v1. Read its settings with GET /v1/key on either host. Create a separate key to change admission mode; changing budget_strict on an existing key is rejected.

Manage end-user keys in bulk

Page through keys with GET /v1/keys?limit=100&offset=0 and follow next_offset until it is null. limit accepts 1–1000. Disabled keys are included unless you pass include_disabled=false. To revoke keys, send up to 1,000 hashes as {"hashes": [...]} to POST /v1/keys/bulk-delete, which reports deleted or not_found for each hash. Only the caller's workspace is affected.

The control plane allows each source IP 300 state-changing requests and 2,400 requests in total per 60 seconds. A bulk delete counts as one write. Back off on 429, honoring Retry-After when present. GET /v1/key reads usage from a snapshot up to five seconds old, and Activity arrives through a separate pipeline, so the two can briefly disagree. See key management for paging, transactions and retries.

What strict mode counts

Ordinary spend-window checks are approximate and exclude in-flight holds. Strict mode counts outstanding estimated costs alongside settled spend in each enforced UTC window. Settlement or refund releases the recorded hold, even across a window reset.

Strict mode is estimated-cost admission, not an absolute final-charge guarantee. Actual provider usage may exceed an estimate. budget_alert_only: true remains alert-only; leave it false for enforcement.

Latency and concurrency

Strict authorization can be much slower because it uses a shared database counter and bypasses local spend leases. Each process admits at most 16 strict keys concurrently, with one authorization per key and no waiting queue.

The database-work budget is five seconds. Other request work and connection acquisition remain subject to their existing bounds. The admission slot is released after authorization, before generation, so a long answer does not occupy it.

Handle limits and retries

429: an enforced spending window is exhausted, or request traffic is throttled. Honor Retry-After and the RateLimit-Reset window.
503: strict admission is busy or temporarily unavailable. Use bounded exponential backoff with jitter.
RateLimit-Limit and RateLimit-Remaining are integer microdollars, unlike the USD amounts in key creation.

See spend-window headers and tagging for client backoff and cost attribution. Keep management keys on your server.