Sandbox

The sandbox is a separate copy of the API for testing your integration. You get the same endpoints, request and response shapes, quotes and batch lifecycle as production, with three differences: every provider is simulated, nothing is charged, and the data is disposable.

Get a sandbox keyCopy Anchor Link

You need a Batchrouter account. The sandbox has no sign-up of its own.

1. Sign in at dash.batchrouter.com and open Settings.
2. In Sandbox keys, choose Create sandbox key, give it a name and a role, and copy the value. It is shown only once.

The same call is POST /v1/auth/account/sandbox-keys with the dashboard session of a workspace owner or admin, and it takes the same body as an API key. Sandbox keys are listed with GET /v1/auth/account/sandbox-keys and revoked with POST /v1/auth/account/sandbox-keys/{id}/revoke. A revoked key can keep working for up to a minute.

A sandbox key only works on the sandbox, and a production key only works on production. Using the wrong one returns 401.

Use itCopy Anchor Link

Send the sandbox key as a bearer token to the sandbox base URL. Everything else is the same as production:

curl https://sandbox.api.batchrouter.com/v1/quotes/model \
  -H "Authorization: Bearer $BATCHROUTER_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sla_tier": "standard",
    "routing_mode": "public_only",
    "privacy_tier": "standard",
    "allowed_regions": ["global"],
    "items": [
      {
        "customer_item_id": "a",
        "operation": "responses",
        "model": "gpt-4.1-mini",
        "input": { "input": [{ "role": "user", "content": "Say hello." }] }
      }
    ]
  }'

Quote first, then create the batch with the returned quote_id, exactly as in production. Quotes show what the work would cost; in the sandbox that price is never charged, and there is no credit balance to run out of.

Starter examplesCopy Anchor Link

The first time your organisation uses the sandbox it finds a few examples to work with, listed by the normal endpoints:

• Presets (GET /v1/presets): "Starter: summarise text (cheapest)", "Starter: extract fields as JSON" and "Starter: embed documents". Each preset's payload is a ready request body for POST /v1/quotes/model.
• A dataset (GET /v1/datasets): "Starter: support ticket triage (5 items)", five support tickets with the expected category and priority.
• An eval (GET /v1/evals): "Starter: ticket category and priority", which scores that dataset by exact match.

They are yours to edit or delete.

What is differentCopy Anchor Link

• Simulated providers. Results come from a simulation, not a model, so the content is placeholder text. Use the sandbox to test request shapes, polling, webhooks, files, errors and your result handling, not output quality.
• No account or money endpoints. Sign-up, sign-in, billing, provider portal and operator endpoints do not exist in the sandbox and answer 404. Manage your account and keys in production.
• Built-in models only. GET /v1/catalog/models lists the built-in models. Models from providers registered on the platform are not part of the sandbox.
• Bring-your-own-key and bucket delivery are off. Provider keys and delivery targets are not available there.
• Every response says so. Sandbox responses carry the header x-batchrouter-environment: sandbox.

If the sandbox cannot check your key because production is unreachable, it returns 503 with code sandbox_auth_unavailable. Retry shortly.

When you are readyCopy Anchor Link

Switch the base URL to https://api.batchrouter.com and the key to your br_live_… key. Nothing else in your integration changes.