# BharatRouter

> India's AI inference gateway. One API key for Indic (Krutrim, Sarvam,
> open-weight models) and global models, with India data-residency
> (`data_policy: india_only`) and routing preferences
> (`optimize: price|latency|uptime`) as first-class request fields.
> Wire format: standard chat-completions — existing SDKs work unchanged.

## API
- Base URL: https://api.bharatrouter.com/v1 (OpenAI wire format)
- Endpoints: POST /v1/chat/completions (streaming + non-streaming), POST /v1/embeddings,
  POST /v1/images/generations (text-to-image; BYOK — pass upstream_key or save a provider
  key; models sdxl/flux-1-schnell/gpt-image-1/qwen-image/cogview-4/… + best-of-N
  bharatrouter/image-sangam), POST /v1/audio/transcriptions, POST /v1/audio/speech (TTS);
  public: GET /v1/models, GET /v1/models/:id/stats
  (7d success/latency/tok-s), GET /v1/providers (registry + BYOK support),
  GET /v1/rankings (most-used models), GET /v1/pricing/compare (vs OpenRouter, INR),
  GET /v1/compare/models (model chooser: per-use-case rankings + measured TTFT/tok-s per route)
- Auth: Authorization: Bearer br-... (sign up at https://bharatrouter.com/login — GitHub or
  Google; a trial key is minted automatically and new orgs get a ₹100 signup credit)
- Spec (inference): https://api.bharatrouter.com/openapi.json
- Spec (management /me/*): https://api.bharatrouter.com/openapi-management.json
- Full single-fetch reference: https://bharatrouter.com/llms-full.txt
- Health: https://api.bharatrouter.com/health (no auth)

## Documentation (https://bharatrouter.com/docs)
- Quickstart (curl/Python/Node): https://bharatrouter.com/docs
- Full API reference: https://bharatrouter.com/docs/api-reference
- Routing, india_only residency & saved fallback chains: https://bharatrouter.com/docs/routing
- Collections (shareable routing chains): https://bharatrouter.com/docs/collections
- BYOE (bring your own endpoint): https://bharatrouter.com/docs/byoe
- API keys, rate limits, ₹ budgets: https://bharatrouter.com/docs/api-keys
- BYOK: https://bharatrouter.com/docs/byok
- Credits & billing (prepaid INR): https://bharatrouter.com/docs/billing
- Usage, activity & rankings: https://bharatrouter.com/docs/usage
- Teams & workspaces: https://bharatrouter.com/docs/teams
- Error codes & handling: https://bharatrouter.com/docs/errors
- MCP for agents: https://bharatrouter.com/docs/mcp

## Cookbook (https://bharatrouter.com/cookbook)
- Copy-paste, runnable recipes — cost optimisation, failover chains, india_only residency,
  DPDP/PII handling, BYOK, MCP agents (incl. wiring Claude Code), streaming costs, Sangam
  consensus. Each has Hindi (/hi) and Marathi (/mr) twins.
- Full machine-readable recipe index (titles, summaries, URLs): https://bharatrouter.com/llms-full.txt

## Request extensions (BharatRouter-specific, stripped before forwarding)
- optimize: "price" (default) | "latency" | "uptime" | "throughput" | "auto" — route-selection preference (throughput = favour routes with rate-limit headroom + low latency; auto = BharatRouter blends the tradeoff)
- optimize_weights: { price, latency, uptime, throughput } — explicit dials; weight the axes directly, overrides optimize (e.g. {"latency":1,"throughput":1,"price":0.2})
- provider: pin one provider (e.g. "vllm", "sarvam") and skip dynamic routing
- data_policy: "india_only" — only India-resident routes are eligible
- open_weights: true — only open-weight models (weights publicly downloadable); see openness in /v1/models
- permissive: true — only permissively-licensed models (Apache-2.0/MIT, no use restrictions); strict subset of open_weights
- upstream_key: per-request BYOK — your own provider key for this request
- Selected route is returned in the x-br-provider response header.

## BYOK (saved keys)
Orgs can save provider keys once (dashboard BYOK tab; AES-256-GCM at rest) instead of sending
upstream_key per request. Saved key is tried first with automatic fallback to platform keys
unless pinned "always use". BYOK requests are FREE during beta. 25+ BYOK-only providers.

## Fallback chains, collections & BYOE
- Saved fallback chains (PUT /me/routing/:model): ordered 1–10 {model, provider?} steps that
  replace a model's default routing org-wide; per-request "fallbacks" array overrides for one call.
- Collections (GET /v1/collections): shareable, versioned chains — star, fork-before-use, import.
- BYOE: register your own OpenAI-compatible endpoint (byoe:<slug>, ₹0), admitted only after an
  automated compliance test; SSRF-guarded.

## MCP server
- Endpoint: https://api.bharatrouter.com/mcp (streamable HTTP, Bearer br-... key)
- Inference tools: list_models, chat, health, create_ephemeral_key (mint scoped sub-agent keys)
- Read tools (org keys): get_balance, list_keys, list_byok_keys, get_fallback_chains,
  list_endpoints, test_endpoint, list_collections, create_topup_link
- Management tools (full-scope org keys only): save_byok_key, remove_byok_key, set_fallback_chain,
  clear_fallback_chain, register_endpoint, remove_endpoint, import_collection, set_key_budget
- Guardrail contract: write tools require user_confirmed=true — ask your human user for
  permission and show them what will change BEFORE calling. Agents can never move money:
  create_topup_link returns a dashboard URL the human reviews and pays.
- Ephemeral keys are scope 'inference' — they can call models but never manage the org.
- Card: https://api.bharatrouter.com/.well-known/mcp/server-card.json

## Status (machine-readable, hosted independently of the gateway)
- JSON: https://status.bharatrouter.com/api (operational/down, latency, 90d uptime)
- Use this for liveness — it stays up even if the gateway is down.

## Models
GET /v1/models returns the catalog with per-route INR pricing, residency,
language tags, and live health (latency EWMA, failure rate, availability).