The router API

Send a conversation in the OpenAI-compatible message format. Set stream to true for server-sent events.

curl 'https://your-router-domain/v1/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "deepseek-v4-flash",
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ],
  "max_tokens": 128
}'

Response: OpenAI Chat Completion object with choices, usage and settled billing metadata. Stream ends with [DONE].

Send one string in prompt, or a single-element string array. The shared gateway applies the same key limits, automatic routing and billing. Responses use text_completion with choices[].text; streaming ends with [DONE]. echo: true includes your prompt once before the output.

curl 'https://your-router-domain/v1/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "deepseek-v4-flash",
  "prompt": "Hello!",
  "max_tokens": 128
}'

The output budget defaults to 128 tokens. Batched prompts, token IDs, multiple samples, legacy logprobs and suffix insertion are unsupported. Request history records the underlying Chat protocol.

curl 'https://your-router-domain/v1/responses' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "deepseek-v4-flash",
  "input": "Hello!",
  "store": false,
  "max_output_tokens": 128,
  "stream": true
}'

Response: Responses object; streamed settlement appears in the final response.completed or response.incomplete event.

curl 'https://your-router-domain/v1/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "deepseek-v4-flash",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ]
}'

Response: Anthropic Message shape with content blocks and usage. The final streamed message_delta contains settlement metadata. A matched stop_sequence is preserved in JSON and SSE; Chat conversions use finish_reason: stop.

curl "$ROUTER_BASE_URL/v1/uploads" \
  -H "Authorization: Bearer $ROUTER_API_KEY" \
  -F "file=@image.png;type=image/png"

Set ROUTER_BASE_URL to this deployment's origin without /v1. HTTP 201 returns id, bytes, content_type and expires_at. The ID is rtr_upload_ followed by 32 lowercase hexadecimal characters. Uploading does not call a model. The one-hour lifetime follows the reference's public DPA statement; this does not establish how its storage behaves at runtime.

Requires the same authentication as upload. Returns HTTP 204 without a body; invalid, expired, deleted and foreign IDs return 404. Deletion or expiry blocks new reads, while physical cleanup runs asynchronously. Bytes already downloaded by a provider cannot be recalled.

Requires an account:read key or a signed-in session. Returns zero_data_retention, updated_at and verified_zdr_capacity: false.

Only a same-origin signed-in browser session may change this setting. Send {"zero_data_retention": true} or false. API keys receive 403 session_required; malformed settings receive 400 invalid_data_protection. Manage it in the data protection settings.

Returns a models array of visible models with price-eligible configured supply. This does not guarantee credentials, health or capacity at inference time. Prices are decimal USD-per-million strings. No account data or internal serving-supplier identities are included.

GET /public/models
GET /public/models?zdr=true

Use an exact, case-sensitive canonical ID or a listed alias. Aliases with a slash are supported, and the response contains the canonical ID. IDs are not lowercased or trimmed. The optional zdr=true filter also applies here.

GET /public/models/deepseek-v4-flash

Success returns one model object. Unknown, hidden, unavailable or ZDR-excluded models return HTTP 404 with {"detail":"The model is not currently available."}. A catalog failure returns HTTP 503 with {"detail":"The catalog is temporarily unavailable."}. Both public endpoints use Cache-Control: public, max-age=0, must-revalidate.

Read model identifiers, current catalog prices, aliases, capability flags and context limits. Requires an API key.

curl 'https://your-router-domain/v1/models' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Requires usage:read. This read-only calculation uses configured customer catalog prices. It does not run inference or reserve supply.

curl 'https://your-router-domain/v1/models/compare?models=deepseek-v4-flash&prompt_tokens=1000&completion_tokens=250&requests=100' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Returns object: model.comparison, currency: USD, and data sorted by estimated billed_usd. Each found model includes input_per_m, output_per_m, list_usd, saved_usd and anonymous suppliers. Provider identifies the model maker; supplier entries show only Provider numbers and customer rates. List and savings estimates are null without a verified reference.

curl 'https://your-router-domain/v1/models/supply?model=deepseek-v4-flash&min_discount_percent=30' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Candidate counts describe current pricing. They are not a reservation, a health check or a guarantee of fulfillment.

Requires usage:read. Returns the latest change for each allowed model at or after since, including that timestamp. Initial observations are updated entries with null previous prices. Removed entries have a null model and null current price fields.

curl 'https://your-router-domain/v1/pricing/changes?since=2026-09-06T00%3A00%3A00Z&limit=100' \
  -H 'Authorization: Bearer YOUR_API_KEY'

The response includes data, has_more, next_cursor, pricing_version and pricing_updated_at. Entries contain model_id, change_type, changed_at, model, previous_pricing and current_pricing. Decimal prices are strings in USD per million tokens. This endpoint gives the latest change per model, rather than every intermediate observation.

Requires usage:read. Read model, request status, token usage, settled ledger cost and latency. Supplier identities stay private. Requests still in flight have status pending and no settled amount.

curl 'https://your-router-domain/v1/usage/requests?limit=25' \
  -H 'Authorization: Bearer YOUR_API_KEY'

New requests retain the published standard input/output token prices at admission. Settled requests compare those prices with the actual ledger charge. This baseline does not estimate cache savings or alternative models. Historical requests without a recorded price return null for provider_list_price_usd and savings_usd. A negative saving is preserved.

Requires usage:read. Returns a usage.daily summary and daily_spend rows, filling empty days with zeros. Failed and pending requests are counted separately; only settled ledger entries contribute to spend and billed tokens.

