Overview

Create and manage routing combos with 19 strategies (priority, weighted, round-robin, Auto-combo, and more). Configure fallback chains, test routing outcomes, and retrieve combo metrics.

Authentication

All requests require a valid Bearer token or session cookie. Obtain a token via POST /api/auth/login or configure REQUIRE_API_KEY=false for local development.

Endpoints

GET /api/combos

List routing combos

curl https://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

POST /api/combos

Create routing combo

curl -X POST https://localhost:20128/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /api/combos/{id}

Get combo by ID

curl https://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

PUT /api/combos/{id}

Update combo

Partial update: the body is merged onto the stored combo, so a field left out keeps its current value. An array that IS sent replaces the stored one outright.

curl -X PUT https://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

PATCH /api/combos/{id}

Update combo

Partial update: the body is merged onto the stored combo, so a field left out keeps its current value. An array that IS sent replaces the stored one outright.

curl -X PATCH https://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE /api/combos/{id}

Delete combo

curl -X DELETE https://localhost:20128/api/combos/{id} \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

GET /api/combos/metrics

Get combo metrics

curl https://localhost:20128/api/combos/metrics \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

POST /api/combos/test

Test a combo configuration

curl -X POST https://localhost:20128/api/combos/test \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /api/fallback/chains

List fallback chains

Returns all registered fallback chains for model routing.

curl https://localhost:20128/api/fallback/chains \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

POST /api/fallback/chains

Create fallback chain

Registers a fallback routing chain for a model.

curl -X POST https://localhost:20128/api/fallback/chains \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

DELETE /api/fallback/chains

Delete fallback chain

curl -X DELETE https://localhost:20128/api/fallback/chains \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

GET /api/combos/auto

GET combos › auto

curl https://localhost:20128/api/combos/auto \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

GET /api/combos/builder/options

GET combos › builder › options

curl https://localhost:20128/api/combos/builder/options \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN"

POST /api/combos/duplicate

POST combos › duplicate

curl -X POST https://localhost:20128/api/combos/duplicate \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

POST /api/combos/reorder

POST combos › reorder

curl -X POST https://localhost:20128/api/combos/reorder \
  -H "Authorization: Bearer $OMNIROUTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Payloads

See the full OpenAPI specification at GET /api/openapi/spec or docs/openapi.yaml for detailed request/response schemas.

OmniRoute — Routing & Combos

Requires OMNIROUTE_URL and OMNIROUTE_KEY. See entry-point SKILL for setup.

What is a combo?

A combo is a named group of providers/models with a routing strategy. All requests through a combo are automatically distributed, failed-over, and load-balanced — the caller uses a single model ID like my-combo.

List existing combos

curl $OMNIROUTE_URL/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_KEY"

Response includes id, name, strategy, enabled, and per-target stats.

Create a combo

curl -X POST $OMNIROUTE_URL/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-combo",
    "strategy": "priority",
    "targets": [
      { "provider": "anthropic", "model": "claude-opus-4-7", "weight": 1 },
      { "provider": "openai",    "model": "gpt-4o",           "weight": 1 }
    ]
  }'

19 public routing strategies

Strategy	Description
priority	Always use target[0]; fall back on error
weighted	Distribute by weight percentage
round-robin	Rotate targets in order
context-relay	Chain models for very long contexts
fill-first	Fill quota of target[0] before spilling
p2c	Power-of-two choices: sample two targets, pick the better candidate
random	Uniform random selection
least-used	Route to the target with the lowest observed usage
cost-optimized	Pick the cheapest eligible target for the token estimate
reset-aware	Prefer targets based on quota-reset state
reset-window	Order targets by their configured reset window
headroom	Prefer targets with more remaining quota headroom
strict-random	Random without repeating until all targets have been used
auto	Auto-Combo scoring across 16 factors
lkgp	Last-known-good-provider sticky routing
context-optimized	Pick the best model for the request's context size
cache-optimized	Prefer targets with stronger cache affinity
fusion	Run a panel in parallel and synthesize one judged response
pipeline	Run a configured sequence of targets as a pipeline

Auto-combo (recommended for production)

Auto-combo scores each candidate on 16 factors every request:

curl -X POST $OMNIROUTE_URL/api/combos \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-auto",
    "strategy": "auto",
    "targets": [
      { "provider": "anthropic", "model": "claude-sonnet-4-6" },
      { "provider": "openai",    "model": "gpt-4o-mini" },
      { "provider": "google",    "model": "gemini-2.0-flash" }
    ]
  }'

Then call it with:

curl -X POST $OMNIROUTE_URL/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "prod-auto", "messages": [{ "role": "user", "content": "Hello" }] }'

Activate / deactivate a combo

# Activate
curl -X PUT $OMNIROUTE_URL/api/combos/{id}/toggle \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -d '{ "enabled": true }'

Get combo metrics

curl $OMNIROUTE_URL/api/combos/{id}/metrics \
  -H "Authorization: Bearer $OMNIROUTE_KEY"

Returns p50/p95/p99 latency, success rate, cost, and per-target breakdown.

Simulate routing (dry run)

curl -X POST $OMNIROUTE_URL/api/routing/simulate \
  -H "Authorization: Bearer $OMNIROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "comboId": "{id}", "messages": [{ "role": "user", "content": "test" }] }'

Returns which provider would be selected and why — no actual API call is made.

Via MCP (if OmniRoute is your MCP server)

omniroute_list_combos     → list all combos
omniroute_switch_combo    → enable/disable a combo
omniroute_set_routing_strategy → change strategy at runtime
omniroute_simulate_route  → dry-run routing decision
omniroute_best_combo_for_task → get recommendation by task type

Errors

• 404 combo not found → check id from /api/combos
• 400 invalid strategy → use one of the 19 strategies above
• 409 name conflict → combo name already exists