Documentation

Quickstart

One line. Then read the rest of this page whenever you want more control.

Official SDKs

The Anthropic surface is complete under one prefix, because an SDK builds every path it will ever call from the single base URL you hand it. Point that base URL at /anthropic and the client you already have keeps working — there is no Prismux wrapper to install, no fork to track, and nothing in your code that knows our name except one string.

# python — the official anthropic package, unmodified
client = anthropic.Anthropic(base_url="https://api.prismux.com/anthropic",
                             api_key=PRISM_TOKEN)

// typescript — @anthropic-ai/sdk, unmodified
const client = new Anthropic({ baseURL: "https://api.prismux.com/anthropic",
                               apiKey: PRISM_TOKEN });

# the agent SDK reads the same variable every Anthropic tool reads
ANTHROPIC_BASE_URL=https://api.prismux.com/anthropic

Three paths make that work, and all three are served: POST /anthropic/v1/messages, GET /anthropic/v1/models, and POST /anthropic/v1/messages/count_tokens. The last two exist because an SDK calls them on its own: client.messages.count_tokens() against a router that served only /v1/messages returned 404, and a client that cannot list models cannot tell a typo from an outage.

raw = base64.b64decode(response.headers["x-prism-receipt"])
# or, without writing any code at all:
$ prism verify --receipt -

One more thing an SDK gives you for free: request-id is set to the receipt id, so response.request_id — the field the Anthropic clients already surface on every success and every raised error — is the identifier our chain is keyed on. Minting a second id beside it is how a support conversation ends up unable to join your log line to our record.

Model identifiers

Ask for a model, not an endpoint. claude-opus-5 resolves to whichever eligible endpoint your policy and our health data select — that is the entire point of the router. The receipt tells you which one served you.

If you need a specific substrate, pin it:

# any eligible endpoint (recommended)
"model": "claude-opus-5"

# a specific substrate and region — disables rung-0 failover
"model": "claude-opus-5@bedrock/eu-central-1"

# a vendor's own identifier, passed through unchanged
"model": "vertex/publishers/anthropic/models/claude-opus-5"

Pinning is a real trade: you gain determinism and lose the capacity of every other quota pool. Your effective availability for a pinned model cannot exceed that single endpoint's.

The full list, with posture, jurisdiction, reasoning grade and live rates, is the catalogue.

Local & self-hosted runtimes

Ollama, llama.cpp's server, LM Studio and vLLM are ordinary catalogue endpoints, not a footnote: same wire, same eligibility filter, same signed receipt per request. All four publish an OpenAI-compatible /chat/completions surface, which is why nothing in the router builds a special request for them — a fork for a wire format we already speak would be one more place for a body to drift.

This table is generated from SPECS in router/src/local.zig when this page is built, so a runtime added to the router appears here or the build fails.

The thing you set is a base URL, not a key. All four ship with authentication off, so there is no credential to issue and none to leak; where you launched one behind --api-key, the matching <RUNTIME>_API_KEY carries it and a bearer is sent. A router with a local runtime configured and no vendor account at all starts and serves.

There is no vendor catalogue of weights to transcribe, so the catalogue carries one endpoint per runtime and the concrete weight comes from the pin above, or from a live listing if you did not pin one. If you pulled several and pinned none, the request is refused and the candidates are named. Picking the alphabetically first of four would be a silent substitution that no receipt could ever expose — it would name a real model that really answered, and nobody would think to ask why it was that one.

Declared context window with nothing configured: 4,096 tokens, which is what all four serve unconfigured. Raise it with <RUNTIME>_MAX_CONTEXT to match how you launched the server. Declaring a larger window here would admit a prompt the runtime then silently truncates, which is the one failure a receipt cannot show.

Policy headers

The policy envelope travels on the request as plain headers, so it works through SDKs you did not write and tools you cannot modify. Anything you omit falls back to the key's policy, then the project's, then the organisation's — most specific wins.

Response headers

Every response — success or refusal — carries the provenance you need to reconcile it later, without parsing the body. This is a real capture, pasted: curl -D against the shipped router on 2026-09-04, started with --mock-upstream. The x-prism-mock: true line is left in, because a capture with its own honesty marker edited out is no longer a capture.

