Skip to main content
POST
/
v1
/
policies
/
{policy_id}
/
revisions
Create a policy revision
curl --request POST \
  --url https://api-sandbox.featherhq.com/v1/policies/{policy_id}/revisions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "based_on_revision_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "check_config": {},
  "action_config": {},
  "tool_target": "<string>",
  "mode": "monitor",
  "timeout_ms": 2,
  "strictness": "relaxed",
  "priority": 0
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "policy_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "check_type": "<string>",
  "enforcement_point": "<string>",
  "action": "<string>",
  "mode": "<string>",
  "on_error": "<string>",
  "strictness": "<string>",
  "priority": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "check_config": {},
  "action_config": {},
  "tool_target": "<string>",
  "timeout_ms": 123,
  "created_by": "<string>"
}

Authorizations

​
x-api-key
string
header
required

Path Parameters

​
policy_id
string<uuid>
required

Body

application/json

Author a new named revision of a policy (optionally cloned from another).

​
name
string
required
Required string length: 1 - 255
​
check_type
enum<string>
required

How a policy decides whether content/state violates it.

  • expression: a PolicyExprEvaluator boolean over turn state.
  • llm_judge: a secondary LLM (via model_router) judges against guardrail_text.
Available options:
expression,
llm_judge
​
enforcement_point
enum<string>
required

Where in a turn a policy's check fires (v2: one point per policy).

agent_response is the single author-facing reply point — the v1 response (per-streamed-unit) + post_response (complete reply) split is an internal runtime detail now, selected by the platform-derived enforcement strategy (buffer-and-gate vs per-unit), not an authored distinction.

Available options:
input,
pre_tool,
post_tool,
agent_response
​
action
enum<string>
required

What happens when a check fails.

  • block: emit a canned safe message, raise PolicyViolationError, short-circuit.
  • redact: deterministic regex/truncate (NO LLM rewrite).
  • append: append a disclaimer.
  • require_approval: route through the HITL approval seam (pre_tool only).
  • handoff: hand off via HandoffService (source="policy").

The v1 monitor action is gone — observe-only is the monitor mode now.

Available options:
block,
redact,
append,
require_approval,
handoff
​
description
string | null
​
based_on_revision_id
string<uuid> | null
​
check_config
Check Config · object
​
action_config
Action Config · object
​
tool_target
string | null
​
mode
enum<string>
default:monitor

The author's INTENT dial — act vs observe. Channel-independent.

  • enforce: the policy acts on a violation (block / redact / append / require_approval / handoff) per the platform-derived strategy.
  • monitor: shadow/canary — the check runs and records would_be_action but never affects the turn. The safe-rollout default.

The TRANSPORT property v2 conflated into enforcement_mode (buffer-and-gate vs best-effort) is now platform-derived from transport_class at runtime (:func:src.policy.resolution.resolve_strategy), never authored. New-policy default selection is monitor (shadow-first; set at the schema layer).

Available options:
enforce,
monitor
​
on_error
enum<string> | null

What to do when a check errors/times out.

Action-derived default (v2): block action → fail_closed; else fail_open.

Available options:
fail_open,
fail_closed
​
timeout_ms
integer | null
Required range: x >= 1
​
strictness
enum<string>
default:relaxed

The streaming latency/guarantee dial (renamed from the v2 severity).

  • strict: always enforce before the user sees anything. On a STREAMING transport this holds/buffers (or incrementally gates), accepting brief added latency; on a BLOCKING transport gating is free.
  • relaxed: enforce without slowing the conversation — best-effort on streaming transports (content may stream while the check runs), but still a FULL gate on blocking transports (gating is free there). relaxed never means "off".

Configurable only at input·llm_judge and agent_response·expression; forced (and hidden in the UI) elsewhere. New-policy default is relaxed.

Available options:
strict,
relaxed
​
priority
integer
default:0

Response

Successful Response

​
id
string<uuid>
required
​
policy_id
string<uuid>
required
​
name
string
required
​
check_type
string
required
​
enforcement_point
string
required
​
action
string
required
​
mode
string
required
​
on_error
string
required
​
strictness
string
required
​
priority
integer
required
​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required
​
description
string | null
​
check_config
Check Config · object
​
action_config
Action Config · object
​
tool_target
string | null
​
timeout_ms
integer | null
​
created_by
string | null