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

# Bind a Shared Preference to a Key

> Bind an existing Routing Studio preference to an API key, or clear the binding.

Manage the binding between an API key and a **shared** Routing Studio preference (one that spans multiple keys or acts as a team default). For the simpler key-first surface that edits rules directly on the key, see [`/api/v1/keys/{id}/routing-rules`](/api-reference/routing-preferences/key-routing-rules).

A null `preference_id` clears the binding; the key then inherits org default → user default → none at request time.

## Authentication

Requires a Bearer token with the `billing` API key scope and access to the key (caller owns it, or has access through the active org).

## GET

Read the current binding.

```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

Set or clear the binding.

<ParamField body="preference_id" type="string">
  Preference UUID. Pass `null` to clear the binding.
</ParamField>

```bash theme={null}
# Bind a preference
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" }'

# Clear the binding
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); // clear
```

## Scope rules

* Personal preferences can only be bound to keys owned by their author.
* Team preferences can only be bound to keys in the same org.
* Crossing the boundary returns `400 routing_preference_not_bindable` with a vendor-neutral message.

## Errors

* `400 routing_preference_not_bindable` — Preference is not visible to the key's scope.
* `404 not_found` — Key or preference doesn't exist (or isn't visible to the caller).