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

Spend controls overview

Create a key with a deliberate budget

Use a management key with POST /v1/keys on the control-plane hostname. 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 the control-plane hostname. Create a separate key to change admission mode; changing budget_strict on an existing key is rejected.

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. 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.