> ## 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 快照,並附帶一個 `source` 枚舉,便於儀表盤向客戶說明該規則的來源。這四種來源對應解析層級:

* `key` — 針對該密鑰的規則(可能是隱藏偏好,也可能是顯式綁定到該密鑰的共享偏好)。
* `org_default` — 沒有針對該密鑰的綁定;回退到當前組織的默認偏好。
* `user_default` — 既沒有針對該密鑰的規則,也沒有組織默認偏好;回退到用戶的個人默認偏好。
* `none` — 沒有任何規則生效;路由引擎按未修改的方式運行。

## 身份驗證

需要具備 `billing` API 密鑰作用域的 Bearer 令牌,且對該密鑰擁有訪問權限。

## 請求示例

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

  ```typescript SDK theme={null}
  const eff = await theo.routingRules.effective(keyId);
  console.log(eff.source);             // "key" | "org_default" | "user_default" | "none"
  console.log(eff.preference_name);    // "This key's rules" | "ACME Legal Default" | null
  ```
</CodeGroup>

## 響應

```json theme={null}
{
  "key_id": "key_abc",
  "source": "key",
  "is_per_key": true,
  "preference_id": "1f4f2c1a-22ce-4b07-9c0b-9c4f4b9b1d2e",
  "preference_name": "This key's rules",
  "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 }
}
```

* `is_per_key: true` — 當前生效的來源是該密鑰的隱藏專屬偏好(即通過 [`/api/v1/keys/{id}/routing-rules`](/api-reference/routing-preferences/key-routing-rules) 保存的規則)。
* `preference_name` — 便於展示的名稱。隱藏的密鑰專屬偏好會渲染為 `"This key's rules"`,以確保 `__key:` 標記不會泄露到面向客戶的界面上。
* 當 `source` 為 `"none"` 時,`preference_id` 和 `preference_name` 均為 `null`,規則數組和示例數組均為空。

## 錯誤

* `404 not_found` — 密鑰不存在、已被撤銷,或調用者無權訪問。


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