API reference

Everything the gateway exposes, grouped by auth model. Inference endpoints take an API key (Authorization: Bearer br-…); dashboard endpoints use the browser session cookie set at sign-in and are listed here for completeness — most people use them through the dashboard UI. A machine-readable schema lives at openapi.json.

Inference (API key)

POST /v1/chat/completions

OpenAI-compatible chat completions, streaming and non-streaming. Accepts the four BharatRouter extensions (optimize, provider, data_policy, upstream_key) — they are consumed by the router and stripped before the request leaves the gateway. The provider that actually served the request is echoed in the x-br-provider response header.

curl https://api.bharatrouter.com/v1/chat/completions \
  -H "Authorization: Bearer br-..." -H "Content-Type: application/json" \
  -d '{
    "model": "krutrim-2",
    "messages": [
      {"role": "system", "content": "You answer in Hindi."},
      {"role": "user", "content": "What is the capital of Maharashtra?"}
    ],
    "max_tokens": 200,
    "optimize": "uptime"
  }'

Response (non-streaming) is a standard chat-completion object with token usage:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "krutrim-2",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "मुंबई ..." }, "finish_reason": "stop" }],
  "usage": { "prompt_tokens": 28, "completion_tokens": 41, "total_tokens": 69 }
}

With "stream": true the response is text/event-stream. The gateway injects stream_options.include_usage on providers that support it, so the final chunk before [DONE] carries the usage block.

POST /v1/embeddings

OpenAI-compatible embeddings with the same extensions, routing, and failover as chat.

curl https://api.bharatrouter.com/v1/embeddings \
  -H "Authorization: Bearer br-..." -H "Content-Type: application/json" \
  -d '{ "model": "bge-m3", "input": ["namaste", "vanakkam"], "data_policy": "india_only" }'

Audio

Self-hosted speech models — full guide on the Audio page.

Endpoint	What it does
`POST /v1/audio/transcriptions`	Speech → text (multipart, `whisper-large-v3`, ≤25 MB). Billed per minute of audio.
`POST /v1/audio/speech`	Text → speech (`kokoro-82m`, Hindi voices). Billed per 1M input characters.

Catalog & health (public, no auth)

Endpoint	Returns
`GET /v1/models`	The full catalog: per-model INR pricing (₹/Mtok), residency, language tags, context length, and live per-route health.
`GET /v1/models/:id/stats`	7-day traffic stats for one model — success rate, p50/p95 latency, tokens/sec.
`GET /v1/providers`	Provider registry: configured status, residency, BYOK support, platform-key fallback.
`GET /v1/pricing/compare`	Price comparison against OpenRouter, FX-converted to INR (cached hourly).
`GET /v1/rankings`	Most-used catalog models by token volume, 7-day and 30-day windows. See Usage.
`GET /v1/collections`	Public collections registry. `GET /v1/collections/:slug` for one with version history.
`GET /health`	Provider configuration plus per-route circuit-breaker state.

curl -s https://api.bharatrouter.com/v1/models | jq '.data[] | select(.id=="krutrim-2")'

Discovery (public)

`GET /openapi.json`	OpenAPI 3.1 schema.
`GET /llms.txt`	LLM-readable API summary.
`GET /.well-known/mcp/server-card.json`	MCP server metadata (streamable HTTP, bearer auth). See MCP for agents.

Dashboard API (session cookie)

Set by GitHub/Google OAuth at sign-in (GET /auth/:provider → callback → br_session cookie; POST /auth/logout clears it). Org owners can do everything; some endpoints are owner-only as marked.

Account

Endpoint	What it does
`GET /me`	Current user + org (id, email, role, org name, domain).
`PATCH /me`	Update display name or remove avatar.
`PATCH /me/org`	Rename the org (owner).

API keys

Full semantics on API keys & limits.

Endpoint	What it does
`GET /me/keys`	List keys: prefix, name, tier, rpm/daily limits, monthly ₹ budget, spend this month, last used.
`POST /me/keys`	Mint a key — `name?`, `budget_inr?`, `expires_days?` (1–365). The full key is shown exactly once. Max 5 active keys per org in beta.
`PATCH /me/keys/:id`	Update `rpm_limit`, `daily_limit`, `budget_inr` (owner/admin). Takes effect within 60 s.
`DELETE /me/keys/:id`	Revoke a key (owner/admin). Effective within 60 s.

BYOK keys

Full guide on the BYOK page.

Endpoint	What it does
`GET /me/byok`	Providers that accept BYOK + your saved keys (masked).
`PUT /me/byok/:provider`	Save or replace a provider key — `key`, `label?`, `always_use?` (owner). Verified live, encrypted at rest; models are discovered on save.
`POST /me/byok/:provider/test`	Re-verify a saved key: `ok` / `rejected` / `unreachable` (owner).
`GET /me/byok/:provider/models`	Models discovered with your key, addressable as `provider/model-id`.
`DELETE /me/byok/:provider`	Remove the saved key (owner).

Billing

Full semantics on Credits & billing.

