> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Key Model Plan

> Read or replace a key's model plan — a single-model pin and/or per-mode engine bindings.

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](/api-reference/custom-providers/manage)).
* **`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>`.

<Note>For a full runnable flow (branches, guardrail nodes, routing) use the [Orchestrator Graph](/api-reference/keys/orchestrator-graph) instead — it takes precedence over the model plan.</Note>

## Authentication

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

## Path Parameters

<ParamField path="id" type="string" required>The API key UUID.</ParamField>

## Get the plan

`GET /api/v1/keys/{id}/model-plan`

<ResponseField name="single_model" type="object | null">The pinned engine (`{ upstream_id, fallback_upstream_id }`) or `null`.</ResponseField>
<ResponseField name="bindings" type="array">Per-mode overrides: `{ mode, upstream_id, fallback_upstream_id }`.</ResponseField>
<ResponseField name="catalog" type="array">The selectable engines (platform + your custom providers) for building a picker.</ResponseField>

## Replace the plan

`PUT /api/v1/keys/{id}/model-plan` — a **full replace** of both fields (send the complete desired state).

<ParamField body="single_model" type="object | null">
  `{ upstream_id, fallback_upstream_id? }` to pin one engine for every text turn, or `null` to clear the pin.
</ParamField>

<ParamField body="bindings" type="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.
</ParamField>

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X PUT https://www.hitheo.ai/api/v1/keys/KEY_ID/model-plan \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "bindings": [
          { "mode": "fast",  "upstream_id": "arca-velox-5.1" },
          { "mode": "think", "upstream_id": "arca-magnus-5.1" }
        ] }'
  ```

  ```ts SDK theme={null}
  await theo.keys.setModelPlan("KEY_ID", {
    single_model: { upstream_id: "anthropic/claude-opus-4.8" }, // deterministic passthrough
  });
  ```
</CodeGroup>