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

# 創建路由偏好

> 創建一個新的 Routing Studio 偏好設置。

創建一個新的 Routing Studio 偏好設置。該接口具有冪等性——使用相同的 `Idempotency-Key` 請求頭會重放相同的響應。

創建偏好設置**不會**自動將其綁定到某個密鑰。請使用 [PUT /api/v1/keys/{id}/routing-preference](/api-reference/routing-preferences/key-routing-preference) 讓某個密鑰選用它,或通過 [PUT /api/v1/keys/{id}/routing-rules](/api-reference/routing-preferences/key-routing-rules) 直接在密鑰上編輯規則。

## 身份驗證

需要攜帶具備 `billing` API 密鑰作用域的 Bearer 令牌。

## 請求體

<ParamField body="name" type="string" required>
  偏好設置名稱。長度為 1–128 個字符。不得包含上游供應商名稱(如 Claude、OpenAI、Anthropic、Gemini、fal.ai 等)。
</ParamField>

<ParamField body="description" type="string">
  自由文本描述,最多 512 個字符。
</ParamField>

<ParamField body="rules" type="object[]">
  最多 50 條關鍵詞/正則規則。每條規則包含 `pattern`(ECMAScript 正則表達式源碼,≤512 字符)、`target_mode`(一個 Theo 模式)、可選的 `target_engine`(Theo 品牌化的引擎 id)、`confidence`(服務端會將其限制在 `[0.5, 0.99]` 範圍內)以及可選的 `description`。
</ParamField>

<ParamField body="examples" type="object[]">
  最多 30 條少樣本(few-shot)示例,會被注入分類器的系統提示詞中。每條示例包含 `prompt`(≤1024 字符)、`expected_mode`,以及可選的 `expected_engine`。
</ParamField>

<ParamField body="confidence_floor_overrides" type="object">
  按模式覆蓋全局 `0.85` 的晉升閾值下限。取值會被限制在 `[0.5, 0.99]` 範圍內。
</ParamField>

<ParamField body="scope" type="string">
  `"personal"`(默認)或 `"team"`。團隊作用域需要一個處於激活狀態的組織,並且需要具備 `manageWebhooks` 權限。
</ParamField>

<ParamField body="is_default" type="boolean">
  將此偏好設置標記為其所屬作用域的默認項。每個作用域最多隻能有一個默認項。
</ParamField>

## 請求示例

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

## 錯誤

* `400 routing_preference_invalid` —— 標籤或規則中包含供應商名稱、正則表達式無法編譯、引擎未知,或規則/示例數量超出上限。
* `400 org_required` —— `scope: "team"` 但沒有處於激活狀態的組織。
* `403 missing_scope` —— API 密鑰缺少 `billing` 作用域。
* `409 conflict` —— 該作用域下已存在 `is_default: true` 的偏好設置。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.