Verify

Every governance decision starts here. Send a prompt; Palveron runs it through policies, NGE, and (optionally) LLM-assist; you get back a decision and a fully-attributed trace.

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": "My social security number is 123-45-6789.",
    "metadata": { "agent_id": "ckagent..." },
    "context": { "tool_name": "customer-support-ui" }
  }'

Request

Agent attribution lives in metadata.agent_id — there is no top-level agent_id field. A top-level agent_id is silently ignored and the trace stays agent-anonymous.

Response

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

Optional fields are omitted from the JSON entirely when not applicable.

Per-policy NGE scores, detected entities, and match details are not part of the verify response — they are recorded on the trace. Retrieve them via the Traces API or the Trace Explorer.

Decisions

• PASSED — Request allowed, original prompt in output.
• BLOCKED — Request rejected. reason explains why.
• MODIFIED — Request allowed with edits. output contains the redacted version.
• FLAGGED — Request allowed; a LOG_ONLY policy fired and the violation is recorded in the trace. If the flagged prompt carries detected personal data or credentials, they are masked before being passed on and the verdict is relabelled ANONYMIZED (or REDACTED for credentials); the triggering rule stays recorded as an observed policy on the trace. The response field observed_policies lists these observed policies (always present, [] when there is none).
• PENDING_APPROVAL — Request queued for a human approver. Track the outcome via GET /api/v1/approvals/status?trace_id=....
• POLICY_CHANGE — Request allowed; it triggered a governance/policy-change event rather than a content verdict.

Sending with a justification in the browser

When the gateway detected personal data in a prompt from Browser Guard, employees can send the prompt with a justification. Only categories that allow a justification go in clear text: person name, organization, location, email address and phone number. IBAN, credit card, social security and tax numbers, ID numbers, credentials and every other category stay masked. In this case the answer carries the field justification:

label is the identifier of the category (such as IBAN), name its word in the language of the request (such as "Person name"), count the number of distinct values. The clear text of a masked detail never appears in the answer, and the field is not stored.

With state: "unavailable", enforcement_action is BLOCK, reason_code is justification_unavailable, and reason reads: "This prompt could not be fully checked for personal data. Sending with a justification is therefore not possible, and the prompt was not sent. Please try again later." The verdict in decision stays the gateway's verdict.

What was actually sent after the choice is stated in the record of the request (see the Traces API).

HTTP status codes

The HTTP status code mirrors the decision field, so load balancers, observability tools, and HTTP-aware clients (e.g. MCP / OpenClaw consumers) get a faithful signal without having to parse the JSON body.

The JSON body is the source of truth. A response with a decision field is a verify response regardless of status (200 / 202 / 403). Clients should branch on decision, not on response.ok. Reserve HTTP-status branching for 429 (rate limits) and 5xx (transport errors).

Resilience headers

Every governance response carries three headers:

Errors

Distinct from a governance BLOCKED (which is a 403 with a verify-shaped body), transport/validation errors return a structured error object:

{ "error": { "code": "validation_error", "message": "Prompt is required", "request_id": "req-..." } }

Messages are localized (Accept-Language); branch on error.code (for example validation_error), and quote error.request_id in support requests.

Tip: distinguish a transport error from a governance block by checking for the decision field. If it's present, the response is a verify outcome (parse the body). If it's absent, treat the status code as a transport/auth error.

Retry behavior

POST /verify is not idempotent — a retry creates a second trace. Retry only on transient failures (timeouts, 429 honouring Retry-After, 5xx) with exponential backoff and jitter, and treat 403/400 as final.