Full endpoint surface
AIRouter exposes four endpoint families. Tenant API endpoints under/api/v1/* accept Authorization: Bearer air_sk_... and enforce per-key scopes. Auth endpoints under /api/auth/* proxy Lightbase and use HTTP-only cookies. Admin endpoints under /api/admin/* require a dashboard session (cookies) and an admin/owner role. Internal endpoints under/api/internal/* are HMAC-signed or triggered by Lightbase cron.
Common request conventions
- Authentication. All tenant API endpoints require
Authorization: Bearer air_sk_.... Auth and admin endpoints require the dashboard session cookiesair_access/air_refresh. - Content-Type. JSON endpoints accept
application/json. File endpoints acceptmultipart/form-data. Audio responses return binary passthrough with the upstreamContent-Type. - Streaming. Add
"stream": trueto chat / completions / messages / responses bodies. The response istext/event-streamwith OpenAI-shapedchat.completion.chunkevents. - Rate limiting. Per-key token bucket (per-minute) and per-day counter, both isolate-local with cache-miss enforcement via Lightbase. Default: 60 RPM, 10 000 RPD on the free plan.
- Errors. All errors return
{"error": {"code": "...", "message": "..."}}with the appropriate HTTP status (400, 401, 403, 404, 429, 500, 502, 503).
Tenant API — /api/v1/*
Bearer-authenticated tenant API. Scopes are enforced per key. A scope of * grants all.
| Path | Method | Required scope | Description |
|---|---|---|---|
/api/v1/chat/completions | POST | chat | OpenAI-shaped chat completions. Streaming (SSE) and non-streaming. Translates to Anthropic / Gemini / custom upstreams. |
/api/v1/completions | POST | chat | OpenAI legacy text completions (single prompt). Same routing pipeline as chat. |
/api/v1/messages | POST | chat | Anthropic Messages API shape. Accepts Anthropic-shaped bodies and translates to OpenAI / Gemini upstreams. |
/api/v1/responses | POST | chat | OpenAI Responses API shape (newer generation). Routes through the same pipeline. |
/api/v1/embeddings | POST | embeddings | Text embeddings (OpenAI shape). Routes to OpenAI, Jina, Cohere, Exa, or any embeddings-capable provider. |
/api/v1/images/generations | POST | images | Image generation (OpenAI shape). Routes to OpenAI DALL-E, Recraft, DeepInfra, AI Horde, etc. |
/api/v1/images/edits | POST | images | Image editing (multipart/form-data). Provider support depends on the chosen credential. |
/api/v1/images/variations | POST | images | Image variations (multipart/form-data). Provider support depends on the chosen credential. |
/api/v1/images/upscale | POST | images | Image upscaling. Currently supported by Recraft. |
/api/v1/audio/speech | POST | audio | Text-to-speech (OpenAI shape). Binary audio response passthrough. |
/api/v1/audio/transcriptions | POST | audio | Speech-to-text (Whisper shape, multipart/form-data). Routes to OpenAI Whisper, Groq Whisper, etc. |
/api/v1/audio/translations | POST | audio | Audio translation to English (Whisper shape). |
/api/v1/music/generations | POST | audio | Music generation. Routes to music-capable providers. |
/api/v1/videos/generations | POST | video | Async video generation. Returns a job id for polling. VeoAI Free and other async providers return v1-limited placeholders where polling is required. |
/api/v1/videos/:id | GET | video | Poll a video generation job by id. Returns the current status and the URL when ready. |
/api/v1/rerank | POST | rerank | Document reranking (Cohere/Jina shape). Routes to Cohere, Jina, or Together rerankers. |
/api/v1/moderations | POST | moderations | Content moderation (OpenAI shape). Routes to OpenAI or Cohere. |
/api/v1/models | GET | any | OpenAI-shape list of models the API key is allowed to route to (after allowedProviders / allowedModels filtering). |
/api/v1/providers | GET | public | Public provider catalog (37 active providers, no excluded providers). No authentication required. |
/api/v1/files | GET, POST | files | List uploaded files (GET) or upload a new file (POST, multipart/form-data). |
/api/v1/files/:id | GET, DELETE | files | Fetch a single file by id (GET) or delete it (DELETE). |
/api/v1/search | POST | search | Web search. Routes to Tavily, Exa, SerpAPI, or Jina. Response normalized to a search.completion shape. |
/api/v1/batches | POST | batches | Submit a batch processing job (OpenAI shape). |
/api/v1/batches/:id | GET | batches | Poll a batch processing job by id. |
Example request — chat completions
curl -X POST https://airouter-beta.pages.dev/api/v1/chat/completions -H "Authorization: Bearer air_sk_..." -H "Content-Type: application/json" -d '{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "Hello"}],
"stream": false
}'Example response — chat completions
{
"id": "chatcmpl-...",
"object": "chat.completion",
"model": "openai/gpt-4o-mini",
"choices": [
{"index": 0, "message": {"role": "assistant", "content": "Hello!"}, "finish_reason": "stop"}
],
"usage": {"prompt_tokens": 9, "completion_tokens": 3, "total_tokens": 12}
}Auth — /api/auth/*
Lightbase-backed. Sets HTTP-only, Secure, SameSite=Lax cookies on signup and login.
| Path | Method | Auth | Description |
|---|---|---|---|
/api/auth/signup | POST | public | Create an account. Bootstraps user, organization, membership, subscription, system_settings. Sets HTTP-only cookies. |
/api/auth/login | POST | public | Login. Supports optional MFA via the mfaCode field. Sets HTTP-only cookies. |
/api/auth/logout | POST | session | Clears the air_access and air_refresh cookies. Best-effort; Lightbase tokens are not revoked server-side in v1. |
/api/auth/me | GET | session | Returns the current Lightbase user, the AIRouter user record, the membership, and the org context. Requires the air_access cookie. |
Example request — signup
curl -X POST https://airouter-beta.pages.dev/api/auth/signup -H "Content-Type: application/json" -d '{"email":"you@example.com","password":"your-password","name":"Your Name"}'Example response — signup
{
"user": {
"id": "usr_...",
"email": "you@example.com",
"name": "Your Name",
"orgId": "org_..."
},
"accessToken": "eyJhbGciOi...",
"refreshToken": "eyJhbGciOi..."
}Admin — /api/admin/*
| Path | Method | Role | Description |
|---|---|---|---|
/api/admin/me | GET | admin | Returns the dashboard session user + org context. Used by the dashboard to gate admin routes. |
/api/admin/credentials | GET, POST | admin | GET: list provider credentials (credential field masked, last4 shown). POST: create a credential (admin role required). Triggers org cache invalidation. |
/api/admin/credentials/:id | PATCH, DELETE | admin | Update (label, priority, weight, enabled, extraConfig) or delete a credential. Both invalidate the org cache. |
/api/admin/routes | GET, POST | admin | GET: list routing rules ordered by priority. POST: create a routing rule (admin role required). |
/api/admin/routes/:id | PATCH, DELETE | admin | Update or delete a routing rule. Both invalidate the routing-rules cache for the org. |
/api/admin/keys | GET, POST | admin | GET: list tenant API keys (no secrets returned). POST: create a new key (returns the air_sk_... secret ONCE in key.secret). |
/api/admin/keys/:id | PATCH, DELETE | admin | PATCH: update label, scopes, allowedProviders, allowedModels, rate limits, enabled. DELETE: revoke the key. Both invalidate the API-key cache. |
/api/admin/usage | GET | admin | Returns usage aggregations for the org. Query params: ?days=7|30|90. Returns daily totals, by-provider, and by-endpoint breakdowns. |
Example request — create credential
curl -X POST https://airouter-beta.pages.dev/api/admin/credentials -H "Content-Type: application/json" -b "air_access=...; air_refresh=..." -d '{
"providerId": "openrouter",
"label": "OpenRouter free",
"credential": "sk-or-v1-...",
"priority": 100,
"weight": 1
}'Example request — create tenant API key
curl -X POST https://airouter-beta.pages.dev/api/admin/keys -H "Content-Type: application/json" -b "air_access=...; air_refresh=..." -d '{
"label": "production",
"scopes": ["chat", "embeddings"],
"allowedProviders": ["openrouter", "openai"],
"allowedModels": ["*"],
"rateLimitPerMin": 60,
"rateLimitPerDay": 10000
}'The response includes key.secret with the plaintext air_sk_.... It is shown only on creation.
Internal — /api/internal/*
Used by Lightbase cron and by admin-side cache invalidation. Not intended for tenant use.
| Path | Method | Auth | Description |
|---|---|---|---|
/api/internal/invalidate | POST | HMAC | HMAC-signed cache invalidation. Body: {orgId?, keyHash?, all?}. The X-AIRouter-Sig header must equal hex(HMAC-SHA256(body, CACHE_INVALIDATION_HMAC_KEY)). |
/api/internal/monthly-reset | POST | Lightbase cron | Called by the Lightbase cron on the 1st of each month UTC. Resets monthly requestCount / tokenCount / costUsd counters for every organization. |
/api/internal/health | GET | public | Liveness probe. Returns {ok: true} with a 200 status. No authentication required. |
Example request — cache invalidation
# Compute the HMAC signature:
SIG=$(printf '{"orgId":"org_abc"}' | openssl dgst -sha256 -hmac "$CACHE_INVALIDATION_HMAC_KEY" -hex | awk '{print $NF}')
curl -X POST https://airouter-beta.pages.dev/api/internal/invalidate -H "X-AIRouter-Sig: $SIG" -H "Content-Type: application/json" -d '{"orgId":"org_abc"}'Response: {"invalidated": "org:org_abc"}. Use {"all": true} to invalidate every cache, or {"keyHash": "..."} for a single API key.