Combos

Overview

Combos publish a named model chain. A client sends the combo name as model; Aurora calls the first model as primary and uses the remaining models as ordered fallback targets.

Use combos when application code should call one stable model name while operators control the primary model and fallback sequence centrally.

Manual management

Use the dashboard at Combos to create, edit, disable, and delete combos. Add providers first, confirm real selectors in GET /admin/api/v1/models, then build the combo from those selectors.

coding-default
  primary:  <provider-name>/<primary-model-id>
  fallback: <provider-name>/fallback-model-id
 

Clients call the combo by name:

{
  "model": "coding-default",
  "messages": [{"role": "user", "content": "Review this function."}]
}
 

Worked example: review chain

Imagine you want a coding-review pipeline: a cheap model drafts a review, an expensive model polishes it. Define a combo with two entries:

curl -X POST http://your-aurora-host/admin/api/v1/combos \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "review-chain",
    "description": "Cheap draft, expensive polish",
    "enabled": true,
    "models": [
      "openai-primary/gpt-4o-mini",
      "anthropic-prod/claude-sonnet-4-5"
    ]
  }'

The first model is the primary. Aurora calls it; if it succeeds, the response is returned. If the primary errors with a 5xx, a 429, or a network failure, Aurora falls through to the second model. Subsequent entries in the list are the ordered fallback chain � they are tried in order until one succeeds.

Clients call the combo as if it were a single model:

curl http://your-aurora-host/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -d '{
    "model": "review-chain",
    "messages": [{"role": "user", "content": "Review this pull request"}]
  }'

The response includes the model field set to the actual upstream model ID that served the request (e.g. openai-primary/gpt-4o-mini), not the combo name. Use the usage log to monitor which combo entry actually answered: filter on the alias name you sent and group by upstream model.

Worked example: tiered router

The other common pattern is a small model that decides whether to escalate to a large model. Aurora does not run the routing logic itself in OSS � use a workflow or a combo where the primary is the cheap model and the fallback is the large model. For richer routing (the small model picks the fallback), see Combos (advanced) in Enterprise, which supports adaptive routing with feedback signals.

How combos differ from pools and failover

Pick one of these per logical model name. Mixing them is supported but makes routing harder to reason about.

Gotchas

• Real selectors � combo entries must be <provider>/<model> strings returned by /admin/api/v1/models. If upstream discovery has not yet happened, the combo creation will fail with selector_not_found.
• Pricing � the response usage carries the cost of whichever model in the chain actually answered. Set per-model pricing overrides for every entry.
• Workflows � the workflow for the primary model is used; workflows for fallback models are not consulted. If you need per-fallback routing rules, use Failover instead.
• Disable, don't delete � disabling a combo with enabled: false returns a clear combo_disabled error. Deleting it is permanent and clients fall back to a 404.
• Aliases and combos can collide � an alias name and a combo name share the namespace. Pick distinct names.

Server API automation

For endpoint reference see the Admin API section.

curl -X POST http://your-aurora-host/admin/api/v1/combos \
  -H "Authorization: Bearer $AURORA_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "coding-default",
    "description": "Default coding chain",
    "enabled": true,
    "models": [
      "<provider-name>/<primary-model-id>",
      "<provider-name>/fallback-model-id"
    ]
  }'
 

Use real selectors from /admin/api/v1/models. Combos are routing policy, not provider credentials.