Omni Combos Routing

---
name: omni-combos-routing
description: 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.
---
<!-- generated by src/lib/agentSkills/generator.ts; manual edits will be overwritten -->

## 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

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

### POST /api/combos

Create routing combo

```bash
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

```bash
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.

```bash
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.

```bash
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

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

### GET /api/combos/metrics

Get combo metrics

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

### POST /api/combos/test

Test a combo configuration

```bash
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.

```bash
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.

```bash
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

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

## Payloads

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

<!-- skill:custom-start -->
<!-- Migrated from skills/omniroute-routing/SKILL.md (preserved curated content) -->

# OmniRoute — Routing & Combos

Requires `OMNIROUTE_URL` and `OMNIROUTE_KEY`. See [entry-point SKILL](https://raw.githubusercontent.com/diegosouzapw/OmniRoute/main/skills/omniroute/SKILL.md) 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

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

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

## Create a combo

```bash
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 13 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 13 factors every request:

```bash
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:

```bash
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

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

## Get combo metrics

```bash
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)

```bash
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
<!-- skill:custom-end -->