Skip to content
IQ Routing

Capability aliases

A capability alias is a stable, intent-named handle that an agent author writes into request code so the gateway picks the right concrete model at routing time. Instead of pinning claude-opus-4-7 at every call site that needs heavy reasoning, the agent author writes model=cap:reason-heavy and the gateway resolves the alias against a per-org capability table. A model-family migration becomes one dashboard click, not a code change across every agent loop. The vocabulary is small by design; six default capabilities cover the routing decisions agent code makes most often, and the per-org override mechanism handles every other case.

The six default capabilities

The gateway ships six default capabilities. Each one resolves to a concrete model and thinking budget that the gateway maintains and tunes; you write the intent-named handle and the gateway keeps the mapping current as the provider mix changes. You can override any default with your own model pick per org (see below).

The reason-heavy capability covers plan-style steps in a multi-step agent loop: anywhere the agent decomposes a goal into subgoals, and any critique step that has to evaluate a prior agent output against a specification. It resolves to a high-reasoning flagship with an extended thinking budget.

The tool-call-strict capability covers the tool-arg-formatter step in an agent loop, anywhere the agent emits a function call against a JSON schema. It resolves to a model with strong strict-mode function calling so the JSON shape lands reliably on a tight schema.

The long-context-128k capability covers a prompt that carries a large attachment (a long meeting transcript, a multi-document research brief, the full context window of a prior agent loop) where the response needs to reason over the full attachment. It resolves to a cost-efficient long-context model.

The vision capability covers any request that includes an image attachment in the message array. It resolves to a cost-efficient vision-capable model.

The cheap-fast capability covers the high-volume, low-stakes parts of an agent loop: text classification, simple Q+A against a small context, sentiment scoring, and anything else where the per-request cost matters more than the marginal quality delta. It resolves to the cheapest, fastest model in the catalog.

The json-mode capability covers a strict-JSON response shape where the input is a free-text prompt rather than a tool-call schema. It resolves to a cost-efficient model that lands JSON mode reliably.

When to use which capability

Reason-heavy synthesis is the canonical fit for cap:reason-heavy. When the agent has to combine multiple retrieval results into a coherent answer, the synthesis step rewards the high-quality multi-step reasoning path more than any other step in the loop. The thinking-budget=high setting pays for itself on the synthesis step because the model has to reconcile contradictions across the retrieved chunks and produce a single output that respects all of them.

Tool-call execution is the canonical fit for cap:tool-call-strict. When the agent has to emit a structured function call against a tight JSON schema, the strict-mode function-calling path lands the schema correctly more often than the alternatives. The provider pick on this capability is load-bearing; the alternative providers drop the schema shape on roughly five percent of tool-call requests at the gateway's current calibration mix.

Long-context retrieval is the canonical fit for cap:long-context-128k. When the agent is reading a 100k-token document and answering a question against the full context, the cost-efficient long-context window beats the alternatives by an order of magnitude on per-token cost without giving up answer quality on the retrieval-style question shape.

Vision input is the canonical fit for cap:vision. When the agent is reading a screenshot or chart and answering a question about it, the vision-capable model with no thinking-budget overhead lands the right output without paying the high-thinking premium on a perception-bound task. Vision tasks rarely benefit from extended chain-of-thought because the bottleneck is the visual parse, not the reasoning step.

Cost-sensitive simple QA is the canonical fit for cap:cheap-fast. When the agent is answering a one-line factual question against a small context, the low-cost low-latency path pays the highest dividend on budget pressure. A high-volume classification or sentiment step in an agent loop typically lands a 10x to 30x cost reduction on the step's spend by routing through cap:cheap-fast instead of the default reason-heavy path.

JSON-mode structured output is the canonical fit for cap:json-mode. When the agent has to emit a strict JSON schema from a free-text prompt (not a tool-call schema), the schema-conformant JSON output path lands the shape correctly without the overhead of the tool-call wrapper. Use cap:tool-call-strict instead when the output is a function call; use cap:json-mode when the output is a free-form JSON object that the downstream code parses directly.

