Get or Set an API Key's Guardrail Binding

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.

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

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

Get or Set an API Key's Guardrail Binding

Authentication

GET

PUT

Scope rules

Errors

​Authentication

​GET

​PUT

​Scope rules

​Errors

Authentication

GET

PUT

Scope rules

Errors