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