request-id: rcp_01M1NVNAXV72AQE4JTZRCCRVQG
x-prism-receipt-id: rcp_01M1NVNAXV72AQE4JTZRCCRVQG
x-prism-served-endpoint: ep_mock_anthropic_direct_use1_sonnet5
x-prism-served-model: claude-sonnet-5
x-prism-retention: retaining
x-prism-jurisdiction: US
x-prism-attempts: 1
x-prism-rate-card: rc_f679c826b60eb8ac8b6ea9452fca6391
x-prism-tokens-in: 2
x-prism-tokens-cache-read: 0
x-prism-tokens-cache-write: 0
x-prism-tokens-out: 92
x-prism-tokens-reasoning: 0
x-prism-tokens-reported-by: prism
x-prism-upstream-tokens-out: 89
x-prism-tokens-variance: 3
x-prism-tokens-variance-out-of-band: false
x-prism-provider-cost-usd: 0.000924
x-prism-charged-usd: 0.001141
x-prism-vault: off
x-prism-chain-prev: prf1:genesis
x-prism-mock: true
x-prism-receipt: eyJyZWNlaXB0X2lkIjoicmNwXzAxTTFOVk5BWFY3MkFR…

Three more are sent when the situation calls for them, and this request was too ordinary to produce any of them:

x-prism-rung    # only when a fallback was taken — how far it travelled
x-prism-reason    # only when a fallback was taken — the machine reason it moved
x-prism-budget-alert    # only on a request that crossed a SOFT budget ceiling and was served anyway — a hard ceiling refuses instead. It carries soft;period=;limit_usd=;committed_usd=;this_request_max_usd=;period_ends_at= — the running total and this request's own conservative maximum, because either number alone misleads — so an advisory breach reaches the caller on their own traffic rather than on an invoice four weeks later
x-prism-receipt-omitted    # instead of x-prism-receipt, if a receipt ever exceeds the 8 KB header ceiling. It names the byte count rather than going quiet

The names above are checked against responseHeaders() in router/src/main.zig when this page is built, in both directions: a header the router gained and this page never mentioned fails the build, and so does one this page still lists after the router dropped it.

Two numbers here are ours and say so. x-prism-tokens-reported-by reads prism because the five token counts are an in-path structural count — what we bill, and therefore what we must publish. x-prism-upstream-tokens-out is what the substrate's own usage block said, and x-prism-tokens-variance is the gap. In the capture above they differ by 3 tokens. Nobody else publishes that number, because publishing it means admitting the two figures can differ at all; when the substrate sent no usage block the value is the word absent, never a zero.

On a streamed response these arrive in the response head, not as trailers — measured on 2026-09-04, 20 of them. x-prism-receipt is not among them and cannot be: see Official SDKs for why, and for the terminal prism.receipt event that carries the same bytes instead.

Streaming

Both wire formats stream natively and we do not buffer. Two additions worth knowing about, both of which existing clients ignore safely:

• event: prism.failover — emitted mid-stream if we move to another endpoint. Carries the reason code and the new endpoint, so your UI can say what happened instead of showing an unexplained seam. Clients that don't know the event type skip it.
• event: prism.receipt — the final event, carrying the full receipt.

We count tokens in the stream ourselves rather than waiting for the upstream usage block, which may never arrive if the client disconnects. When upstream usage does arrive we reconcile the two, and any divergence beyond tolerance increments metering_variance on your dashboard. It is the one number nobody else publishes because nobody else admits the two figures can differ.

If you disconnect mid-stream, you are billed for what was actually generated up to that point — we know, because we relayed it.

Error reference

Closed taxonomy. Every error carries a machine code, one plain sentence, the constraint that bound, a receipt id, and a specific next action. A refusal here is more informative than a success elsewhere.

