Policies

Die Policies-API ist das programmatische Pendant zum Dashboard-Policy-Editor. Sie eignet sich, um Policies aus Infrastructure-as-Code auszurollen, Policies in Bulk aus Regulierungen zu generieren oder Policies zwischen Projekten zu synchronisieren.

GET /api/v1/policies

Policies mit optionalen Filtern auflisten.

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

Query	Default	Beschreibung
`status`	—	z. B. `DRAFT`, `ACTIVE`, `DEPRECATED`
`severity`	—	Nach Policy-Severity filtern
`action`	—	Nach Enforcement-Action filtern
`source`	—	Nach Policy-Quelle filtern (z. B. `CUSTOM`, `SYSTEM`, `CATALOG`)
`env`	—	Umgebungs-Scope

Jede zurückgegebene Policy trägt enforcementType, detectionModeOverride (nullable) und das berechnete effectiveDetectionMode.

POST /api/v1/policies

Neue Policy anlegen.

{
  "name": "Finanz-PII blockieren",
  "prompt": "Blockiere jeden Prompt mit Kreditkartennummern, IBANs oder SSNs.",
  "action": "BLOCK",
  "detection_mode_override": null,
  "scope": "all_agents",
  "status": "DRAFT"
}

Feld	Erforderlich	Beschreibung
`name`	✅	Policy-Name (nicht leer)
`prompt`	✅	Die Neural Instruction — was die Policy erkennt/durchsetzt (nicht leer)
`description`	—	Menschenlesbare Beschreibung
`action`	—	Enforcement-Action
`severity`	—	Severity-Label
`status`	—	Initialer Status (Default `DRAFT`-artig; Aktivierung über Lifecycle)
`source`	—	Default `CUSTOM` (zählt gegen das Manual-Guardrail-Limit)
`scope`	—	Scope-Selektor
`regulatory_ref`	—	Regulierungs-Referenz
`environment`	—	Umgebungs-Scope
`attestation_level`	—	Attestierungs-Level
`detection_mode_override`	—	`"exact"` / `"semantic"` / `null` (Auto-Klassifikation)

Fehlendes name oder prompt liefert 400 („Name and prompt are required"). Enthält der Body stattdessen ein Top-Level-Array policies, läuft der Legacy-Bulk-Sync-Pfad.

PATCH /api/v1/policies/{id}

Felder einer bestehenden Policy aktualisieren. detection_mode_override (Alias detectionModeOverride) akzeptiert "exact", "semantic" oder den Leerstring "" zum Zurücksetzen auf Auto-Klassifikation; ein weggelassenes Feld bleibt unberührt.

Lifecycle

Endpoint	Wirkung
`POST /policies/{id}/activate`	`DRAFT → ACTIVE`
`POST /policies/{id}/deprecate`	`ACTIVE → DEPRECATED`
`DELETE /policies/{id}`	Policy löschen

Deprecated Policies bleiben in Traces und Audit-Logs abfragbar, werden aber nicht mehr gegen neue Anfragen ausgewertet.

POST /api/v1/policies/generate

Eine oder mehrere DRAFT-Policies aus einem Regulierungsdokument generieren (z. B. EU-KI-Verordnung, DSGVO, HIPAA, eine interne AUP). Gesendet wird der Dokument-Text, kein Slug:

{
  "text": "…vollständiger oder auszugsweiser Regulierungstext…",
  "source_name": "EU AI Act Art. 5-6",
  "language": "de",
  "max_policies": 5
}

Feld	Erforderlich	Beschreibung
`text`	✅	Der Regulierungstext (Plain Text oder aus PDF extrahiert)
`source_name`	—	Name des Quelldokuments
`language`	—	Zielsprache der generierten Policies (Default: wie Input)
`max_policies`	—	Obergrenze der generierten Policies

Liefert generierte Policies im Status DRAFT. Jede einzelne im Dashboard prüfen, bevor sie aktiviert wird — der Generator ist high-recall, nicht high-precision.

POST /api/v1/ai/assist

Derselbe Endpoint, der den NL Policy Builder des Dashboards und den Agent-Wizard antreibt. Liefert zu einer natürlichsprachlichen Beschreibung einen strukturierten Vorschlag.

{
  "context": "policy_builder",
  "input": "Blockiere Kreditkartennummern und IBANs in Kundensupport-Prompts.",
  "language": "de"
}

Feld	Erforderlich	Beschreibung
`context`	✅	Welches Feature aufruft: `agent_onboarding`, `policy_builder`, `compliance_advisor`, `trace_explain`
`input`	✅	Die natürlichsprachliche Eingabe
`document_text`	—	Extrahierter Text aus einem hochgeladenen Dokument (PDF/DOCX/TXT)
`language`	—	Zielsprache der Antwort (Default `en`)

Response:

{
  "suggestion": { "…Struktur hängt vom context ab…": "…" },
  "model": "…",
  "processing_time_ms": 850,
  "remaining_today": 24
}

suggestion ist context-abhängig geformt (bei policy_builder enthält es die vorgeschlagenen Policy-Felder). remaining_today ist das verbleibende AI-Assist-Tageskontingent des Projekts.

Fehler

Fehler liefern einen einfachen {"error": "<Meldung>"}-Body (lokalisiert). Wichtige Fälle:

Status	Bedeutung
`400`	Fehlendes `name` oder `prompt` beim Anlegen
`409`	Manual-Guardrail-Limit des Tiers erreicht (`limit_exceeded`) — Upgrade oder bestehende Custom-Policy entfernen