API Docs: Quickstart and SDKs

Fail-closed privacy filters

{
  "model": "your/model",
  "provider": {"min_privacy": "zdr"}
}

{
  "model": "your/model",
  "provider": {"min_privacy": "confidential"}
}

trustedrouter/e2e and trustedrouter/confidential select the same verified compute + E2EE + ZDR pool. A TR-funded ZDR agreement qualifies only the funded route, not BYOK. provider.data_collection = "deny" remains an OpenRouter-compatible routing preference; use min_privacy when the privacy floor must never be relaxed.

Confidential-only API hostname

Use https://api.confidential.trustedrouter.com/v1 and explicitly include "provider": {"min_privacy": "confidential"} in every inference request. The hostname is an additional guard, not an implicit default: missing, weaker, or alias values such as e2e return 400 confidential_privacy_required before inference.

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["TRUSTEDROUTER_API_KEY"],
    base_url="https://api.confidential.trustedrouter.com/v1",
)
response = client.chat.completions.create(
    model="trustedrouter/confidential",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={"provider": {"min_privacy": "confidential"}},
)

Chat Completions, Responses, and Anthropic Messages use the same hard confidential filter, including internal orchestration calls and fallback candidates. If no eligible endpoint remains, the request fails instead of using an ordinary provider. Hosted web search, batch/files, embeddings, and media APIs are not supported on this hostname.

The equivalent mirror base URLs are https://api.confidential.quillrouter.com/v1, https://api.confidential.allyrouter.com/v1, and https://api.confidential.uptimerouter.com/v1. They require the same explicit setting. Health, attestation, and public catalog discovery remain available without it; the catalog is not a filtered list of eligible endpoints.

The ordinary API hostname is unchanged. A hostname and HTTPS alone are not independent proof of confidential execution: clients that verify hardware attestation should still follow the attestation verification guide.

Guides

SDKs

Model route changes

Poll GET https://trustedrouter.com/v1/models/changes or subscribe to the Atom feed. Both are public and need no API key. They report model and provider-route additions and removals, route metadata changes, confidential route gains and losses, best privacy tier changes, and upcoming provider retirements.

GET /v1/models/changes?model=deepseek/deepseek-v4-flash&since=2026-09-01T00:00:00Z
GET /v1/models/changes.atom?type=confidential_route_lost
GET /v1/models/changes?upcoming=true

Each entry has a stable id, model, type, before, after, recorded_at and effective_at. Results are complete and ordered by (recorded_at, id), ascending. since is inclusive and filters when entries were recorded, so newly announced future changes are discoverable immediately. Save the greatest recorded_at you receive and deduplicate the next poll by id. Use timezone-qualified timestamps; model matches an exact public id. Repeat type to select several change types. upcoming=true selects future effective dates; false selects changes already effective; omit it for both.

Announcements use retirement_scheduled; projected route changes have source: "scheduled" and the announced effective date. They describe the current plan. If a forecast is withdrawn or replaced, it disappears from the current feed and a schedule_cancelled entry identifies its old id. Scheduled pricing policies use pricing_schedule_changed, excluded by default: select that type or add include_prices=true. Ordinary price refreshes and each recurring peak/off-peak switch are omitted to keep subscriptions readable; pricing policy entries contain the recurring schedule.

trustedrouter.last_route_change_at in /v1/models gives the latest recorded route change that is already effective, or null if none is known. The history starts with a September 1, 2026 baseline and replays committed catalog revisions using their contemporary privacy rules. Backfilled observations use commit dates, not deployment timestamps. Later entries describe catalog observations and announced cutovers; they do not establish release completion, live provider health, capacity, or credential availability. Conditional discovery-expiry deadlines are recorded when observed, rather than forecast as provider retirements.

Model request capabilities

GET /v1/models includes trustedrouter.capabilities on concrete model rows. For example, GPT-5.5 reports:

"capabilities": {
  "reasoning_effort": ["none", "low", "medium", "high", "xhigh"],
  "tools": true,
  "seed": true,
  "vision": true,
  "confidential": false
}

Model-level tools and seed match membership in the model row's final supported_parameters; vision matches image input in architecture.input_modalities. These discovery fields include model declarations and current Credits and BYOK route declarations after known overclaims are removed. Some routes declare less than the model supports: GPT-5.5's OpenAI routes report seed: false even though its model-level discovery union includes seed. tools means function tools; seed means a supported seed control (not guaranteed deterministic output); vision means image input, not image generation. These flags describe each control independently, not every combination.

Per route, reasoning_effort has three states: a non-empty list gives verified accepted values; [] means do not send effort because the route is verified to accept none; null means not verified. At model level, it is the union of verified lists, or [] when every route is verified to reject effort, otherwise null. Mistral Large reports []. Values appear in this order: none, minimal, low, medium, high, xhigh, max. The string "none" is an explicit accepted value, distinct from null and []. Values describe the top-level chat reasoning_effort control after gateway translation, which can map to a token budget or thinking level. Do not combine it with a conflicting reasoning.enabled or budget setting.

Default routing filters by the parameters that decide what kind of response comes back: tools and tool_choice (tool calling) and response_format (structured output). It skips a route the catalog says lacks the capability. For tool calling, that is a route that does not declare tools while another route of the same model does. For either, a routing pool such as trustedrouter/auto skips a model that declares the capability neither on its own row nor on any route. A model you name keeps its routes when the catalog says nothing either way, because some models take tools without declaring them. When no route is left, the request fails with a 400 that names the parameter. Other parameters are filtered only with provider.require_parameters: true, which keeps only routes whose own supported_parameters include every parameter sent. Check the per-route values first: trustedrouter.endpoints[].capabilities and the route's supported_parameters, because some routes declare less than the model supports. This filters parameter names, not effort values or image input; pin a suitable provider when values differ. GET /v1/models/{author}/{slug}/endpoints returns each endpoint's trustedrouter.capabilities without an API key. The default list omits per-route detail to stay small; GET /v1/models?include=endpoints adds trustedrouter.endpoints[] and the model-level trustedrouter.provider_policy text to every row.