{
  "type": "error",
  "error": {
    "code": "retention_floor_unmet",
    "message": "This project requires zdr_contractual.
                gpt-5.x is available to us only at retaining, so the request
                was refused rather than sent — your prompt did not leave our
                network.",
    "binding_constraint": "min_retention_posture=zdr_contractual",
    "candidates_considered": 2,
    "candidates_eligible": 0,
    "next_action": "No endpoint we hold meets zdr_contractual.
                    Every posture we can evidence today is retaining, so this
                    floor cannot be satisfied by any model here until a
                    retention agreement is in place and verified.",
    "receipt_id": "rcp_01J8QK5T7GKC1M9PXQ2NDA4JS6",
    "docs": "https://prismux.com/docs#errors"
  }
}

Reason codes

Every attempt records why it happened: for a fallback, how the previous attempt ended; for the first attempt, the preference that chose that endpoint over the one we would otherwise have tried — when one did. A closed enum rather than prose, because your dashboard aggregates on it and prose cannot be counted. Billable? answers one question only: were you charged for an attempt that ended this way. A move is never charged for; the attempt it opens is billed like any other.

Split delivery

If a stream stalls after delivering tokens and we retry elsewhere, you received output from two endpoints. That is the one genuinely awkward billing case in this whole system, so the default is the one that costs us: absorb_retry, where you are billed for the first delivery only and we eat the second. The receipt marks it delivery: "split" either way.

The Prismux Receipt Format

PRF is an open specification for a signed, hash-chained, content-free record of one routed request. It is published under a permissive licence, and we would be pleased if other gateways adopted it — a format only we implement is a marketing asset, not a standard.

The three nested records

• Rate card — an immutable, content-addressed price document. Never edited; a price change mints a new version with supersedes set. Carries source URL, observation date, document hash and a maximum age.
• Attempt — one upstream try. Endpoint, rung, the reason the previous attempt ended, retention posture, timings including first token, the five token classes, how they were counted, the rate card, provider cost, and whether it was billable.
• Receipt — the request. Policy hash, demanded capabilities, every attempt including the ones that produced nothing, the charge breakdown, a promises block recording each guarantee kept or broken, vault status, the previous receipt's hash, its own hash, and a signature.

Why it cannot contain your content

The schema admits counts, identifiers, hashes, enumerations and timestamps. There is no free-text field, no body field and no header map. A guard walks the schema on every change and fails the build on any unconstrained string; a second guard walks the database columns so a future migration cannot quietly add a prompt column. That is what makes our retention claim structural rather than a policy we ask you to trust.

The chain

Receipts are chained per organisation: each carries the hash of the previous one. A receipt cannot be deleted, reordered or inserted after the fact without breaking the chain, and prism verify proves that offline. Daily chain heads and a monthly Merkle root — which is what lets you prove completeness rather than only integrity — are specified, and the router carries a comment where that code will go rather than the code. So a chain you hold is provably unaltered and provably ungapped internally, and completeness is the part you are still taking from us.

Corrections are append-only credit_note records that reference the original receipt, name a reason from a closed enum, and join the same chain. We cannot quietly edit a billing error — which is the point, and also why our pricing has to be right the first time.

The verifier · Try the live chain on the home page

Open-source verifier

A single static binary, in a different language from our data plane, with no dependency on our infrastructure. That is deliberate and it is the whole design constraint: verification that requires our SDK is not verification.

$ prism verify receipts-2026-08.jsonl --keys prismux-receipts.pub

  ◢◤ prismux  verify

  reading  4 receipts from receipts-2026-08.jsonl
  keys     1 from prismux-receipts.pub

  ✓ rcp_01M1B6WPD1PVJ…  claude-sonnet-5         direct     $0.001218
  ✓ rcp_01M1B6WPDB7HH…  claude-sonnet-5         direct     $0.001218
  ✓ rcp_01M1B6WPDM8NW…  claude-sonnet-5         direct     $0.001218
  ✓ rcp_01M1B6WPDY2S6…  claude-sonnet-5         direct     $0.001218

  ────────────────────────────────────────────────────────────────────────
  ✓ signatures 4 of 4 verified against the key you supplied
  ✓ 4 receipts · chain intact from genesis · total $0.004872

$ echo $?
0

