Verify

Der zentrale Endpoint für KI-Governance — Prompt senden, Entscheidung erhalten.

Jede Governance-Entscheidung beginnt hier. Senden Sie einen Prompt; Palveron lässt ihn durch Policies, NGE und (optional) LLM-Assist laufen; Sie erhalten eine Entscheidung und einen vollständig attributierten Trace zurück.

POST /api/v1/verify

curl -X POST https://gateway.palveron.com/api/v1/verify \
  -H "Authorization: Bearer pv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Meine Sozialversicherungsnummer ist 123-45-6789.",
    "agent_id": "agent_...",
    "context": { "sourceSystem": "kundensupport-ui" }
  }'

Request

Feld	Erforderlich	Beschreibung
`prompt`	✅	Der auszuwertende Text
`agent_id`	—	Agent-Attribution (Default: anonymer Projekt-Agent)
`attachments`	—	Array von Multi-Modal-Payloads (siehe Multi-Modal)
`context`	—	Freiform-Metadaten (MCP-Server, Tool-Name, Source-UI) — werden in Traces durchgereicht
`dry_run`	—	Wenn `true`, wird kein Trace persistiert (nur für clientseitiges Previewing)

Response

{
  "decision": "BLOCKED",
  "reason": "PII erkannt: SSN",
  "trace_id": "trc_01HVB...",
  "integrity_hash": "sha256:...",
  "modified_prompt": null,
  "nge_policy_scores": {
    "injection": 0.04,
    "toxicity": 0.02,
    "off_topic": 0.18,
    "pii_density": 0.91
  },
  "detected_entities": [
    { "type": "SSN", "start": 26, "end": 37, "confidence": 0.99, "redacted": "[SSN]" }
  ],
  "deterministic_results": {
    "regex_matches": ["ssn_us"],
    "keyword_matches": [],
    "blocklist_hits": []
  },
  "engine": "nge_local",
  "policies_evaluated": ["pol_pii_mask", "pol_no_pii"],
  "latency_ms": 42
}

Entscheidungen

PASSED — Anfrage erlaubt, Original-Prompt weitergeleitet.
BLOCKED — Anfrage abgelehnt. reason erklärt den Grund; modified_prompt ist null.
MODIFIED — Anfrage erlaubt mit Änderungen. modified_prompt enthält die redigierte Version.
FLAGGED — Anfrage erlaubt; eine LOG_ONLY-Policy hat ausgelöst und der Verstoß wurde im Trace protokolliert.
PENDING_APPROVAL — Anfrage wartet auf menschliche Freigabe. Trace oder Approval-Queue-API pollen, um den Ausgang zu erfahren.
ERROR — Interner Fehler. Retry; bei Persistenz Support mit trace_id kontaktieren.

HTTP-Status-Codes

Der HTTP-Status spiegelt das decision-Feld — Load Balancer, Observability-Tools und HTTP-aware Clients (z. B. MCP- / OpenClaw-Konsumenten) bekommen so ein verlässliches Signal, ohne den JSON-Body parsen zu müssen.

Status	Decision	Bedeutung
`200 OK`	`PASSED` / `MODIFIED` / `FLAGGED` / `POLICY_CHANGE`	Anfrage erlaubt. Den (ggf. modifizierten) Prompt an das LLM weiterleiten.
`202 Accepted`	`PENDING_APPROVAL`	Menschliche Freigabe erforderlich. Der Trace ist persistiert; die Freigabe wird über `trace_id` verfolgt.
`403 Forbidden`	`BLOCKED`	Anfrage abgelehnt durch Policy, Capability-Modell oder Per-Agent-Budget-Cap. Nicht retryen — `reason` prüfen.
`429 Too Many Requests`	kein `decision`	Tier-Rate-Limit erreicht. `Retry-After` respektieren. Body ist der Rate-Limit-Error, kein Verify-Response.
`400 Bad Request`	kein `decision`	Fehlerhafte Anfrage: fehlender Prompt, zu großes Attachment, ungültige Config.

Der JSON-Body ist die Quelle der Wahrheit. Eine Response mit decision-Feld ist ein Verify-Response, unabhängig vom Status (200 / 202 / 403). Clients sollten auf decision verzweigen, nicht auf response.ok. HTTP-Status-Branching ist reserviert für 429 (Rate-Limit) und 5xx (Transport-Fehler).

NGE-Felder

Feld	Beschreibung
`nge_policy_scores`	NLI-basierte Confidence-Scores pro Policy-Intent (0.0 – 1.0). Befüllt, wenn NGE-Modus `nge_local` oder `nge_fallback` ist.
`detected_entities[]`	PII / Named-Entity-Treffer mit Byte-Offsets und Confidence. Befüllt, wenn NGE-Entity-Detection aktiv ist.
`deterministic_results`	Regex-, Aho-Corasick-Keyword- und Blocklist-Treffer — immer befüllt, NGE-unabhängig.
`engine`	Welche Engine das Ergebnis produziert hat: `disabled`, `nge_local`, `nge_fallback` oder `llm_only`.

Bei engine = nge_fallback enthält die Response zusätzlich escalated_to_llm (true / false) — true heißt, ein Grenzfall wurde zur Cloud-LLM für die finale Entscheidung eskaliert.

Siehe Neural-Governance-Engine-Leitfaden für die vollständige Pipeline und Trade-offs pro Modus.

Fehler

Abzugrenzen von einem Governance-BLOCKED (das ist ein erfolgreiches 403 mit Verify-Body) — diese Status zeigen, dass die Gateway die Anfrage überhaupt nicht verarbeiten konnte.

Status	Code	Bedeutung
`400`	`MISSING_PROMPT`	Pflichtfeld `prompt` fehlt
`400`	`INVALID_ATTACHMENT`	Nicht unterstützter MIME-Typ oder zu großes Payload
`401`	`INVALID_API_KEY`	Fehlender oder ungültiger API-Key
`429`	`RATE_LIMIT_EXCEEDED`	Per-Key-Burst oder Monatskontingent erreicht; `Retry-After` respektieren
`503`	`NGE_RELOADING`	Modelle werden neu geladen (~2 s); transient, einmal wiederholen

Tipp: Transport-Fehler von Governance-Block unterscheiden, indem auf das decision-Feld geprüft wird. Wenn vorhanden → Verify-Response (Body parsen). Wenn nicht vorhanden → Status-Code als Transport-/Auth-Fehler behandeln.

Retry-Verhalten

POST /verify ist standardmäßig nicht idempotent — ein Retry erzeugt einen zweiten Trace. Die SDKs lösen das, indem sie auf jeder Anfrage einen Idempotency-Key-Header (UUID v4) setzen und nur bei idempotent-sicheren Fehlern (Timeouts und 5xx) wiederholen. Eigene Clients sollten dasselbe tun: Idempotency-Key setzen, transiente Fehler mit Exponential Backoff plus Jitter wiederholen.

POST /api/v1/verify
Idempotency-Key: 4d6b9a40-...

Palveron dedupliziert über den Idempotency-Key für 24 Stunden — ein Retry innerhalb dieses Zeitfensters gibt die Original-Response zurück, ohne einen Duplikat-Trace zu erzeugen.

On this page