> ## 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.

# Create Routing Preference

> Author a new Routing Studio preference.

Create a new Routing Studio preference. Idempotent — the same `Idempotency-Key` header replays the same response.

Creating a preference does **not** auto-bind it to a key. Use [PUT /api/v1/keys/{id}/routing-preference](/api-reference/routing-preferences/key-routing-preference) to opt a key in, or edit rules directly on a key via [PUT /api/v1/keys/{id}/routing-rules](/api-reference/routing-preferences/key-routing-rules).

## Authentication

Requires a Bearer token with the `billing` API key scope.

## Body

<ParamField body="name" type="string" required>
  Preference name. 1–128 chars. May not reference upstream provider names (Claude, OpenAI, Anthropic, Gemini, fal.ai, etc.).
</ParamField>

<ParamField body="description" type="string">
  Free-text description. Up to 512 chars.
</ParamField>

<ParamField body="rules" type="object[]">
  Up to 50 keyword/regex rules. Each rule has `pattern` (ECMAScript regex source, ≤512 chars), `target_mode` (a Theo mode), optional `target_engine` (Theo-branded engine id), `confidence` (clamped server-side to `[0.5, 0.99]`), and an optional `description`.
</ParamField>

<ParamField body="examples" type="object[]">
  Up to 30 few-shot examples injected into the classifier's system prompt. Each example has `prompt` (≤1024 chars), `expected_mode`, and optional `expected_engine`.
</ParamField>

<ParamField body="confidence_floor_overrides" type="object">
  Per-mode replacements for the global `0.85` promotion floor. Values are clamped to `[0.5, 0.99]`.
</ParamField>

<ParamField body="scope" type="string">
  `"personal"` (default) or `"team"`. Team scope requires an active org and the `manageWebhooks` permission.
</ParamField>

<ParamField body="is_default" type="boolean">
  Mark this preference as the default for its scope. At most one default per scope.
</ParamField>

## Request Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://www.hitheo.ai/api/v1/routing-preferences \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "ContractIQ Legal",
      "description": "Contract terms get the analytical engine.",
      "rules": [
        {
          "pattern": "\\b(clause|provision|indemnity|warranty)\\b",
          "target_mode": "think",
          "confidence": 0.92,
          "description": "Contract terms get the analytical engine."
        }
      ],
      "examples": [
        { "prompt": "Look at this clause", "expected_mode": "think" }
      ]
    }'
  ```

  ```typescript SDK theme={null}
  const pref = await theo.routingPreferences.create({
    name: "ContractIQ Legal",
    description: "Contract terms get the analytical engine.",
    rules: [
      {
        pattern: "\\b(clause|provision|indemnity|warranty)\\b",
        target_mode: "think",
        confidence: 0.92,
        description: "Contract terms get the analytical engine.",
      },
    ],
    examples: [{ prompt: "Look at this clause", expected_mode: "think" }],
  });
  ```
</CodeGroup>

## Errors

* `400 routing_preference_invalid` — Vendor-named label or pattern, uncompilable regex, unknown engine, or rule/example cap exceeded.
* `400 org_required` — `scope: "team"` without an active organization.
* `403 missing_scope` — API key lacks the `billing` scope.
* `409 conflict` — `is_default: true` already set for this scope.