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-8 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).

A capability’s thinking budget resolves to one of four settings, none, low, medium, or high, where medium sits between a cheap nudge and a full reasoning pass. Each setting maps onto whatever the destination provider actually supports, so the same capability produces an Anthropic thinking budget, an OpenAI reasoning effort, or a Gemini thinking budget without the alias or your call site changing. If your org runs thinking budgets in auto mode, the gateway’s complexity judge picks the tier per request instead of the capability pinning one, and every request records whether the budget came from the client, the org default, or auto, so the choice is auditable on the usage page.

The cheap-fast capability currently ships without a bound model: a cap:cheap-fast request is served by the automatic routing band instead, and the x-iq-served-model response header discloses the fall-through with cap_unresolved: true.

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 the fallback on the request row rather than failing the call.

Once a cap: reference resolves to a (provider, model, thinking_budget) tuple, that tuple is binding within your team’s model allow-list: when the resolved model is on the allow-list (or no allow-list is set), the gateway dispatches it first rather than treating the resolution as a hint the routing layer is free to swap. A resolved model outside your team’s allow-list is not promoted to dispatch. If that dispatch fails on a retryable error, automatic fallback runs down the family ladder for the request’s judged complexity tier, the same tier-based ladder described in Routing, appended behind the resolved model as the fallback tail. Whenever the model that actually served the request diverges from the capability’s resolved target, the x-iq-served-model response header names the model that served it, so the divergence is visible from the response alone.

Per-org overrides propagate within about a minute. The resolver caches the row it resolved for sixty seconds, so a dashboard override write lands on live traffic once that window turns over rather than on the very next request.

The resolved decision is recorded on the request’s routing record 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.

cap:orchestrate

cap:orchestrate is a seventh capability handle, structurally separate from the six defaults above: the exclusive channel to claude-fable-5. The model is never a rung in the auto, frontier, or cheap ladder, never the target of default, and never reached by the family lock’s fallback climb described in Routing; the only way to reach it is naming cap:orchestrate in the model field, per request. That placement is deliberate: claude-fable-5 is scoped to the kind of work its shape fits, not slotted into the complexity ladder as another rung to climb, so nothing routes to it by escalation and no other alias falls through to it.

A safety refusal that comes back as a well-formed 200 is not treated as a successful response on a cap:orchestrate route. The gateway detects the refusal structurally and treats it as a routing failure, which triggers the same automatic fallback described above: the request moves to the next model in the fallback tail, and the x-iq-served-model header names whichever model actually answered. This detection covers non-streaming requests only in v1; a streaming cap:orchestrate call does not get the same structural check, so a streamed response still needs your own client-side handling for a refusal.

Two per-request limits apply on cap:orchestrate routes specifically, and both are hard stops with an explicit error rather than a silent substitution. A per-request spend ceiling, $2.50 by default, is computed as a worst-case cost estimate before the request ever dispatches; a request whose estimate exceeds the ceiling never reaches the model, and the gateway returns a 4xx error naming both the estimate and the cap. A tool-call ceiling, 8 tool calls by default, caps how many tool calls a single response can carry; a response that would exceed it returns an error instead of the tool-call fan-out. Both numbers are product limits that can change, not a fixed contract — treat the values above as the current defaults rather than something to hardcode against.

claude-fable-5 is priced at $10 per million input tokens and $50 per million output tokens, which is what the spend-ceiling estimate is computed against.

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 prompt is a short editable field on the drawer, so the test is one throwaway call of your own wording rather than a sample of your live traffic, and the result panel reports the chosen provider, the chosen model, the latency, the per-call cost, and the response text.

Every override write records an audit entry under the capability_override_set action. The entry 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.fairmeter.in/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.fairmeter.in/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. If automatic fallback changed which model actually served the request, the x-iq-served-model response header names that model, so the divergence from the requested capability is visible from the response headers alone. 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.