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

# 管理某个密钥的路由规则

> 免偏好设置的捷径——直接在 API 密钥上编辑规则。

这是 Routing Studio 的简化的、以密钥为中心的入口。客户从不会看到"偏好设置"对象——服务端会在后台自动查找或创建一个隐藏的按密钥偏好设置，并确保绑定行指向它。

当你要调优单个 API 密钥时，请使用此端点。当你想要一套跨多个密钥共享的规则集、或作为团队默认设置时，请改用 [`/api/v1/routing-preferences`](/api-reference/routing-preferences/list-preferences)。

## 认证

需要具有 `billing` API 密钥作用域的 Bearer 令牌，并且需要有权访问该密钥（调用者拥有该密钥，或通过其所在的活跃组织获得访问权限）。

## GET

读取该密钥的规则以及已解析的绑定状态。

```bash theme={null}
curl https://www.hitheo.ai/api/v1/keys/{id}/routing-rules \
  -H "Authorization: Bearer $THEO_API_KEY"
```

```typescript theme={null}
const snap = await theo.routingRules.get(keyId);
console.log(snap.active);          // true if these rules drive completions today
console.log(snap.shared_binding);  // populated when the key is bound to a shared preference
```

### 响应

```json theme={null}
{
  "key_id": "key_abc",
  "rules": [
    {
      "id": "r_a4b8c01x9y",
      "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" }
  ],
  "confidence_floor_overrides": { "think": 0.65 },
  "active": true,
  "shared_binding": null
}
```

* `active: true` —— 这些规则当前正驱动该密钥的补全请求。
* `active: false` —— 该密钥继承了默认设置（或绑定到了某个共享偏好设置）；规则仍可编辑，但在保存之前或共享绑定被清除之前不会生效。
* `shared_binding` —— 当该密钥绑定到某个共享偏好设置（而非其隐藏行）时会填充此字段。此时应将共享规则渲染为只读，并提供一个"在此密钥上覆盖"按钮。

## PUT

替换按密钥的规则/示例/覆盖项。该路由会自动查找或创建隐藏的偏好设置，并确保绑定指向它。

<ParamField body="rules" type="object[]">最多 50 条规则。结构与 `routing-preferences` 相同。</ParamField>
<ParamField body="examples" type="object[]">最多 30 个少样本（few-shot）示例。</ParamField>
<ParamField body="confidence_floor_overrides" type="object">按模式设置的置信度下限覆盖项。</ParamField>

```bash theme={null}
curl -X PUT https://www.hitheo.ai/api/v1/keys/{id}/routing-rules \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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 theme={null}
await theo.routingRules.set(keyId, {
  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" }],
});
```

## DELETE

清除按密钥的规则：删除绑定，使解析级联回退到**组织默认 → 用户默认 → 无**，并删除隐藏的偏好设置行。指向非隐藏（共享）偏好设置的现有绑定不受影响。

```bash theme={null}
curl -X DELETE https://www.hitheo.ai/api/v1/keys/{id}/routing-rules \
  -H "Authorization: Bearer $THEO_API_KEY"
```

## 错误

* `400 routing_preference_invalid` —— 校验失败（例如出现供应商名称、正则表达式无法编译等）。
* `404 not_found` —— 密钥不存在、已被吊销，或调用者无权访问。


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