API reference
BatchRouter API reference — base URL, bearer auth, the interactive Scalar reference, the raw OpenAPI spec, and a summary of every public /v1 endpoint.
The BatchRouter API is a single REST surface for routing batch-AI workloads across providers: get a quote, create a batch, then poll or receive results. This page is the reference hub — it covers the base URL and auth, links to the interactive reference and raw spec, and summarizes every public endpoint.
Base URL and auth
All public endpoints live under /v1.
| Environment | Base URL |
|---|---|
| Production | https://api.batchrouter.com |
| Test / staging | https://test.api.batchrouter.com |
Authenticate by sending your API key as a bearer token on every request:
curl https://api.batchrouter.com/v1/auth/account \
-H "Authorization: Bearer $BATCHROUTER_API_KEY"Keys start with br_live_ (legacy ob_live_ keys still work) and are shown only once at creation. Create one from the dashboard or via POST /v1/auth/account/api-keys, or get an org and key in a single call with POST /v1/auth/agent-register. Keep keys server-side. See Authentication for the full flow.
Public catalog, provider, and pricing endpoints (GET /v1/catalog/models, GET /v1/providers, GET /v1/pricing/fees) require no authentication — you can call them before you have a key.
Interactive reference and spec
The interactive reference (Scalar) is generated directly from the live OpenAPI spec, so it is always current — when an endpoint, field, or response shape changes, the reference reflects it immediately. Treat it as the authoritative contract; the summary below is a map, not a substitute.
Interactive API reference
Browse and try every endpoint live, with schemas and examples.
Raw OpenAPI spec
The machine-readable OpenAPI 3.1 document — feed it to your codegen or client.
The interactive reference and the raw spec are always in sync with production. If anything here disagrees with them, trust the spec.
Endpoint summary
A compact map of the public endpoints. "Auth" shows whether a request needs your bearer key. Path parameters use {braces}.
Quotes, files, and batches
| Method | Path | Purpose | Auth |
|---|---|---|---|
POST | /v1/quotes/model | Get a free cost estimate and routing lanes before dispatching | Bearer |
POST | /v1/files | Upload a file (large JSONL or binary input) for use in batch items | Bearer |
POST | /v1/batches | Create a batch (inline items or input_file_id); send an Idempotency-Key | Bearer |
GET | /v1/batches/{batchId} | Poll a batch's status (?include_billing_receipt=true optional) | Bearer |
GET | /v1/batches/{batchId}/results | Page through per-item results (?limit, ?cursor) | Bearer |
GET | /v1/batches/{batchId}/artifact-url | Get a signed URL to download all results (preferred for large batches) | Bearer |
Chat completions
| Method | Path | Purpose | Auth |
|---|---|---|---|
POST | /v1/chat/completions | A single chat request: answered directly (stream: true for SSE), or queued as a one-item batch with batch | Bearer |
GET | /v1/chat/completions/{id} | Poll a queued chat job; result holds the chat.completion when done | Bearer |
See Chat completions.
Catalog and pricing (public)
| Method | Path | Purpose | Auth |
|---|---|---|---|
GET | /v1/catalog/models | List models with per-provider pricing, capacity, regions, retention, and tools | None |
GET | /v1/pricing/fees | Read the public fee schedule | None |
Account and billing
| Method | Path | Purpose | Auth |
|---|---|---|---|
GET | /v1/auth/account | Read account details, including credit_balance | Bearer |
POST | /v1/auth/account/api-keys | Create an API key (value shown once) | Bearer |
POST | /v1/auth/agent-register | Register an org agent-first, no email — returns org_id + key once | None |
PUT | /v1/auth/account/delivery-webhook | Set the org-level default delivery webhook | Bearer |
There is no API endpoint for purchasing credits. Add credits from the billing dashboard; the API then settles batch costs against your balance. Check the current balance with GET /v1/auth/account → credit_balance.
Operator, admin, and provider-partner routes are gated behind admin authentication and are intentionally excluded from the public spec. If you don't see an endpoint in the interactive reference, it isn't part of the public API.
OpenAI compatibility
BatchRouter also exposes an OpenAI-Batch-compatible surface: point your existing OpenAI batch client's base URL at BatchRouter and use a br_live_ key. BatchRouter is a routing and aggregation layer, not a passthrough — your batch is quoted, routed across lanes, and delivered through the same pipeline as a native batch. See the OpenAI compatibility guide for the exact paths and client setup.
Errors
Errors use standard HTTP status codes with a JSON error body.
| Status | Meaning | What to do |
|---|---|---|
400 | Validation failed (see error.details.preflight — bad JSONL, unsupported file type, context window exceeded, unsafe webhook URL) | Fix the input and retry |
401 / 403 | Missing, invalid, or unauthorized key | Check your Authorization header |
402 | Insufficient credits | Check GET /v1/auth/account → credit_balance; add credits from the billing dashboard |