The key came from the router's own start-up banner, which prints the line signing <id> ed25519pub:<base64> and tells you to pin it. prism verify reads that line verbatim.

It reads an export and a published key, recomputes every hash, walks the chain, checks for sequence gaps, and reconciles the total against your invoice. It never contacts us. Run it in your own CI against every invoice if you like — several finance teams will, and that is the intended use.

What a failure looks like

Both of these are real runs against the same four-receipt chain, one with the charged field of record 2 edited, one with record 3 deleted.

$ prism verify receipts-tampered.jsonl --keys prismux-receipts.pub
  ✓ rcp_01M1B6WPD1PVJ…  claude-sonnet-5         direct     $0.001218
  ✗ rcp_01M1B6WPDB7HH…  claude-sonnet-5         direct     $9.990000
  ✓ rcp_01M1B6WPDM8NW…  claude-sonnet-5         direct     $0.001218
  ✓ rcp_01M1B6WPDY2S6…  claude-sonnet-5         direct     $0.001218
  ────────────────────────────────────────────────────────────────────────
  ✗ rcp_01M1B6WPDB7HHG9…  line 2  content hash mismatch — this receipt was altered after signing
  • signatures 4 of 4 verified — but see the hash failures above: a signature attests the hash, not the content
  ✗ 1 failures · an invoice built on this chain cannot be trusted · total $9.993654
  intact through 1 receipts, then line 2
$ echo $?
1

$ prism verify receipts-gap.jsonl --keys prismux-receipts.pub
  ✗ rcp_01M1B6WPDY2S6RA…  line 3  broken link — the record before this one does not match
  intact through 2 receipts, then line 3
$ echo $?
1

prism — the companion CLI

prism is deliberately not another coding agent. Building one would mean competing with the tools you already use, and we would rather work with them. It reads your receipt stream and your vault instead, and gives whatever you already use the layer it lacks.

Limits and retries

Upstream rate limits are ours to absorb, not yours to see. A 429 from a vendor becomes a rung-0 failover to another quota pool; you see a 429 from us only when your own per-key limit is the binding constraint, and then Retry-After is set honestly.

• Retry safely with X-Prism-Idempotency-Key. A retry carrying the same key returns the original receipt rather than billing a second time. Keys are held for 24 hours.
• Reservations, not post-hoc billing. A conservative maximum is held against your balance and tested against your period ceiling at admission — in one critical section, before anything is forwarded — and released on settlement. So an in-flight request’s maximum is already spent as far as every concurrent request is concerned, and N requests arriving in the same instant cannot each decide independently that they fit. That is what makes budget_exhausted a guarantee rather than a best effort: not that we check a number, but where we check it.
• Hard ceilings refuse; soft ceilings alert. A hard ceiling returns budget_exhausted before a token is forwarded. A soft one always serves and reports instead: x-prism-budget-alert on the response, and a budget_soft_breaches counter on /health for whoever is watching the account rather than the request. Periods are UTC — daily rolls at 00:00Z, weekly on Monday 00:00Z, monthly on the 1st — and a ceiling is set per organisation with POST /v1/admin/orgs/<org>/budget, amounts as quoted decimal strings so they never pass through a float.
• Circuit breakers are per endpoint, with exponential probe backoff and half-open recovery. An endpoint we have marked open is skipped rather than tried and failed, which is why circuit_open attempts cost nothing and add no latency.

Vault and export API

Three modes, configured per key or per request. Full explanation of the trade on Trust → the vault.

# List sealed records (metadata only — we cannot read the contents)
GET /v1/vault/objects?since=2026-08-01&project=acme-client-14

# Fetch ciphertext. Unwrapping happens on your machine, with your key.
GET /v1/vault/objects/rcp_01J8QK4M2XN7B3VYFH0RTZ6WC9

# Export receipts for verification and reconciliation
GET /v1/receipts/export?month=2026-08&format=jsonl

# Published signing keys, with validity windows and rotation history
GET /.well-known/prismux-signing-keys.json

In customer_bucket mode the object endpoints return a pointer into your own bucket rather than bytes from us, because in that mode we hold nothing at all — not even the ciphertext.