Skip to main content
Manage the 1:1 binding between an API key and a guardrail policy. The strict opt-in contract is enforced here: passing policy_id: null clears the binding and the key returns to no enforcement — there is no automatic fallback to an org or user default.

​
Authentication

Requires a Bearer token with the billing API key scope and access to the key (the caller must own it, or — for team keys — have access through the org).

​
GET

Read the current binding. 
curl https://www.hitheo.ai/api/v1/keys/{id}/guardrails \
  -H "Authorization: Bearer $THEO_API_KEY"

const { policy_id, has_policy } = await theo.keys.getGuardrailPolicy(keyId);

{ "key_id": "key_abc", "policy_id": "1f4f2c1a-...", "has_policy": true }

​
PUT

Set or clear the binding.
​
policy_id
string
Policy UUID. Pass null to clear the binding entirely.
# Bind a policy
curl -X PUT https://www.hitheo.ai/api/v1/keys/{id}/guardrails \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "policy_id": "1f4f2c1a-22ce-4b07-9c0b-9c4f4b9b1d2e" }'

# Clear the binding
curl -X PUT https://www.hitheo.ai/api/v1/keys/{id}/guardrails \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "policy_id": null }'

await theo.keys.setGuardrailPolicy(keyId, "1f4f2c1a-22ce-4b07-9c0b-9c4f4b9b1d2e");
await theo.keys.setGuardrailPolicy(keyId, null); // clear

​
Scope rules

  • Personal policies can only be bound to keys owned by their author.
  • Team policies can only be bound to keys in the same org.
  • Crossing the boundary returns 400 guardrail_policy_not_bindable with a vendor-neutral message.

​
Errors

  • 400 guardrail_policy_not_bindable — Policy is not visible to the key’s scope.
  • 404 not_found — Key or policy doesn’t exist (or isn’t visible to the caller).