Documentation

Collections

A collection is a named, versioned fallback chain for one catalog model — a tested sequence of { model, provider }steps you can publish, share, and import. Think of it as a routing recipe: "forllama-3.1-8b-instruct, try my own GPU first, then Krutrim, then OpenRouter." Collections carry steps and a README only — never API keys.

Public registry

Anyone — human or agent — can browse published collections; no auth needed.

Endpoint	Returns
`GET /v1/collections`	Public registry, top 200 by stars then recency.
`GET /v1/collections/:slug`	One collection with its version history.

Fork-before-use

When you import a collection that belongs to another org, BharatRouter first forks it — taking a private snapshot into your org — and then applies that snapshot. The lineage (forked_from) is kept, but the original author's later edits never silently change your routing. Importing your own collection applies it directly, no fork. An existing fork is reused rather than duplicated.

Import → your routing

Importing sets the collection's steps as your org's saved fallback chain for that model, effective within a minute. From then on, requests for that model follow the chain (a per-request fallbacks array still wins for a single call).

POST /me/collections/import/india-first-llama
→ { "ok": true, "model": "llama-3.1-8b-instruct",
    "steps": [ {"model":"llama-3.1-8b-instruct","provider":"bharatrouter"},
               {"model":"llama-3.1-8b-instruct","provider":"krutrim"} ],
    "forked_as": "india-first-llama-2" }

If a step references a BYOK model (provider/model-id) or a BYOE endpoint (byoe:<slug>), it resolves only once your org has that key saved or that endpoint registered — unresolved steps are skipped at request time, exactly like an empty link in the chain.

Creating & managing

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

Members can star and fork; only owners and admins create, edit, delete, or import. Limits: up to 50 collections per org, README up to 20,000 characters, names up to 80 characters. Slugs are auto-generated and collision-suffixed within your org.

Reliability monitoring

Any collection can be marked monitored: BharatRouter then canaries every step on a schedule and tracks per-step uptime and p95 latency, with email/webhook alerts on error rate or latency. See Reliability monitoring.

From agents (MCP)

Agents get the same surface over MCP: list_collections(read) and import_collection (write — requires user_confirmed: true, fork-before-use applies).