API quickstart

Use Sage Router from any OpenAI-compatible client.

Create a hosted API key, set one base URL, and use Sage Router profiles such as sage-router/frontier without opening anonymous model traffic.

Copy setup first. Paste the bundle into your terminal now, then replace the placeholder with your generated sk_sage_* key after account setup. Create API key next

Start API key setup API reference Gateway migration Max implementation review Fusion Browse models Codex setup Troubleshoot API errors View pricing Check status

Live /v1/models requires an active generated sk_sage_* key. The primary setup path opens the hosted account page with Pro preselected, then verifies the generated key against the public edge.

1 minute

Create an API key

Open the hosted account page with Pro preselected, sign in, then generate an sk_sage_* key. Raw keys are shown once.

Base URL

Point your client

Use OPENAI_BASE_URL=https://api.sagerouter.dev/v1 and your generated key as OPENAI_API_KEY.

Profile

Pick a route

Start with sage-router/frontier, verify /v1/models, then send the first chat request. Pro/Max users can use sage-router/fusion for panel-plus-judge synthesis.

Environment

Set the OpenAI-compatible endpoint.

Environment

export OPENAI_BASE_URL=https://api.sagerouter.dev/v1
export OPENAI_API_KEY=sk_sage_your_key_here
export OPENAI_MODEL=sage-router/frontier

First request

Verify the key before wiring an agent.

Curl

curl https://api.sagerouter.dev/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sage-router/frontier",
    "messages": [
      {"role": "user", "content": "Reply with one sentence about Sage Router."}
    ]
  }'

JavaScript

OpenAI SDK

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: "https://api.sagerouter.dev/v1",
});

await client.chat.completions.create({
  model: "sage-router/frontier",
  messages: [{ role: "user", content: "Plan one launch task." }],
});

Python

OpenAI SDK

Python

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url="https://api.sagerouter.dev/v1",
)

client.chat.completions.create(
    model="sage-router/frontier",
    messages=[{"role": "user", "content": "Plan one launch task."}],
)

The OpenAI SDK sends a normal client User-Agent. If you use raw urllib or a custom HTTP stack and see Cloudflare 1010, set a descriptive User-Agent and retry.

Codex

Hosted profile

Codex

mkdir -p ~/.codex
cat >> ~/.codex/config.toml <<'TOML'
[model_providers.sage-router-hosted]
name = "Sage Router Hosted"
base_url = "https://api.sagerouter.dev/v1/"
env_key = "OPENAI_API_KEY"
wire_api = "responses"

[profiles.sage-router-frontier]
model_provider = "sage-router-hosted"
model = "sage-router/frontier"
TOML

export OPENAI_API_KEY=sk_sage_your_key_here
codex --profile sage-router-frontier

Read the dedicated Codex setup page for hosted, local port 8790, and Tailnet profiles.

Premium synthesis

Call Fusion when one answer is not enough.

On Pro, Max, metered, manual, or operator-enabled accounts, sage-router/fusion runs a small panel of eligible authorized routes, then asks a judge route to synthesize one final answer. Clients can request the model directly or attach {"type":"sage-router:fusion"} as a premium server tool. Lite keys receive 402 fusion_plan_required. Read the Fusion guide.

Curl

curl https://api.sagerouter.dev/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sage-router/fusion",
    "messages": [
      {"role": "user", "content": "Compare the strongest launch risks and give one recommendation."}
    ]
  }'

Server tool

curl https://api.sagerouter.dev/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sage-router/frontier",
    "messages": [
      {"role": "user", "content": "Survey the strongest arguments for and against this launch."}
    ],
    "tools": [{"type": "sage-router:fusion"}],
    "tool_choice": "required"
  }'

Status	Likely cause	Next action
401	Missing, revoked, or inactive `sk_sage_*` key.	Create or verify a hosted API key on the account page.
402	Plan, quota, or billing state blocks routing.	Choose a plan, finish checkout, or review current quota.
429	Request-per-minute limit or abuse control triggered.	Back off, reduce concurrency, or upgrade the plan limit.
503	No healthy authorized backend route is available.	Check public status, provider credentials, local router health, or fallback policy.

For safe diagnostics, response headers, and support context, read the dedicated API troubleshooting page.

Boundary

Hosted routing does not bypass provider authorization.

Sage Router sells routing, account management, quotas, analytics, and reliability infrastructure. Public plans route across customer-authorized provider access, local models, subscriptions, API keys, cloud accounts, or endpoints. Sage Router does not grant unauthorized model access, pool personal accounts, or override provider terms.