Guides

Onboard an agent

Give an agent a key, a base URL and a model. It sends its first request in minutes.

Any agent that speaks the OpenAI or Anthropic API works. Point it at https://api.minirouter.sh/v1 and give it its own key. Agents that read setup files can fetch /agents.md.

1. Get a key

Create a key, save the key and dashboard link, then add credits. Already have an account? Create a key per agent in Keys.

2. Set the environment

Put the key where the agent runs. Most agents read the OpenAI variables.

.env

MINIROUTER_KEY=mr-live-YOUR-KEY-HERE
OPENAI_BASE_URL=https://api.minirouter.sh/v1
OPENAI_API_KEY=mr-live-YOUR-KEY-HERE

3. Pick a model

Use an exact author/name ID from the catalog, or let minirouter/auto choose. The list is public.

Terminal

curl https://api.minirouter.sh/v1/models

4. Send a first request

Terminal

curl https://api.minirouter.sh/v1/chat/completions \
  -H "Authorization: Bearer $MINIROUTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "openai/gpt-5.6-luna",
  "messages": [
    {
      "role": "user",
      "content": "Reply with: ready"
    }
  ],
  "max_tokens": 64
}'

A 200 with ready means the agent is connected. The request appears in Request logs.

Working example

Send one request and print the reply, the model that answered, its cost and your balance.

Python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.minirouter.sh/v1",
    api_key=os.environ["MINIROUTER_KEY"],
)

raw = client.chat.completions.with_raw_response.create(
    model="openai/gpt-5.6-luna",
    messages=[{"role": "user", "content": "Reply with: ready"}],
    max_tokens=64,
)
completion = raw.parse()
print(completion.choices[0].message.content)
print("model:", raw.headers["x-minirouter-model"])
print("cost USD:", raw.headers["x-minirouter-cost-usd"])
print("balance USD:", raw.headers["x-minirouter-balance-usd"])

Needs pip install openai.

TypeScript

const key = process.env.MINIROUTER_KEY;
if (!key) throw new Error("Set MINIROUTER_KEY");

const res = await fetch("https://api.minirouter.sh/v1/chat/completions", {
  method: "POST",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "openai/gpt-5.6-luna",
    messages: [{ role: "user", content: "Reply with: ready" }],
    max_tokens: 64,
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);

console.log(body.choices[0].message.content);
console.log("model:", res.headers.get("x-minirouter-model"));
console.log("cost USD:", res.headers.get("x-minirouter-cost-usd"));
console.log("balance USD:", res.headers.get("x-minirouter-balance-usd"));

No dependencies. Run with Node.js 20 or later as an .mjs file.

Terminal

curl https://api.minirouter.sh/v1/chat/completions \
  -H "Authorization: Bearer $MINIROUTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "openai/gpt-5.6-luna",
  "messages": [
    {
      "role": "user",
      "content": "Reply with: ready"
    }
  ],
  "max_tokens": 64
}'

Using a coding agent? Its exact settings are in Integrations.

Keep the key safe

One key per agentRevoke one agent without breaking the rest.
Environment onlyNever in prompts, code, logs or repositories.
Set an expiry7, 30 or 90 days, or an exact date.
Rotate on exposureThe old key works for 24 hours, then stops.

Usage and billing controls

Set limits on each key before an agent runs unattended.

dailyLimitNano: Daily spend cap. Over it returns 403 spend_limit_exceeded.
monthlyLimitNano: Monthly spend cap.
rpmLimit: Requests per minute.
tpmLimit: Tokens per minute.
allowedModels: Models this key may call.

Edit them in Keys. For budgets and model or provider rules across keys, assign a guardrail. See rate limits.

x-minirouter-cost-usd: Charge for this request. Streams report usage.cost in the final chunk.
x-minirouter-balance-usd: Remaining balance.
x-minirouter-model: Model that answered.
x-minirouter-request-id: Quote this to support.

Troubleshooting

401 invalid_api_key

The key is wrong, revoked or expired. Check for spaces or quotes around it, and that it starts with mr-live-.

402 insufficient_credits

The balance is below the request's estimated cost. Add credits or lower max_tokens.

403 spend_limit_exceeded

The key hit its spend cap. Wait for the reset in the error, or raise the cap in Keys.

404 unknown_model

Use the full ID: openai/gpt-5.6-luna, not gpt-5.6-luna. Fetch the model list for exact IDs.

400 No endpoint at …

The base URL is wrong. Use https://api.minirouter.sh/v1 exactly, without /chat/completions.

429 usage_limit_exceeded

Wait the seconds in Retry-After, or raise the key's request or token limit.

Free model refused

Accounts created by an agent cannot use Auto Free. Use a paid model.

Every error carries error.code and a link to its fix. Full list: errors.