Gateway migration

Move OpenAI-compatible clients to Sage Router.

Switch the base URL, use a generated sk_sage_* key, and start with sage-router/frontier. Sage Router keeps the OpenAI-compatible client shape while adding local-first BYOK routing, hosted account keys, Tailnet resilience, and explicit provider authorization boundaries.

Create hosted API key Quickstart API reference Compare gateways Check status

No provider key or credit card required until your generated sk_sage key exists.

Hosted Sage Router routes only authorized provider access, local models, customer subscriptions, API keys, cloud accounts, or endpoints. It does not grant unauthorized provider access, pool personal accounts, or bypass provider terms.

Existing gateway setupSage Router hosted setupMigration note
OPENAI_BASE_URL=https://gateway.example/api/v1 OPENAI_BASE_URL=https://api.sagerouter.dev/v1 Most OpenAI-compatible SDKs only need the base URL changed.
LEGACY_GATEWAY_API_KEY or a Bearer key OPENAI_API_KEY=sk_sage_your_key_here Generate the Sage Router key on the hosted account page. Raw keys are shown once.
Provider-prefixed model IDs from the hosted catalog Start with sage-router/frontier; use sage-router/fusion on Pro/Max for premium synthesis. Provider-specific routes remain available only when your Sage Router profile has authorized provider access configured. Fusion fans out across eligible authorized routes and returns one judged answer.
Gateway /models Public https://api.sagerouter.dev/model-catalog and authenticated GET /v1/models Discovery metadata is public; live model APIs still require an active generated key.

Before

Typical gateway environment.

export OPENAI_BASE_URL=https://gateway.example/api/v1
export OPENAI_API_KEY=$LEGACY_GATEWAY_API_KEY

After

Hosted Sage Router 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 routing before moving production traffic.

Use a small chat completion first, then move agents and job queues after the generated key, plan state, quota, and backend health are confirmed.

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 migration check."}
    ]
  }'
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: "Route this request." }],
});
Routes

Profile migration

  • Use sage-router/frontier for high-quality hosted agent work.
  • Use sage-router/fusion when Pro/Max prompts need a parallel panel plus judge synthesis. The dedicated Fusion page lives at /fusion.
  • Existing Fusion tool calls can keep {"type":"sage-router:fusion"}; Sage Router handles that server tool before downstream provider routing and applies the same Fusion plan gate.
  • Use sage-router/local when the router has local Ollama routes available.
  • Use model catalog discovery before mapping provider-specific IDs.
Safety

Provider boundary

Sage Router does not grant unauthorized provider access. Managed provider access is private beta only and requires provider authorization, margin policy, quotas, durable operator audit events, abuse controls, and acceptable-use enforcement before activation.

StatusLikely migration causeNext action
401Missing, inactive, malformed, or revoked generated key.Generate or rotate an sk_sage_* key on the account page.
402Checkout, subscription, plan, or monthly quota blocks model traffic.Finish checkout or choose an active hosted plan.
429Request-per-minute limit or burst control triggered.Back off, reduce concurrency, or move to a higher plan.
503No healthy authorized backend route is available.Check public status, Tailnet/router health, provider credentials, local Ollama, and fallback policy.

For response headers, safe probes, and no-secret support context, use API troubleshooting.

Cutover checklist

Move one client at a time.

  1. Create a hosted account and generated sk_sage_* key.
  2. Set OPENAI_BASE_URL=https://api.sagerouter.dev/v1 in one development client.
  3. Send a sage-router/frontier chat completion.
  4. Confirm usage, quota, and status before moving agent jobs.
  5. Keep existing gateway fallback in your deployment plan until Sage Router provider credentials and profiles are healthy.