Bind a Shared Preference to a Key

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

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

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

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

PUT

Set or clear the binding.

string

Preference UUID. Pass null to clear the binding.

# 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 }'

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

Overview

Completions

Media Generation

Audio

Skills API

E.V.I. Canvas

Workflows

Hooks

Settings

Embed Widgets

Guardrails

Routing Studio

Theo Browser

Benchmarks

Webhooks

Billing

Resources

Bind a Shared Preference to a Key

Authentication

GET

PUT

Scope rules

Errors

​Authentication

​GET

​PUT

​Scope rules

​Errors

Authentication

GET

PUT

Scope rules

Errors