API reference
JetRouter speaks the OpenAI API. Chat completions, legacy completions, embeddings and streaming all keep the request and response shapes your SDK already knows; the model string becomes a catalog slug, and a handful of optional blocks let you steer routing, caching and cost.
Defaults to the host you are reading this on. The router is served at /v1 on the same origin as this portal.
Start here
Set JETROUTER_API_KEY to a key from your dashboard and run one of these. Nothing else is required — no SDK of ours, no config file.
curl https://jetrouter.dev/v1/chat/completions \
-H "Authorization: Bearer $JETROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-sonnet-5",
"messages": [
{ "role": "user", "content": "Say hello in one sentence." }
]
}'Authentication
Send your jr- key as a bearer token. Keys are created in the dashboard and shown exactly once, at creation — we store only a SHA-256 hash and cannot show it to you again. Lose one and rotate it; there is nothing to recover.
Authorization: Bearer jr-xxxxxxxxxxxxxxxxxxxxxxxxPolicy lives on the key
Requests run on our provider accounts
The catalog
A slug is vendor/model — anthropic/claude-opus-5, openai/gpt-5, google/gemini-2.5-flash. It is stable, it is what you are billed under, and it is what appears in your activity log, whichever upstream actually served the call.
/v1/modelsGET/v1/models/{slug}# Public — no key required.
curl https://jetrouter.dev/v1/models
# One model, including its exact per-token prices.
curl https://jetrouter.dev/v1/models/anthropic/claude-opus-5jetrouter/autojetrouter/cheapestjetrouter/fastestCore
The OpenAI request body, unchanged. Sampling parameters, stop sequences, seeds, tool definitions and response formats are forwarded to the provider that serves the call.
/v1/chat/completions| Field | Type | Notes |
|---|---|---|
| model | string | A catalog slug, a meta-slug, or a legacy alias. Required. |
| messages | array | At least one message. Required. |
| stream | boolean | Server-sent events when true. |
| max_tokens | integer | Also the basis of the credit reservation held while the call runs. |
| temperature, top_p, top_k, stop, seed | — | Forwarded to the provider. A provider that does not accept one drops it — the request is still served. |
| tools, tool_choice | — | Forwarded verbatim, and billed as input: they are part of what the provider charges for. |
| response_format | object | Forwarded to the provider, and dropped by it if unsupported. |
| provider | object | JetRouter extension — see Provider routing. |
| cache | object | JetRouter extension — see Caching. |
Core
Set stream: true and you get text/event-stream with the usual data: frames and a final [DONE]. The charge settles when the stream closes, from the tokens actually delivered.
curl -N https://jetrouter.dev/v1/chat/completions \
-H "Authorization: Bearer $JETROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-sonnet-5",
"messages": [{ "role": "user", "content": "Count to five." }],
"stream": true
}'Extensions
One slug can have several deployments. By default the router takes the cheapest healthy one and steps over an upstream that is failing. The provider block lets you override that per request.
curl https://jetrouter.dev/v1/chat/completions \
-H "Authorization: Bearer $JETROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-opus-5",
"messages": [{ "role": "user", "content": "Hello" }],
"provider": {
"order": ["anthropic", "openrouter"],
"sort": "price",
"allow_fallbacks": true
}
}'| Field | Values | Effect |
|---|---|---|
| order | array of provider names | Try these first, in this order. Anything not listed still follows, unless fallbacks are off. |
| sort | price · throughput | How the remaining candidates rank. Defaults to price. |
| allow_fallbacks | boolean | False confines the request to the providers you named. Defaults to true. |
Extensions
Two different mechanisms, both opt-in, both visible on the response.
curl https://jetrouter.dev/v1/chat/completions \
-H "Authorization: Bearer $JETROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-haiku-4-5",
"messages": [{ "role": "user", "content": "Classify: refund request" }],
"cache": { "ttl": 300 }
}'Core
Both take the same key, the same policy and the same metering as chat.
/v1/embeddingscurl https://jetrouter.dev/v1/embeddings \
-H "Authorization: Bearer $JETROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/text-embedding-3-small",
"input": ["the quick brown fox", "the lazy dog"]
}'/v1/completionscurl https://jetrouter.dev/v1/completions \
-H "Authorization: Bearer $JETROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-haiku-4-5",
"prompt": "Finish this sentence: routing is",
"max_tokens": 32
}'Introspection
Limits and usage for the calling key, in the OpenRouter shape. This is the endpoint to read before you assume an entitlement — it is published by the same module the request path enforces.
/v1/keycurl https://jetrouter.dev/v1/key \
-H "Authorization: Bearer $JETROUTER_API_KEY"{
"data": {
"label": "production",
"usage": "128.500000",
"limit": "5000.000000",
"limit_remaining": "4871.500000",
"is_free_tier": false,
"rate_limit": { "requests": 600, "interval": "1m" },
"jetrouter": {
"tier": "growth",
"tenant_balance_usd": "16.461538462",
"tenant_available_usd": "16.298076923",
"pii_mode": "off",
"saving_tier": "off",
"allowed_models": null
}
}
}| Field | Meaning |
|---|---|
| limit | This key's spend cap in US dollars, or null when it has none. |
| limit_remaining | What this key can still actually spend: the cap less usage, floored by the tenant's available wallet. On a prepaid router those are different questions. |
| rate_limit.requests | The effective limit — the lower of the key's own RPM and the tenant's. Publishing the key's alone would promise throughput the tenant window rejects. |
| jetrouter.pii_mode | off, warn or tokenize — the privacy mode set on this key. |
Introspection
Every response carries X-JetRouter-Request-Id. Hand it back here for the full cost breakdown of that call.
/v1/generation?id=# The id comes from the X-JetRouter-Request-Id response header.
curl "https://jetrouter.dev/v1/generation?id=$REQUEST_ID" \
-H "Authorization: Bearer $JETROUTER_API_KEY"{
"data": {
"id": "7c9f0a1e-1d3b-4a55-9b7c-2f1a0e5d6c88",
"model": "anthropic/claude-sonnet-5",
"provider_name": "anthropic",
"streamed": false,
"created_at": "2026-09-04T02:11:47.913000+00:00",
"tokens_prompt": 1842,
"tokens_completion": 311,
"native_tokens_prompt": 1842,
"native_tokens_completion": 311,
"tokens_cache_read": 1536,
"tokens_cache_write": 0,
"cache_hit": false,
"usage": "0.000529231",
"total_cost": "0.000529231",
"usd_charged": "0.000529231",
"cache_discount": "0.000283846",
"usd_saved": "0.000283846",
"latency": 2140,
"finish_reason": "stop",
"status": 200,
"model_asked": "anthropic/claude-sonnet-5",
"saving_tier": "off",
"models_used": ["anthropic/claude-sonnet-5"]
}
}Optional
Every key carries a pii_mode, and it defaults to off. It is set in the dashboard, not per request, and GET /v1/key reports the one in force. It governs the routed surfaces — /v1/* and /legacy/v1/* — where you send a prompt and we decide what to do with it. The /jetrouter/v1/* privacy endpoints are not gated by it: calling /jetrouter/v1/anonymize is the instruction, so the dial has no default left to apply.
| Mode | What happens to the request |
|---|---|
| off | Nothing examines the prompt. It is routed as written. This is the default and it is what most traffic runs on. |
| warn | Detected personal data is counted by type and returned on X-JetRouter-PII-Warning. The prompt is still sent as written. |
| tokenize | Detected values are replaced with vault tokens before the request leaves and restored in the reply. An independent egress gate then scans the whole outbound body and refuses the call with 422 egress_blocked if a pattern-class value survived. stream: true is refused on such a key. |
Reference
A sibling surface to the router, at /jetrouter/v1/*, authenticated with the same jr- key. Use it when you want to detect or replace personal data yourself — before sending text somewhere we do not route, or to hold your own tokens across several calls. It is not governed by the key’s pii_mode: calling it is the instruction.
/jetrouter/v1/detect# The privacy API is a SIBLING of the router, not a path under it.
curl https://jetrouter.dev/jetrouter/v1/detect \
-H "Authorization: Bearer $JETROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "text": "Director Chan Tai Man, HKID K123456(0), phone 9123 4567" }'{
"entities": [
{ "entity_type": "PERSON", "start": 9, "end": 22, "score": 0.85 },
{ "entity_type": "HK_HKID", "start": 30, "end": 40, "score": 0.95 }
],
"profile": "hk_business",
"capability": "multilingual",
"ner_unmapped": { "MISC": 1 }
}/jetrouter/v1/anonymizecurl https://jetrouter.dev/jetrouter/v1/anonymize \
-H "Authorization: Bearer $JETROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "text": "Director Chan Tai Man, HKID K123456(0)" }'{
"text": "Director [PERSON_A3F9C_1], HKID [HK_HKID_A3F9C_1]",
"session_id": "0b8f1e2c-6d21-4f0a-9a3e-1f77c0c4b512",
"capability": "multilingual",
"ner_unmapped": {}
}/jetrouter/v1/restore# session_id comes from the /anonymize response. Only the subscriber that
# created the session may restore it, and it expires with the tokens.
curl https://jetrouter.dev/jetrouter/v1/restore \
-H "Authorization: Bearer $JETROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "session_id": "$SESSION_ID", "text": "Contact [PERSON_A3F9C_1] about the file." }'/jetrouter/v1/estimatecurl "https://jetrouter.dev/jetrouter/v1/estimate?provider=anthropic&model=claude-sonnet-5&chars=4000" \
-H "Authorization: Bearer $JETROUTER_API_KEY"{
"provider": "anthropic",
"model": "claude-sonnet-5",
"chars": 4000,
"estimated_usd": 0.0024,
"breakdown": { "token_in": 0.0024 },
"note": "input-side estimate; output tokens are settled from actual usage"
}/jetrouter/v1/audit/reportcurl "https://jetrouter.dev/jetrouter/v1/audit/report?from=2026-08-01&to=2026-08-31" \
-H "Authorization: Bearer $JETROUTER_API_KEY"Optional
Which free model is currently best at a kind of work, and why. The ranking is computed from measured health, measured latency and published capabilities — not asserted — and every answer carries the evidence it was computed from.
/v1/jet/modelscurl "https://jetrouter.dev/v1/jet/models?category=code" \
-H "Authorization: Bearer $JETROUTER_API_KEY"Reference
Routing comes back on every served response, and cost on every non-streamed one, so you never have to reconcile a bill to find out what happened. A stream's total is not known when its headers are sent — read the cost off GET /v1/generation with the request id instead.
curl -i https://jetrouter.dev/v1/chat/completions \
-H "Authorization: Bearer $JETROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"jetrouter/cheapest","messages":[{"role":"user","content":"hi"}]}'| Header | Value |
|---|---|
| X-JetRouter-Request-Id | The id to pass to GET /v1/generation. Present on EVERY response — a served one and a refused one alike. On a refusal it rides in the body too (request_id beside error/type/status/detail in problem+json, request_id inside the error object on /v1/*), so a 4xx or 5xx you did not expect can be quoted back to us. |
| X-JetRouter-Provider | Which upstream served this request. |
| X-JetRouter-Cache | hit or miss. Set on every served response, never absent. |
| X-JetRouter-Cache-Bypass | Present only when you asked for the response cache and the request could not use it, naming what made it ineligible: temperature (an omitted or non-zero temperature with no seed), stream, tools, n, pii_mode (the key's privacy mode is warn or tokenize), fanout, or key-unavailable. Without it the only symptom would be miss on every call. Absent when you did not send a cache block, and absent on a request the cache took — a miss there is a real miss and may hit next time. |
| X-JetRouter-Cost-USD | US dollars the ledger took for this call, as a fixed-point string. Absent on a stream: the total is not known when the headers are sent. |
| X-JetRouter-Saved-USD | What the savings engine removed from the charge, in US dollars. Absent on a stream, for the same reason. |
| X-JetRouter-Discount-USD | Your tenant's negotiated commercial discount, in US dollars, counted separately from engine savings. Absent on a stream, for the same reason. |
| X-JetRouter-Saving-Tier | Present only when a saving tier substituted a cheaper model for this call. The tier that was in force. |
| X-JetRouter-Model-Asked | The model you named, when it differs from the one that served you. |
| X-JetRouter-Model-Served | The model that actually ran. The `model` field in the response body carries this same value, so a substitution is visible without reading headers at all. |
| X-JetRouter-Models-Used | Every model the call actually ran through, comma-separated, in order. One name on a straight substitution; more when a cascade or a planner stage ran. Present on the same responses as X-JetRouter-Saving-Tier. |
| X-JetRouter-Saving-Planner | The free model that read the task and chose the executing one, when a planning stage ran. Absent when none did. It is disclosed because the planner sees your prompt under a weaker policy than the model that serves it. |
| X-JetRouter-Max-Tokens-Budgeted | The output ceiling we fitted to your balance, when you named no max_tokens and could not afford the model's full ceiling. The request was shortened rather than refused; without this header the only symptom would be finish_reason: "length" on a call you never capped. Absent on every request that was not shortened. |
| X-JetRouter-PII-Pipeline | Which privacy mode ran on THIS request: off, warn or tokenize. Present on every chat response, including off — so a response with no X-JetRouter-PII-Warning is never ambiguous between “we looked and found nothing” and “we did not look”. off is the default on a new key: your prompt is routed with no detection, no tokenization and no egress gate, and this header is where that is stated. Set a key’s mode to warn or tokenize to change it. |
| X-JetRouter-PII-Warning | Entity-type COUNTS, as JSON, when the key's privacy mode is warn or tokenize and the prompt carried personal data. Never a value. |
| X-JetRouter-PII-Capability | What the detector could examine on THIS request: finetuned or multilingual (names, organisations and addresses in free text were covered), degraded (they were not), not_applied (the layer did not run). Absent when the key's mode is off, because nothing looked. |
| X-JetRouter-PII-Unclassified | Entity-type COUNTS, as JSON, for things the detector FOUND in your text and could not classify — on /jetrouter/v1/detect and /jetrouter/v1/anonymize. Read it together with X-JetRouter-PII-Capability, which answers whether the layer looked, not whether it could name what it saw: a response can report a working detector and still carry this header, and on /anonymize that means the text we returned to you may still contain the entity. The same counts appear as ner_unmapped in the body. Absent when there is nothing to disclose. Never a value. |
| Retry-After | On a 429 only. |
Reference
On /v1/* errors are in the OpenAI shape, so an SDK’s own error handling works. Our precise reason stays in code, and where a refusal has an action attached, metadata carries it in machine-readable form rather than only in the prose.
{
"error": {
"message": "model 'anthropic/claude-opus-5' is not in this key's allow-list.",
"type": "permission_error",
"code": "model_not_allowed",
"param": null,
"request_id": "3c48e2b6-1d0e-4f7a-9c31-8e6b2f5a4d17",
"metadata": {
"model": "anthropic/claude-opus-5"
}
}
}| HTTP | code | type | When |
|---|---|---|---|
| 400 | validation_failed | invalid_request_error | The body did not validate. Field paths and reasons only — we never echo your prompt back in an error. |
| 400 | modality_mismatch | invalid_request_error | The model named cannot serve this endpoint — a chat model sent to /v1/embeddings, or an embedding model to /v1/chat/completions. metadata carries the model and the modality it actually has. Nothing about your key is wrong; name a model that does this job. |
| 401 | invalid_key | authentication_error | Missing, malformed or revoked key. |
| 402 | insufficient_credits | insufficient_quota | The prepaid balance cannot cover the reservation. Top up; nothing is served on credit. |
| 403 | model_not_allowed | permission_error | The key's own allow-list does not include this model. |
| 403 | suspended | permission_error | The tenant is suspended. |
| 403 | moderation_blocked | permission_error | Refused by moderation policy. |
| 404 | not_found | invalid_request_error | No such slug in the catalog, or no such generation id for this tenant. |
| 405 | method_not_allowed | invalid_request_error | Right path, wrong verb — the completion routes are POST and the reference routes are GET. |
| 422 | egress_blocked | invalid_request_error | Only with a privacy mode enabled: the request would have sent raw PII to a provider. |
| 429 | rate_limited | rate_limit_error | Over the effective rate limit. Carries Retry-After. |
| 500 | internal_error | api_error | We failed in a way we did not anticipate. The body says nothing else on purpose — a path, a key or a payload in an error is a leak — but the failure is counted and logged on our side. Safe to retry. |
| 503 | provider_paused | api_error | The upstream is paused, usually on a spend cap. Retry or steer with provider.order. |
| 503 | jetrouter_unavailable | api_error | Two different situations, and the metadata tells you which — they need opposite responses from you. metadata.provider_reached false, or no metadata.upstream_status: nothing left our side. A component the request needs is down, or no credential exists for the provider, and we fail closed rather than degrade quietly — retry. metadata.upstream_status 403 or 451: the provider answered and refused this specific model on authorisation, region or its own terms. That is a decision, not an outage — retrying will not change it, so choose another model. Nothing is billed in either case: across 214 live refusals the total charged is exactly 0. |
Reference
Prepaid, metered per token in US dollars, settled after the response from what the provider actually reported.
Migrating
Both are a base URL change. Neither needs your request bodies rewritten.