API Overview
Routerly exposes two groups of HTTP endpoints:
| Group | Path prefix | Auth method | Purpose |
|---|---|---|---|
| LLM Proxy | /v1/* | Bearer router token | Forward requests to LLM providers |
| Management API | /api/* | Bearer JWT (dashboard session) | Configure models, routers, users, etc. |
Authentication
LLM Proxy (/v1/*)
Pass your router token as a Bearer token:
Authorization: Bearer sk-rt-YOUR_ROUTER_TOKEN
Router tokens start with sk-rt- and are created in the router's Tokens tab.
Management API (/api/*)
First obtain a JWT by logging in:
curl -X POST http://localhost:3000/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","password":"your-password"}'
Response:
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 86400
}
Then pass the JWT as a Bearer token:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
JWTs expire after 24 hours. Re-authenticate to get a new token.
Error Format
All errors return a JSON body:
{
"error": "error_code",
"message": "Human-readable description"
}
Common error codes:
| HTTP Status | error value | Meaning |
|---|---|---|
400 | validation_error | Request body is invalid |
401 | unauthorized | Missing or invalid token |
403 | forbidden | Valid token but insufficient permissions |
404 | not_found | Resource does not exist |
409 | conflict | Duplicate resource (e.g. slug already taken) |
503 | budget_exceeded | Request blocked by a budget limit |
503 | no_model_available | All routing candidates filtered out |
Request Tracing
Proxied responses carry no Routerly headers: the trace lives on the management API, not on the LLM wire.
- Live — send your own correlation id on the request
(
x-routerly-trace: <id>) and read the entries as they happen onGET /api/traces/stream?correlationId=<id>. - Afterwards — every request's trace is stored on its usage record and is visible in the Usage page or via the Usage API.
Health Check
GET /health
Unauthenticated. Returns 200 OK with:
{ "status": "ok", "version": "1.2.3" }
Suitable for load-balancer health probes.