Skip to content
Collab with Anthropic and OpenAI
NovaRouter
The API

Three lines to switch providers. Zero to switch back.

NovaRouter accepts the core OpenAI chat, responses and embeddings shapes. Provider routing and failover happen on the server, while your client keeps one base URL.

import OpenAI from "openai"; const nova = new OpenAI({  baseURL: "https://nova-router-main.vercel.app/api/v1",  apiKey: process.env.NOVAROUTER_API_KEY,}); const stream = await nova.chat.completions.create({  model: "claude-sonnet-5",  messages: [{ role: "user", content: "Summarise this changelog." }],  stream: true,}); for await (const chunk of stream) {  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");}
OpenAI SDKVercel AI SDKLangChainLlamaIndexRaw HTTP

Ordered routing

Each model alias declares an ordered chain of upstreams. The first that answers serves the request; a rate limit or 5xx moves to the next.

Failover without a retry

Transient upstream failures move to the next candidate in the chain automatically — no retry logic in your code.

Drop-in compatible

Point the OpenAI SDK at our base URL. No new client, no rewritten call sites.

Request metering

Every request records tokens, latency, status and the public model alias for your usage dashboard.

Scoped API keys

Restrict each key to specific endpoints and model aliases, then pause or revoke it immediately.

Auditable failover

Each upstream attempt is recorded privately so operators can diagnose retries without exposing routing details.

CLI integrations

One gateway. Two protocol contracts.

Claude Code speaks Anthropic Messages. Codex speaks OpenAI Responses. Pick the lane you use and copy the configuration exactly — especially the base URL.

Claude Code math
https://nova-router-main.vercel.app/api+/v1/messages

Claude Code appends the Messages path. Stop the configured URL at /api.

Codex math
https://nova-router-main.vercel.app/api/v1+/responses

Codex uses the Responses wire API. Its configured base ends at /api/v1.

  1. 01

    Create a NovaRouter API key

    In the dashboard, open API Keys, issue a key with the chat.completions scope, and copy it once. Claude Code reaches /api/v1/messages, but NovaRouter intentionally authorizes that surface with the same chat scope.

  2. 02

    Choose where the configuration lives

    All projects
    macOS: ~/.claude/settings.json
    Windows: %USERPROFILE%\.claude\settings.json
    One project
    .claude/settings.local.json

    Keep it gitignored. Never put a key in the committed .claude/settings.json.

    settings.json
    {
  "env": {
    "ANTHROPIC_BASE_URL": "https://nova-router-main.vercel.app/api",
    "ANTHROPIC_AUTH_TOKEN": "nr_sk_your_key",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "fable-5"
  }
}
    Why AUTH_TOKEN? NovaRouter accepts Authorization: Bearer nr_sk_…. Claude Code sends ANTHROPIC_AUTH_TOKEN in exactly that header. ANTHROPIC_API_KEY uses x-api-key; NovaRouter accepts it too, but bearer avoids Claude Code's one-time custom-key approval prompt.
  3. 03

    Try it on macOS before saving it

    Open Terminal. These exports last only for this window, which makes them the safest first test.

    macOS · zsh
    export ANTHROPIC_BASE_URL="https://nova-router-main.vercel.app/api"
export ANTHROPIC_AUTH_TOKEN="nr_sk_your_key"
export ANTHROPIC_MODEL="claude-sonnet-5"
claude

    After it works, use the settings file above rather than putting the key in ~/.zshrc. Settings also reach Claude Code background agents reliably.

  4. 04

    Try it on Windows before saving it

    Open PowerShell. The variables last for this PowerShell window and every process started from it.

    Windows · PowerShell
    $env:ANTHROPIC_BASE_URL = "https://nova-router-main.vercel.app/api"
$env:ANTHROPIC_AUTH_TOKEN = "nr_sk_your_key"
$env:ANTHROPIC_MODEL = "claude-sonnet-5"
claude

    For persistence, use %USERPROFILE%\.claude\settings.json. It works for PowerShell, Command Prompt, VS Code terminals, and background agents without maintaining four separate environment setups.

  5. 05

    Verify the route, then verify Claude Code

    Test NovaRouter directly first. A JSON response beginning with msg_ proves the URL and token are correct.

    Direct Messages test
    curl -X POST "https://nova-router-main.vercel.app/api/v1/messages" \
  -H "Authorization: Bearer $NOVAROUTER_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":8,"messages":[{"role":"user","content":"Say OK"}]}'

    Start claude, send a message, then run /status. The Status tab must show:

    • Anthropic base URL: https://nova-router-main.vercel.app/api
    • Auth token: ANTHROPIC_AUTH_TOKEN
    Do not configure /api/v1 here. Claude Code appends /v1/messages. If you set ANTHROPIC_BASE_URL to https://nova-router-main.vercel.app/api/v1, it requests /api/v1/v1/messages and gets 404.

Fix the symptom, not the config twice

The error tells you which layer failed.

401 / invalid keyThe credential is missing, revoked, or sent in the wrong header.Claude Code: use ANTHROPIC_AUTH_TOKEN. Codex: confirm NOVAROUTER_API_KEY exists in the shell.
404 / route not foundThe base URL includes one path segment too many.Claude Code uses https://nova-router-main.vercel.app/api; Codex uses https://nova-router-main.vercel.app/api/v1.
Model not foundThe key allowlist excludes the selected alias, or the model name is wrong.Copy an alias from /models and add it to the key's model allowlist.
Claude Code opens loginA project settings file loads after first-run, so no credential existed at startup.Put the env block in ~/.claude/settings.json, or export the variables before launching.
Codex ignores providerThe custom provider was placed in project config.Move it to ~/.codex/config.toml; provider definitions are machine-local.
Stream starts, then stopsEvery upstream failed after the first byte, when failover can no longer restart safely.Open Dashboard → Logs and inspect the request id returned in X-NovaRouter-Request.
Documentation

Docs written by the people who run the gateway

Copy-pasteable examples and honest caveats. Every endpoint listed below has a route handler behind it.

Quickstart

Point the OpenAI SDK at the NovaRouter base URL, set your key, and send a request. Nothing else changes.

Claude Code and Codex

Configuration files, exact base URLs and macOS and Windows setup for both agent CLIs — written out above on this page.

Scoped keys

Issue `nr_sk_…` keys per environment and restrict any of them to specific models. Up to 25 live keys per account.

Streaming

Server-sent events on every model, with failover before the first byte so a dead upstream costs latency rather than the request.

Ordered fallback

Each alias declares its own chain across five providers. A rate limit or 5xx moves to the next candidate with no retry in your code.

Usage and rollups

Every request is logged with tokens, latency and status — queryable per key or per model. Metering, not billing.

Setting up a CLI?

Claude Code and Codex each need a different base URL. Both are written out, with macOS and Windows steps.

Configure a CLI