confidential is an availability flag: at least one current endpoint satisfies the same confidential privacy rule used in routing, including verified compute, end-to-end encryption, zero retention, and exclusion of the model's own vendor. On the confidential host, send provider.min_privacy: "confidential"; the host requires it and ordinary endpoints are excluded. The flag describes catalog eligibility, not live health, your credentials, or capacity. Zero retention alone does not qualify.

Routing aliases such as trustedrouter/auto, orchestration models, and hidden routes omit the object because their selected models and internal calls can vary. Absence is not a declaration of no support. A routing pool (trustedrouter/auto, cheap, fast, frontier, advanced, professional, efficient, eu, zdr, e2e, green) lists a parameter in supported_parameters only when every model it can route to has one of the pool's routes that accepts it, so a request that sends it with provider.require_parameters: true keeps every model in the pool. Its architecture.input_modalities lists what any of its routes accepts; routing sends image input only to routes that accept images. Its context_length is the largest window among the models it routes to: chat routing sends a request only to models whose window holds its estimated prompt plus max_tokens, and answers 400 context_length_exceeded when none does. Otherwise the legacy supported_parameters union and architecture.input_modalities remain discovery fields; they need not describe every endpoint.

API reference

Manage keys at scale

Key management runs on the control plane, https://trustedrouter.com/v1, with a management key. Every operation is limited to the caller's workspace. Keep management keys on your server.

List and page through keys

GET /v1/keys?limit=100&offset=0 returns {"data": [...], "next_offset": 100}. Pass next_offset as the next request's offset with the same limit and filter. A null next_offset marks the last page. limit accepts 1–1000 and offset accepts any non-negative integer. Other values return HTTP 400 with error.type: "bad_request".

Keys sort newest first, with ascending hash as the tie-breaker. Disabled keys are included unless you pass include_disabled=false, which filters before paging. Without limit, the response keeps its original {"data": [...]} shape and lists every key after the offset. offset and include_disabled match OpenRouter's parameters; limit and next_offset are TrustedRouter additions.

Each page reads keys and their usage together in one database query. Creating or deleting keys between requests shifts later offsets. To delete every key, collect the hashes first, or keep reading page zero while you delete.

Delete many keys in one request

POST /v1/keys/bulk-delete
Authorization: Bearer $TR_MANAGEMENT_KEY
Content-Type: application/json

{"hashes": ["key_first", "key_second"]}

HTTP 200
{"data": [{"hash": "key_first", "status": "deleted"},
          {"hash": "key_second", "status": "not_found"}]}

Send 1–1000 hashes per request. Results follow the input order, and a repeated hash repeats its first result. Missing keys and keys in another workspace both report not_found. Each group of up to 100 distinct hashes is deleted atomically, together with its lookup indexes. Groups commit independently, so after a failure you can retry the whole request; keys already deleted then report not_found. DELETE /v1/keys/{hash} also deletes atomically and returns {"data": {"deleted": true, "hash": "..."}}, or 404 when the key does not exist.

Request rate limits and retries

The control plane limits each source IP address, across every credential behind it:

• 300 state-changing requests per 60 seconds: POST, PUT, PATCH, and DELETE. Each DELETE /v1/keys/{hash} counts once.
• 2,400 requests per 60 seconds of any method, including GET /v1/keys.

A request over either limit gets HTTP 429 from the edge, before it reaches the API. That response may be HTML or plain text and need not carry Retry-After. Management calls have no separate per-key request quota. A bulk delete counts as one write, so revoking 1,000 keys takes one request instead of more than three minutes of single deletes.

Back off on every 429. Honor Retry-After when present; otherwise use capped exponential backoff with jitter. Database contention returns 503 with error.type: "service_unavailable" and Retry-After: 1; retry it the same way. Inference spend-window limits use the separate RateLimit-* headers below.

Usage freshness

Key usage counters advance when a request settles. GET /v1/key reads them from a snapshot up to five seconds old. GET /v1/keys reads them with a strong read.

Activity comes from a separate analytics pipeline. It can show a request before GET /v1/key does, or after it, and it trails further when the pipeline has a backlog. data.analytics.drain_lag_seconds in status.json reports that backlog. A key's updated_at changes with its settings, not with usage.

Billing and usage

Token counts and token list prices are the starting point for billing. Review the rounding rules below, then inspect credits and activity at https://trustedrouter.com/v1 to reconcile charges.

Spend-window rate limits

A key with a hard daily, weekly, or monthly spend limit gets the governing window on every response. Values are integer microdollars, the same unit used by the key-limit API. Keys without a hard spend window do not get fabricated rate-limit headers.

{"name":"Strict project budget","limit_daily":5,"limit_monthly":100,"budget_strict":true}

import math
import time
import httpx

jobs = [{"model": "trustedrouter/auto", "messages": [...]}]
next_budget_microdollars = 50_000

with httpx.Client() as client:
    while jobs:
        response = client.post(API_URL, headers=AUTH, json=jobs[0])
        reset = max(1, math.ceil(float(
            response.headers.get("RateLimit-Reset", "1")
        )))

        if response.status_code == 429:
            time.sleep(max(1, int(response.headers.get("Retry-After", "5"))))
            continue

        response.raise_for_status()
        jobs.pop(0)
        remaining = int(response.headers.get(
            "RateLimit-Remaining", next_budget_microdollars
        ))
        if jobs and remaining < next_budget_microdollars:
            time.sleep(reset)