API reference

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.

Tip

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.

Note

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

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

Note

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.

Note

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

Next steps

Authentication

Submit a batch

Get a quote

Webhooks & delivery

Quickstart