Skip to main content
GET
Key Model Plan
The model plan controls which upstream engine a key runs. Two independent levers:
  • single_model — pin ONE engine for every text turn. This is a deterministic passthrough that skips the classifier (ideal for a coding / IDE backend, including a custom: bring-your-own model).
  • bindings — remap individual modes to specific engines; the classifier still routes, but each mode’s engine is pinned.
Engine ids are the real upstream ids (this is a configuration surface): arca-velox-5.1, arca-magnus-5.1, anthropic/claude-sonnet-4.6, anthropic/claude-opus-4.8, anthropic/claude-haiku-4.5, google/gemini-2.5-pro, openai/gpt-4.1, or your own custom:<providerId>:<model>.
For a full runnable flow (branches, guardrail nodes, routing) use the Orchestrator Graph instead — it takes precedence over the model plan.

Authentication

Requires an API key with billing scope; the caller must own the key.

Path Parameters

string
required
The API key UUID.

Get the plan

GET /api/v1/keys/{id}/model-plan
object | null
The pinned engine ({ upstream_id, fallback_upstream_id }) or null.
array
Per-mode overrides: { mode, upstream_id, fallback_upstream_id }.
array
The selectable engines (platform + your custom providers) for building a picker.

Replace the plan

PUT /api/v1/keys/{id}/model-plan — a full replace of both fields (send the complete desired state).
object | null
{ upstream_id, fallback_upstream_id? } to pin one engine for every text turn, or null to clear the pin.
object[]
Per-mode overrides, each { mode, upstream_id, fallback_upstream_id? }. Every referenced upstream id is validated against the platform catalog or your custom providers.

Example