Skip to main content
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.
​
preference_id
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).