curl 'https://your-router-domain/v1/usage/daily?timezone_offset_minutes=480' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Requires account:read. Returns object: account, email, role, active_key_count, last_key_use_at and enabled_technique_count. Active keys are unrevoked and unexpired. A workspace key has a fixed organization_id; sessions can select it with the organization_id query parameter. Workspace reads identify the responsible member by email and platform role, and include workspace.id, workspace.name and workspace.role (owner or member). workspace_name is the actual name; funded_by_owner is true when the member differs from the wallet owner. Personal reads omit workspace metadata.

curl 'https://your-router-domain/v1/account' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Requires account:read. Returns object: account.balance, currency: USD, and numeric balance_usd, available_usd and reserved_usd from one balance snapshot. Workspace reads show the owner-funded wallet; auto-recharge is false and threshold_usd, recharge_amount_usd and card are null, keeping the owner's personal payment configuration private. Personal reads return the account's actual saved-card and auto-recharge state. Responses are not cached.

curl 'https://your-router-domain/v1/account/balance' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Requires account:read. The days parameter is an integer from 1 to 90, defaulting to 7. The response covers that many trailing 24-hour periods and includes request counts, settled spend and the five models with the highest spend. window_start is inclusive; window_end is exclusive. USD values are numbers, with exact integer values in amounts_nanos.

Savings use the published standard token prices recorded with each request. If any settled request lacks a price, list_usd, saved_usd and savings_percent are null; priced_request_count and savings_status describe that coverage. Savings can be negative.

curl 'https://your-router-domain/v1/account/usage?days=7' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Requires account:read. Returns 1-day, 7-day and 30-day usage windows with a shared end time, current techniques and up to 100 experiments. experiments_has_more indicates additional experiments. Experiment avg_saved remains null: a price comparison does not establish savings caused by a technique or experiment.

curl 'https://your-router-domain/v1/account/savings' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Requires account:read or a browser session. Returns object: list, data and available_events. available_events contains the nine supported event definitions as id, name and description; events contains each channel’s saved selection. Reading options does not subscribe a channel. A channel includes its id, platform, workspace_name, integration_active, report_frequency and report_hour in UTC. workspace_name labels the external destination, not a Router organization. integration_active reports configuration eligibility; Email also requires the matching verified address. This does not prove delivery.

curl 'https://your-router-domain/v1/channels' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Requires account:read or a browser session. Unknown, foreign or disconnected channels return 404.

Requires account:write or a same-origin browser session. Omitted fields stay unchanged. At least one field is required; an empty object is invalid. Recipient addresses and report hours cannot be set here.

{"report_frequency":"weekly","events":[]}

Requires account:write or a same-origin browser session. This is an explicit message action. No request body is needed. It summarizes the previous complete UTC day, Monday-based week or calendar month; off uses the previous day. Sending is limited to once per channel per minute and 20 times per UTC day, including admitted no-activity results and failed delivery attempts. Reconnecting does not reset these limits. Manual sending does not consume the next scheduled digest.

Returns object: channel.report, sent, cadence and window_label. A successful no-activity window returns sent: false with a message. Missing configuration returns 503. Provider acceptance is not proof of delivery to an inbox or that a person read the message. A limit returns 429 rate_limited with Retry-After; delivery retries return 503 report_pending. Terminal failures also return 503. An unknown acknowledgement is not automatically resent.

Router extension; browser session required. GET returns available, email_verified, email and channel. A same-origin POST requires consent: true and report_frequency; the destination is the account’s current verified email. No arbitrary to address is accepted. An unverified address returns 403 email_verification_required, and missing mail configuration returns 503 email_unavailable. First connection returns 201 with a Channel; an already connected identical configuration returns 200. API keys cannot connect an email channel.

Same-origin browser session required. Returns object: channel.disconnected and id. Disconnecting stops future eligible submissions; already submitted email cannot be recalled. There is no public /v1 channel-create or channel-delete operation.

This browser-only extension accepts slack, discord or telegram. GET returns available, channel and optional pending state. available means that connection configuration is present; a saved channel independently reports sending eligibility through integration_active. POST requires consent: true and return_to set to /dashboard/reports or /dashboard/notifications. It returns url, flow_id and expires_at.

Open the returned Slack or Discord authorization URL to select a destination. For Telegram, open the Bot link, press Start, then read connection status again. Confirm a ready recipient with POST /api/channels/telegram/confirm using flow_id and consent: true. Confirmation requires the same unexpired Router session that began the connection. Clients cannot submit a chat ID or webhook URL.

Connections start with the schedule Off and never send a test message. Use DELETE /api/channels/{platform}/{id} from the signed-in browser to disconnect. This cancels unsent work and clears the local credential; it does not delete a remote webhook or message.

Requires a valid API key with account:write, sent as a Bearer token or X-Api-Key. A browser session alone is insufficient. The customer completes payment on Stripe; this request does not charge or credit the wallet.

A successful response has object: billing.topup, amount_usd, checkout_url, session_id, min_usd: 5 and max_usd: 1000. checkout_url is the Stripe-hosted link. Success and cancel return URLs are set by the server; custom URLs are not supported.

curl "$ROUTER_BASE_URL/billing/topup" \
  -H "Authorization: Bearer $ROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: topup-example-0001' \
  -d '{"amount_usd":25.50}'

Set ROUTER_BASE_URL to your API base URL ending in /v1. Replace the example idempotency key for each new top-up intent.

Requires account:read. Returns object: list with data entries; use include_revoked=true to include revoked keys. Secrets and hashes are never returned.

curl 'https://your-router-domain/v1/keys' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Requires account:write. Returns object: api_key and a one-time key secret. A key caller can grant only its own scope subset and must have no policy restrictions. A signed-in session can create an independently restricted key.

Requires account:write. Self-revocation is allowed. Subsequent authentication with the revoked key fails.

Browser session and same-origin request required. Only included fields change; null clears a numeric limit or expiry, [] clears model/IP restrictions. Returns key metadata and policy without a secret.