Richtlinien

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

GET /api/v1/policies

Richtlinien mit optionalen Filtern auflisten.

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

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

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

POST /api/v1/policies

Neue Richtlinie anlegen.

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

Feld	Erforderlich	Beschreibung
`name`	✅	Richtlinien-Name (nicht leer)
`prompt`	✅	Die Neural Instruction — was die Richtlinie erkennt/durchsetzt (nicht leer)
`description`	—	Menschenlesbare Beschreibung
`action`	✅	Enforcement-Action. Genau einer der fünf Werte `BLOCK`, `APPROVAL`, `FLAG`, `LOG`, `ANONYMIZE` (Groß-/Kleinschreibung wird normalisiert). Es gibt keinen Vorgabewert mehr: Fehlt das Feld, antwortet der Endpunkt `400` mit der Kennung `policy_action_missing`; ein anderer Wert ergibt `400` mit `policy_action_invalid`.
`mode`	✅	`ENFORCE` (die Regel greift) oder `OBSERVE` (die Regel beobachtet nur). Fehlt `mode`, liefert der Dienst `400` mit `error.code` `policy_mode_missing`.
`severity`	—	Severity-Label
`status`	—	Initialer Status (Default `DRAFT`-artig; Aktivierung über Lifecycle)
`source`	—	Default `CUSTOM` (zählt gegen das Manual-Richtlinien-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, prompt oder mode liefert 400 (fehlt mode, ist error.code policy_mode_missing); eine fehlende oder unbekannte action liefert 400 mit der Kennung policy_action_missing bzw. policy_action_invalid. 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 Richtlinie aktualisieren. detection_mode_override (Alias detectionModeOverride) akzeptiert "exact", "semantic" oder den Leerstring "" zum Zurücksetzen auf Auto-Klassifikation; ein weggelassenes Feld bleibt unberührt.

Der Zustand (status) ist hier nicht änderbar; ein Aufruf mit diesem Feld wird mit policy_status_not_patchable abgewiesen, ohne dass andere Felder geschrieben werden. Zustandswechsel laufen über die Lifecycle-Endpunkte (siehe unten).

Lifecycle

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

Archivierte Richtlinien (Status DEPRECATED) bleiben in Traces und Audit-Logs abfragbar, werden aber nicht mehr gegen neue Anfragen ausgewertet. Über restore kehren sie in den abgeschalteten Zustand (INACTIVE) zurück und können danach wieder aktiviert werden.

POST /api/v1/policies/generate

Eine oder mehrere DRAFT-Richtlinien 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 Richtlinien (Default: wie Input)
`max_policies`	—	Obergrenze der generierten Richtlinien

Liefert generierte Richtlinien 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 Richtlinien-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`
`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
}

suggestion ist context-abhängig geformt (bei policy_builder enthält es die vorgeschlagenen Richtlinien-Felder).

Fehler

Fehler liefern ein strukturiertes error-Objekt (code, message, request_id). Wichtige Fälle:

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