Skip to main content
Gateway Guardrails layer deterministic input/output policies around every completion bound to an API key. The SDK exposes:
  • theo.guardrails.policies — author and manage policies.
  • theo.guardrails.presets — read-only preset templates.
  • theo.guardrails.executions — tail the audit log.
  • theo.keys.getGuardrailPolicy / setGuardrailPolicy — bind a policy to a key.
See the Guardrails guide for the strict opt-in contract, the built-in protections, and the verdict semantics. The API reference covers the underlying HTTP shapes.

Strict opt-in contract

A policy applies only when explicitly bound to an API key via theo.keys.setGuardrailPolicy(). Unbound keys never trigger a guardrail — there is no automatic org or user default fallback. Creating a policy (or seeding one from a preset) does not auto-bind it.

Policies

List

Get

Create

scope: "team" requires an active org and the team-config permission. Idempotent via the Idempotency-Key header.

Update

Sending rules replaces the entire rule set.

Delete

Cascade-removes every key binding pointing at the policy — previously-bound keys revert to the strict opt-in default (no enforcement).

Test (replay a prompt)

Replays a fixture prompt (and optional model output) against the policy and returns the verdict trail — used by the dashboard test bench without burning a real completion call.

Bindings

List active (non-revoked) keys currently bound to a policy. Use this to verify a policy is enforcing on the keys you expect before relying on it in production.

Presets

Read-only blueprints the dashboard offers in the empty state. The four shipping presets are pii-safe, strict-json, cost-conscious, and enterprise-default. Creating a policy from a preset is a normal policies.create() call seeded with the preset’s rules:

Executions (audit log)

The append-only log of every guardrail evaluation. Personal callers see their own rows; team callers see every member’s rows on policies owned by the active org. Rows persist for 90 days.

Key bindings

Error handling

When an input-phase deny fires, the SDK throws a structured error matching the REST envelope:
For streaming completions, the same envelope is emitted as an error SSE event before done. See Error handling for the full taxonomy.

Types

The SDK exports first-class types for every shape:
  • GuardrailPolicySummary — full policy row.
  • GuardrailRuleInput — single rule (guardrail_id, phase, verdict, optional config, enabled, rule_order).
  • GuardrailId"pii_redactor" | "prompt_injection" | "json_repair" | "max_length" | "profanity".
  • GuardrailPhase"input" | "output".
  • GuardrailVerdict"flag" | "redact" | "truncate" | "repair" | "deny".
  • GuardrailPolicyPreset — preset template returned by presets.list().
  • GuardrailPolicyBinding — single row of the bindings endpoint.
  • GuardrailPolicyTestResult — verdict trail returned by policies.test().
  • GuardrailExecutionRecord — single row of the executions audit log.