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