Resolution precedence

A cap: reference resolves against the per-org capability table first. If your org has an override for that capability, the gateway uses it. If not, the gateway falls back to the global default mapping. Resolution never blocks the request: if the override store is unreachable, the gateway ships the request to the default model and records a cap_resolve_failed_open event rather than failing the call.

Per-org overrides propagate within about a minute. A dashboard override write takes effect on the next request inside that window, and the editor's Save button forces the change to apply immediately rather than waiting for the window to expire.

The resolved decision is recorded on the route-decision row with the chosen capability, the concrete model it resolved to, and the source of the mapping, so the dashboard sessions surface at /sessions/[id] can replay the decision for postmortem review.

Focus-mode interaction

The capability resolver biases on the per-org focus mode. When the focus mode is set to cost reduction, the resolver prefers a cheaper variant and a lower thinking budget within the capability tier; when it is set to quality mode, the resolver prefers a premium variant and a higher thinking budget. The default balanced mode applies no bias and uses the mapping as written. The focus-mode bias composes with the step-class bias rather than overriding it.

The focus-mode bias is the cheapest dial the operator has on the agent loop's cost envelope. A cost-driven workload typically lands a meaningful cost reduction on the agent loop's total spend by flipping the focus mode to cost reduction and leaving the capability vocabulary unchanged; the quality-mode flip lands the inverse trade-off for customer-facing flows.

Override the default mapping

The dashboard editor at /settings/capabilities surfaces the per-org capability table. Each row carries the capability name, the resolved (provider, model, thinking_budget) tuple, the row source (global default when no override exists, per-org override when the operator has written a row), and the priority column. The Edit drawer opens a per-row form with the same four fields; submitting the form writes the override row and emits a capability_override_set audit event.

A Test capability button on the Edit drawer lets the operator preview the resolved tuple plus the live cost estimate against a synthetic prompt before committing the override row, so a fat-fingered provider pick or a typo in the model name surfaces in the preview pane rather than landing on the live agent loop. The preview runs against the staging gateway with a fixed 200-token prompt and reports the per-call cost in dollars to four decimal places.

Every override write records an org_audit_events row under action = "capability_override_set". The audit row carries the actor email, the previous tuple, the new tuple, and the request id of the write so the operator can replay the change against the request browser. The write also triggers a webhook delivery to every active subscriber under the org's webhook subscription list, so a downstream automation can react to the override (for example, posting a Slack notice to the ops channel or invalidating a downstream cache).

curl -X POST https://gateway.iq-routing.com/admin/capabilities \
  -H "Authorization: Bearer $IQ_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "11111111-2222-3333-4444-555555555555",
    "capability": "reason-heavy",
    "provider": "openai",
    "model": "gpt-5",
    "thinking_budget": "high",
    "priority": 200
  }'

The webhook event payload carries the same fields as the audit row plus the event name and the created-at timestamp:

{
  "event": "capability_override_set",
  "org_id": "...",
  "capability": "reason-heavy",
  "provider": "openai",
  "model": "gpt-5",
  "thinking_budget": "high",
  "priority": 200,
  "actor_email": "...",
  "created_at": "..."
}

The cap:<name> syntax

The gateway accepts the cap: prefix on the request's model field in both the OpenAI-compatible chat-completions surface and the Anthropic- compatible messages surface. The prefix replaces the concrete model name; the rest of the request shape is unchanged.

curl https://gateway.iq-routing.com/v1/chat/completions \
  -H "Authorization: Bearer gw_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cap:reason-heavy",
    "messages": [
      {"role": "user", "content": "Decompose: ship a billing dashboard in two weeks."}
    ]
  }'

The response carries the resolved concrete model on the model field of the response body, so the agent loop can log the actual model that ran without an extra round-trip to the gateway's admin surface. The X-Request-Id header on the response correlates to the route-decision row in the dashboard's /requests browser, where the resolved tuple plus the focus-mode bias plus the capability source appear as columns on the request detail page.