API Reference

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 cookies air_access / air_refresh.
  • Content-Type. JSON endpoints accept application/json. File endpoints accept multipart/form-data. Audio responses return binary passthrough with the upstream Content-Type.
  • Streaming. Add "stream": true to chat / completions / messages / responses bodies. The response is text/event-stream with OpenAI-shaped chat.completion.chunk events.
  • 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.

PathMethodRequired scopeDescription
/api/v1/chat/completionsPOSTchatOpenAI-shaped chat completions. Streaming (SSE) and non-streaming. Translates to Anthropic / Gemini / custom upstreams.
/api/v1/completionsPOSTchatOpenAI legacy text completions (single prompt). Same routing pipeline as chat.
/api/v1/messagesPOSTchatAnthropic Messages API shape. Accepts Anthropic-shaped bodies and translates to OpenAI / Gemini upstreams.
/api/v1/responsesPOSTchatOpenAI Responses API shape (newer generation). Routes through the same pipeline.
/api/v1/embeddingsPOSTembeddingsText embeddings (OpenAI shape). Routes to OpenAI, Jina, Cohere, Exa, or any embeddings-capable provider.
/api/v1/images/generationsPOSTimagesImage generation (OpenAI shape). Routes to OpenAI DALL-E, Recraft, DeepInfra, AI Horde, etc.
/api/v1/images/editsPOSTimagesImage editing (multipart/form-data). Provider support depends on the chosen credential.
/api/v1/images/variationsPOSTimagesImage variations (multipart/form-data). Provider support depends on the chosen credential.
/api/v1/images/upscalePOSTimagesImage upscaling. Currently supported by Recraft.
/api/v1/audio/speechPOSTaudioText-to-speech (OpenAI shape). Binary audio response passthrough.
/api/v1/audio/transcriptionsPOSTaudioSpeech-to-text (Whisper shape, multipart/form-data). Routes to OpenAI Whisper, Groq Whisper, etc.
/api/v1/audio/translationsPOSTaudioAudio translation to English (Whisper shape).
/api/v1/music/generationsPOSTaudioMusic generation. Routes to music-capable providers.
/api/v1/videos/generationsPOSTvideoAsync 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/:idGETvideoPoll a video generation job by id. Returns the current status and the URL when ready.
/api/v1/rerankPOSTrerankDocument reranking (Cohere/Jina shape). Routes to Cohere, Jina, or Together rerankers.
/api/v1/moderationsPOSTmoderationsContent moderation (OpenAI shape). Routes to OpenAI or Cohere.
/api/v1/modelsGETanyOpenAI-shape list of models the API key is allowed to route to (after allowedProviders / allowedModels filtering).
/api/v1/providersGETpublicPublic provider catalog (37 active providers, no excluded providers). No authentication required.
/api/v1/filesGET, POSTfilesList uploaded files (GET) or upload a new file (POST, multipart/form-data).
/api/v1/files/:idGET, DELETEfilesFetch a single file by id (GET) or delete it (DELETE).
/api/v1/searchPOSTsearchWeb search. Routes to Tavily, Exa, SerpAPI, or Jina. Response normalized to a search.completion shape.
/api/v1/batchesPOSTbatchesSubmit a batch processing job (OpenAI shape).
/api/v1/batches/:idGETbatchesPoll 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.

PathMethodAuthDescription
/api/auth/signupPOSTpublicCreate an account. Bootstraps user, organization, membership, subscription, system_settings. Sets HTTP-only cookies.
/api/auth/loginPOSTpublicLogin. Supports optional MFA via the mfaCode field. Sets HTTP-only cookies.
/api/auth/logoutPOSTsessionClears the air_access and air_refresh cookies. Best-effort; Lightbase tokens are not revoked server-side in v1.
/api/auth/meGETsessionReturns 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/*

Dashboard session (cookies) required. Every admin endpoint verifies theair_access cookie against Lightbase, resolves the AIRouter user record, the membership, and the organization. Write operations additionally require anadmin or owner role.
PathMethodRoleDescription
/api/admin/meGETadminReturns the dashboard session user + org context. Used by the dashboard to gate admin routes.
/api/admin/credentialsGET, POSTadminGET: list provider credentials (credential field masked, last4 shown). POST: create a credential (admin role required). Triggers org cache invalidation.
/api/admin/credentials/:idPATCH, DELETEadminUpdate (label, priority, weight, enabled, extraConfig) or delete a credential. Both invalidate the org cache.
/api/admin/routesGET, POSTadminGET: list routing rules ordered by priority. POST: create a routing rule (admin role required).
/api/admin/routes/:idPATCH, DELETEadminUpdate or delete a routing rule. Both invalidate the routing-rules cache for the org.
/api/admin/keysGET, POSTadminGET: list tenant API keys (no secrets returned). POST: create a new key (returns the air_sk_... secret ONCE in key.secret).
/api/admin/keys/:idPATCH, DELETEadminPATCH: update label, scopes, allowedProviders, allowedModels, rate limits, enabled. DELETE: revoke the key. Both invalidate the API-key cache.
/api/admin/usageGETadminReturns 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.

PathMethodAuthDescription
/api/internal/invalidatePOSTHMACHMAC-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-resetPOSTLightbase cronCalled by the Lightbase cron on the 1st of each month UTC. Resets monthly requestCount / tokenCount / costUsd counters for every organization.
/api/internal/healthGETpublicLiveness 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.