# minirouter agent onboarding

You are configuring minirouter, an OpenAI-compatible LLM gateway. The
human-readable setup page is https://minirouter.sh/setup.

## Connection

- Base URL: https://api.minirouter.sh/v1
- API key environment variable: MINIROUTER_KEY
- Key format: mr-live-<26 base58>
- Model IDs: author/name, for example meta/llama-3.3-70b
- Model list: GET https://api.minirouter.sh/v1/models

Both https://api.minirouter.sh/v1 and https://api.minirouter.sh are accepted as base URLs. Do
not append /chat/completions in a client's base URL field; clients add the
endpoint themselves.

## Get a key

Check MINIROUTER_KEY in the environment. If it is absent, send the human to
https://minirouter.sh/key. No account is required, and the key is created
before payment. Save the API key and permanent dashboard link shown during
setup; the link preserves dashboard access if the key is lost or rotated.
Email or wallet sign-in at https://minirouter.sh/start adds personal recovery.

## Verify the connection

    curl https://api.minirouter.sh/v1/chat/completions \
      -H "Authorization: Bearer $MINIROUTER_KEY" \
      -H "Content-Type: application/json" \
      -d '{"model":"meta/llama-3.3-70b","messages":[{"role":"user","content":"ping"}]}'

## Configure a client

Use the client draft as a starting point, then confirm the field names against
the installed client version:
https://minirouter.sh/setup

Do not invent model IDs or shorten them. Fetch the current catalog when the
requested model is not known.

## Recovery

- 401 invalid_api_key: check or rotate the key.
- 402 insufficient_credits: ask the human to top up.
- 404 unknown_model: use the suggestion or fetch the model list.
- 429 rate_limited: wait for Retry-After before retrying.
- 503 model_unavailable: use one of the alternatives named in the response.

Full error reference: https://minirouter.sh/docs/errors.md

## Routing and cost

- Failover between hosts of the same model is automatic.
- To allow fallback to another model, send models as an ordered list of
  acceptable model IDs. minirouter never chooses outside that list.
- Response headers include x-minirouter-provider, x-minirouter-ttft-ms,
  x-minirouter-cost-usd and x-minirouter-balance-usd.
- 1,000 credits = $1.

## Documentation retrieval

- Index: https://minirouter.sh/llms.txt
- Full corpus: https://minirouter.sh/llms-full.txt
- Agent resources: https://minirouter.sh/docs/agent-resources.md
- Documentation MCP server: https://minirouter.sh/mcp
- Append .md to a docs or integration URL for clean Markdown.
- The same pages negotiate Markdown with Accept: text/markdown.