Endpoint	What it does
`GET /me/billing`	Balance (₹), low-balance threshold, money-event ledger, payments, 30-day usage, billing address.
`POST /me/billing/address`	Set the billing address (required before the first top-up, for GST place-of-supply) (owner).
`GET /me/billing/pincode/:pin`	India Post PIN lookup → city/state autofill.
`POST /me/billing/orders`	Create a Razorpay order — `amount_inr` (whole ₹, 100–1000 in beta), `promo_code?` (owner).
`POST /me/billing/verify`	Verify checkout signature and credit the balance (idempotent) (owner).
`POST /me/billing/promo/check`	Validate a promo code before paying (owner).
`POST /me/billing/settings`	Set or clear the low-balance email threshold (₹) (owner).
`GET /me/billing/receipts/:paymentId`	Printable HTML payment receipt (owner).

Routing chains

Saved org-wide fallback chains — full guide on Routing.

Endpoint	What it does
`GET /me/routing`	List saved chains; `GET /me/routing/:model` for one.
`PUT /me/routing/:model`	Save/replace a model's chain — `steps` (1–10) (owner/admin).
`DELETE /me/routing/:model`	Remove it; routing returns to default (owner/admin).

Collections

Full guide on Collections.

Endpoint	What it does
`GET /me/collections`	Your org's collections (private + public + forked).
`POST /me/collections`	Create — `name`, `model`, `steps`, `readme_md?`, `public?` (owner/admin).
`PATCH /me/collections/:id` · `DELETE /me/collections/:id`	Edit (bumps version) or delete (owner/admin).
`POST /me/collections/star/:slug`	Toggle a star (one per org).
`POST /me/collections/fork/:slug`	Fork a public collection into your org.
`POST /me/collections/import/:slug`	Fork-if-foreign, then apply as your routing (owner/admin).

Custom endpoints (BYOE)

Full guide on Bring your own endpoint.

Endpoint	What it does
`GET /me/endpoints`	List registered endpoints (keys masked, with compliance status).
`POST /me/endpoints`	Register + compliance-test inline (owner/admin).
`POST /me/endpoints/test`	Compliance-test an unsaved config (no write).
`POST /me/endpoints/:id/retest` · `DELETE /me/endpoints/:id`	Re-test or remove (owner/admin).

Reliability monitoring

Full guide on Reliability monitoring.

Endpoint	What it does
`POST /me/collections/:slug/monitor`	Toggle monitoring on/off (`monitored`) (owner/admin).
`POST /me/collections/:slug/check`	Canary every step now and return fresh health.
`GET /me/collections/:slug/health`	Per-step uptime + p95 latency + last canary (`?days=` 1–90, default 7).
`GET/POST /me/collections/:slug/alerts` · `DELETE …/alerts/:id`	List, create or remove alerts on `error_rate`/`latency_p95` → email/webhook (owner/admin to mutate).

Teams & workspaces

Full guide on Teams & workspaces.

Endpoint	What it does
`GET /me/orgs` · `POST /me/orgs` · `POST /me/orgs/switch`	List orgs, create a team org, switch active org.
`GET /me/members` · `POST /me/members`	List members + pending; invite by email + role (owner/admin).
`PATCH /me/members/:id` · `DELETE /me/members/:id`	Change role (owner) · remove or leave.
`GET /me/invitations` · `POST /me/invitations/:id/(accept\|decline)`	Your invitations; accept or decline.
`GET/POST /me/workspaces` · `PATCH/DELETE /me/workspaces/:id`	List/create workspaces; `PATCH` renames or sets a `monthly_budget_inr` cap; `DELETE` archives (owner/admin to mutate).

Usage & activity

Full guide on Usage, activity & rankings.

Endpoint	What it does
`GET /me/usage`	Per-key requests and tokens, today (IST) and last 30 days.
`GET /me/usage/daily`	Last 30 days grouped by day and model — powers the dashboard chart.
`GET /me/activity`	Spend/volume aggregates over a date range — day×model, top models/keys, per-provider cost split.
`GET /me/activity/events`	Per-request drill-down, newest first, keyset-paginated.
`POST /me/attribution`	One-time "where did you hear about us?" signup survey.

Webhooks

Endpoint	Notes
`POST /webhooks/razorpay`	Razorpay events (`payment.captured`, `payment.failed`), verified via the `x-razorpay-signature` HMAC header. Crediting is idempotent across webhook and checkout-verify paths.

Response headers

Header	Meaning
`x-br-provider`	Provider that served the request (e.g. `krutrim`, `vllm`).
`retry-after`	On 429 responses: seconds to wait before retrying.

Platform limits

Limit	Value
Gateway rate limit	120 requests/min per key (or per IP when unauthenticated).
Trial keys	60 requests/min, 200 requests/day (resets midnight IST).
Active keys per org	5 (beta).
Top-up	₹100–₹1,000 per transaction (beta).

Per-key limits and monthly ₹ budgets are configurable — see API keys & limits. Errors use a single JSON envelope — see Errors.