Routing & model selection

model=auto vs selected model

Send "model":"auto" (or a virtual model id) and the gateway resolves a concrete executable offer. Inspect the response headers:

• X-Darouter-Selected-Model — concrete model that ran
• X-Darouter-Effective-Model / related Selected-/Effective- headers when present
• X-Darouter-Route-Explanation — human-readable why
• X-Darouter-Decision-ID — look up later via portal Routing or GET /v1/optimizer/decisions/{id}

curl -sS -D - https://api.cybertronic.dev/v1/chat/completions \
  -H "Authorization: Bearer $DAROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"auto","messages":[{"role":"user","content":"ping"}]}' \
  -o /tmp/out.json | grep -i x-darouter

Fallbacks, cascade, hedge

When a primary attempt fails or a hedge wins first token, the decision record lists attempts. Portal Routing loads aggregates from GET /v1/optimizer/aggregates and a single decision by id. winner_cost_micros sums won attempts only — do not invent cross-attempt savings.

Cascade rescues and hedge wins are observable signals, not a published SLA or guaranteed cheaper bill.

Cache-aware ranking

X-Darouter-Cache-Reason is a closed enum explaining cache-aware rank contribution. It is distinct from a gateway HIT and from provider prompt_cache_key. No provider-native KV affinity claim.

Portal

Customer portal → Routing: load aggregates for an evidence window, paste a decision id, export JSON/CSV. Optimization panel loads the efficiency advisor (advisory until you opt in).

OpenAPI operations

Contract: /v1/openapi.json. Routing starts at chat, then explain via optimizer decisions:

• POST /v1/chat/completions — drop-in chat (send model=auto or a virtual model id)
• GET /v1/models, GET /v1/models/{id} — listed offers
• GET /v1/optimizer/decisions/{decision_id} — explain resolution after the fact
• GET /v1/optimizer/aggregates — evidence-window rollups in portal Routing