> ## 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 密鑰，或清除綁定。

管理 API 密鑰與**共享**路由工作室偏好（跨多個密鑰使用，或作為團隊默認值的偏好）之間的綁定關係。如果需要更簡單的、直接在密鑰上編輯規則的密鑰優先方式，請參見 [`/api/v1/keys/{id}/routing-rules`](/api-reference/routing-preferences/key-routing-rules)。

將 `preference_id` 設為 null 即可清除綁定；此後該密鑰在請求時將按順序繼承組織默認值 → 用戶默認值 → 無。

## 身份驗證

需要攜帶具有 `billing` API 密鑰作用域的 Bearer 令牌，並且調用方需擁有對該密鑰的訪問權限（調用方本人擁有該密鑰，或通過所在活躍組織獲得訪問權限）。

## GET

讀取當前的綁定關係。

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

```typescript theme={null}
const { preference_id, inherits_default } = await theo.keys.getRoutingPreference(keyId);
```

```json theme={null}
{
  "key_id": "key_abc",
  "preference_id": "1f4f2c1a-22ce-4b07-9c0b-9c4f4b9b1d2e",
  "inherits_default": false
}
```

## PUT

設置或清除綁定關係。

<ParamField body="preference_id" type="string">
  偏好的 UUID。傳入 `null` 可清除綁定。
</ParamField>

```bash theme={null}
# 綁定一個偏好
curl -X PUT https://www.hitheo.ai/api/v1/keys/{id}/routing-preference \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "preference_id": "1f4f2c1a-22ce-4b07-9c0b-9c4f4b9b1d2e" }'

# 清除綁定
curl -X PUT https://www.hitheo.ai/api/v1/keys/{id}/routing-preference \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "preference_id": null }'
```

```typescript theme={null}
await theo.keys.setRoutingPreference(keyId, "1f4f2c1a-22ce-4b07-9c0b-9c4f4b9b1d2e");
await theo.keys.setRoutingPreference(keyId, null); // 清除
```

## 作用域規則

* 個人偏好只能綁定到其創建者本人擁有的密鑰。
* 團隊偏好只能綁定到同一組織內的密鑰。
* 跨越該邊界會返回 `400 routing_preference_not_bindable`，並附帶與廠商無關的提示信息。

## 錯誤

* `400 routing_preference_not_bindable` — 該偏好對該密鑰的作用域不可見。
* `404 not_found` — 密鑰或偏好不存在（或調用方不可見）。


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