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.",
    "metadata": { "agent_id": "ckagent..." },
    "context": { "tool_name": "kundensupport-ui" }
  }'

Request

Feld	Erforderlich	Beschreibung
`prompt`	✅	Der auszuwertende Text
`metadata`	—	Freiform-JSON-Objekt. `metadata.agent_id` attribuiert die Anfrage einem registrierten Agent (ohne diese Angabe wird der Trace ohne Agent-Attribution aufgezeichnet). `metadata.source: "browser"` kennzeichnet Browser-Guard-Traffic.
`attachments`	—	Array von Multi-Modal-Payloads (siehe Multi-Modal)
`context`	—	Request-Origin-Kontext: `tool_name`, MCP-Server, Chain-Depth, Source-System — wird in Traces durchgereicht
`structured_input`	—	Optionale strukturierte Feld-Zerlegung für Tools mit Routing-Metadaten (z. B. `email:send`). Wenn vorhanden und das Tool der Field-Role-Registry bekannt ist, enthält die Response `modified_fields`.
`extracted_text`	—	Legacy: vor-extrahierter Text aus Bildern/PDFs. Bevorzugt `attachments` verwenden.

Agent-Attribution gehört in metadata.agent_id — es gibt kein Top-Level-Feld agent_id. Ein Top-Level-agent_id wird still ignoriert und der Trace bleibt agent-anonym.

Response

{
  "decision": "BLOCKED",
  "output": "",
  "reason": "PII erkannt: SSN",
  "trace_id": "cktrace...",
  "integrity_hash": "sha256:...",
  "sequence_num": 1042,
  "flare_status": "PENDING",
  "should_anchor": true,
  "content_type": "text"
}

Feld	Beschreibung
`decision`	Das Governance-Urteil (siehe unten)
`output`	Der Inhalt, der an das LLM weitergeleitet wird. Bei `MODIFIED` die redigierte/geänderte Version; bei `PASSED` das Original.
`reason`	Menschenlesbare Begründung (vorhanden, wenn eine Policy ausgelöst hat)
`trace_id`	ID des unveränderlichen Trace-Records — nutzbar im Trace Explorer, in Exporten und bei `POST /api/v1/verify-proof`
`integrity_hash`	SHA-256-Integritäts-Hash des Trace
`sequence_num`	Monotone Trace-Sequenznummer pro Projekt
`flare_status`	Blockchain-Anchoring-Status des Trace (z. B. `PENDING`), wenn Flare aktiv ist
`should_anchor`	Ob dieser Trace für Blockchain-Anchoring qualifiziert
`content_type`	Erkannter Inhaltstyp (`text`, `image`, `audio`, `document`, …)
`findings`	Nur bei Multi-Modal-Anfragen: Findings pro Attachment
`enforcement_action`	Nur bei Browser-Guard-Anfragen: Browser-Enforcement-Aktion (`BLOCK`, `WARN`, `JUSTIFY`, `REDIRECT`)
`action_config`	Nur zusammen mit `enforcement_action`: deren Konfiguration (z. B. Redirect-Ziel)
`error_class`	Nur bei fail-closed-/Engine-Fehler-Urteilen: maschinenlesbare Fehlerklasse (z. B. `llm_4xx`)
`modified_fields`	Nur bei `structured_input`-Anfragen: Ergebnis-Map pro Feld (ROUTING erhalten, CONTENT maskiert)

Optionale Felder fehlen im JSON vollständig, wenn sie nicht zutreffen.

Per-Policy-NGE-Scores, erkannte Entities und Match-Details sind nicht Teil der Verify-Response — sie werden am Trace aufgezeichnet. Abrufbar über die Traces-API oder den Trace Explorer.

Entscheidungen

PASSED — Anfrage erlaubt, Original-Prompt in output.
BLOCKED — Anfrage abgelehnt. reason erklärt den Grund.
MODIFIED — Anfrage erlaubt mit Änderungen. output 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. Ausgang verfolgen über GET /api/v1/approvals/status?trace_id=....
POLICY_CHANGE — Anfrage erlaubt; sie hat ein Governance-/Policy-Change-Ereignis ausgelöst, kein Inhalts-Urteil.

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. `output` 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. Den `Retry-After`-Header respektieren. Body ist der Rate-Limit-Error, kein Verify-Response.
`400 Bad Request`	kein `decision`	Fehlerhafte Anfrage (z. B. fehlender `prompt`). Body: `{"error": "<Meldung>"}`.
`503 Service Unavailable`	kein Body	Die Gateway konnte die Governance-Entscheidung nicht dauerhaft aufzeichnen (DB und DLQ nicht verfügbar). Mit Backoff wiederholen.

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).

Resilience-Header

Jede Governance-Response trägt drei Header:

Header	Werte
`X-Palveron-Status`	`healthy` \| `degraded` — Plattform-Health-Rollup
`X-Palveron-Trace-Persisted`	`db` \| `dlq` \| `none` — wo der Trace dieser Anfrage gelandet ist
`X-Palveron-Degraded-Subsystems`	Kommagetrennte Liste; fehlt vollständig bei gesunder Plattform (Header-Abwesenheit ist die schnelle „alles gut"-Probe)

Fehler

Abzugrenzen von einem Governance-BLOCKED (das ist ein 403 mit Verify-Body) — Transport-/Validierungsfehler liefern ein einfaches Fehler-Objekt:

{ "error": "Prompt is required" }

Fehlermeldungen sind lokalisiert (Accept-Language) und menschenlesbar; ein separates maschinenlesbares Fehlercode-Feld gibt es auf diesem Endpoint nicht.

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 nicht idempotent — ein Retry erzeugt einen zweiten Trace. Nur bei transienten Fehlern wiederholen (Timeouts, 429 unter Beachtung von Retry-After, 5xx) — mit Exponential Backoff plus Jitter; 403/400 sind final.

On this page