Hosted API reference

OpenAI-compatible routing with Sage Router accounts.

Use one hosted base URL, generated sk_sage_* keys, route profiles such as sage-router/frontier, and public model discovery without opening anonymous model traffic.

Create API key Quickstart Gateway migration Troubleshooting Model catalog Pricing

Hosted API base URL: https://api.sagerouter.dev/v1. Browser account and billing UI live at https://app.sagerouter.dev.

Auth

Bearer key

Send Authorization: Bearer sk_sage_.... Generated keys are scoped to a Sage Router account and should be rotated from the account page if exposed.

OpenAI

Drop-in clients

Point OpenAI-compatible SDKs and tools at https://api.sagerouter.dev/v1. Use sage-router/frontier as the first route profile, or sage-router/fusion on Pro/Max for judged multi-model synthesis.

Limits

Quota aware

Plans enforce monthly request quotas and request-per-minute limits. Responses include safe quota and rate-limit headers for client backoff.

Client setup

Use OpenAI SDK configuration.

export OPENAI_BASE_URL=https://api.sagerouter.dev/v1
export OPENAI_API_KEY=sk_sage_your_key_here

curl "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "User-Agent: OpenAI-compatible-client/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sage-router/frontier",
    "messages": [{"role": "user", "content": "Return ok."}]
  }'

Standard SDKs such as OpenAI Python/JavaScript reach the edge auth gate. Raw HTTP stacks that trigger Cloudflare 1010 should set a descriptive User-Agent.

Endpoint	Auth	Purpose	Notes
`GET /v1/models`	Generated key	Authenticated model list for OpenAI-compatible clients.	Use this to verify keys before wiring agents. Anonymous requests return guided `401`.
`POST /v1/chat/completions`	Generated key	OpenAI-compatible chat completions with routing profiles and provider fallback.	Supports common chat client flows, including streaming-shaped compatibility responses. `sage-router/fusion` is a premium chat model alias, and `{"type":"sage-router:fusion"}` is accepted as a premium server tool for Pro/Max-style synthesis.
`POST /v1/responses`	Generated key	OpenAI Responses-compatible shape for Codex and agent harnesses that use Responses wiring.	Codex profiles should set `wire_api = "responses"`.
`GET /model-catalog`	Public metadata	gateway-style discovery metadata for route families and model catalog pages.	Discovery only. Live `/v1/models` and model traffic still require an active generated key.
`GET /pricing`	Public metadata	Hosted plans, limits, API base URL, checkout path, and public launch boundary.	Managed provider access remains disabled unless provider resale controls, durable quotas, and durable operator audit events are explicitly ready.

Responses API

Use Responses wiring for Codex-style clients.

curl https://api.sagerouter.dev/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sage-router/frontier",
    "input": "Return one sentence about Sage Router."
  }'

Signal	Header or field	When to use it
Authentication	`WWW-Authenticate`, `apiKeyPrefix`, `accountUrl`	Diagnose missing, inactive, malformed, or revoked generated keys.
Billing or quota	`X-Quota-Limit`, `X-Quota-Used`, `X-Quota-Remaining`, `X-Quota-Period`, `X-Quota-Reset`, `upgradeUrl`, `billingUrl`, `supportUrl`	Show plan usage, monthly reset timing, and safe recovery links without exposing prompts or generated keys.
Rate limit	`Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`	Back off safely when clients exceed request-per-minute limits.
Reliability	`X-Sage-Router-Retry-Count`, status page health, selected upstream	Understand failover behavior when a backend returns `401`, `429`, `502`, `503`, or `504`.

Boundary

The hosted API is authenticated and customer-authorized.

Anonymous /v1/* model traffic is blocked with guided onboarding errors.
Sage Router does not grant unauthorized provider access or pool personal provider accounts by default.
Do not send prompts, provider credentials, OAuth tokens, generated keys, private keys, session cookies, raw provider responses, or customer data in support requests.