Policies

The Policies API is the programmatic equivalent of the dashboard policy editor. Use it to roll out policies from infrastructure-as-code, to bulk-generate policies from regulations, or to sync policies between projects.

GET /api/v1/policies

List policies with optional filters.

GET /api/v1/policies?status=ACTIVE&severity=HIGH

Query	Default	Description
`status`	—	e.g. `DRAFT`, `ACTIVE`, `DEPRECATED`
`severity`	—	Filter by policy severity
`action`	—	Filter by enforcement action
`source`	—	Filter by policy source (e.g. `CUSTOM`, `SYSTEM`, `CATALOG`)
`env`	—	Environment scope

Each returned policy carries enforcementType, detectionModeOverride (nullable), and the computed effectiveDetectionMode.

POST /api/v1/policies

Create a new policy.

{
  "name": "Block financial PII",
  "prompt": "Block any prompt containing credit card numbers, IBANs, or SSNs.",
  "action": "BLOCK",
  "detection_mode_override": null,
  "scope": "all_agents",
  "status": "DRAFT"
}

Field	Required	Description
`name`	✅	Policy name (non-empty)
`prompt`	✅	The neural instruction — what the policy detects/enforces (non-empty)
`description`	—	Human-readable description
`action`	—	Enforcement action
`severity`	—	Severity label
`status`	—	Initial status (default `DRAFT`-like behaviour; activate via lifecycle)
`source`	—	Defaults to `CUSTOM` (counts against the manual-guardrail limit)
`scope`	—	Scope selector
`regulatory_ref`	—	Regulation reference
`environment`	—	Environment scope
`attestation_level`	—	Attestation level
`detection_mode_override`	—	`"exact"` / `"semantic"` / `null` (auto-classify)

Missing name or prompt returns 400 ("Name and prompt are required"). If the request body contains a top-level policies array instead, the endpoint runs the legacy bulk-sync path.

PATCH /api/v1/policies/{id}

Update fields on an existing policy. detection_mode_override (alias detectionModeOverride) accepts "exact", "semantic", or the empty string "" to clear back to auto-classify; omitting the field leaves it untouched.

Lifecycle

Endpoint	Effect
`POST /policies/{id}/activate`	`DRAFT → ACTIVE`
`POST /policies/{id}/deprecate`	`ACTIVE → DEPRECATED`
`DELETE /policies/{id}`	Delete the policy

Deprecated policies stay queryable in traces and audit logs but are no longer evaluated against new requests.

POST /api/v1/policies/generate

Generate one or more DRAFT policies from a regulation document (e.g. EU AI Act, GDPR, HIPAA, an internal AUP). Send the document text, not a slug:

{
  "text": "…full or excerpted regulation text…",
  "source_name": "EU AI Act Art. 5-6",
  "language": "en",
  "max_policies": 5
}

Field	Required	Description
`text`	✅	The regulation text (plain text or extracted from PDF)
`source_name`	—	Name of the source document
`language`	—	Target language for generated policies (default: same as input)
`max_policies`	—	Cap on the number of generated policies

Returns generated policies in DRAFT status. Review every one in the dashboard before activating — the generator is high-recall, not high-precision.

POST /api/v1/ai/assist

The same endpoint that powers the dashboard's NL Policy Builder and the agent wizard. Given a natural-language description, returns a structured suggestion.

{
  "context": "policy_builder",
  "input": "Block credit card numbers and IBANs in customer-support prompts.",
  "language": "en"
}

Field	Required	Description
`context`	✅	Which feature is calling: `agent_onboarding`, `policy_builder`, `compliance_advisor`, `trace_explain`
`input`	✅	The user's natural-language input
`document_text`	—	Extracted text from an uploaded document (PDF/DOCX/TXT)
`language`	—	Target language for the response (default `en`)

Response:

{
  "suggestion": { "…structure depends on context…": "…" },
  "model": "…",
  "processing_time_ms": 850,
  "remaining_today": 24
}

suggestion is context-shaped (for policy_builder it contains the proposed policy fields). remaining_today is the project's remaining AI-assist quota for the day.

Errors

Errors return a plain {"error": "<message>"} body (localized). Notable cases:

Status	Meaning
`400`	Missing `name` or `prompt` on create
`409`	Tier's manual-guardrail limit reached (`limit_exceeded`) — upgrade or remove an existing custom policy