Skip to main content
POST /v1/guard is the only runtime endpoint. A collector calls it to evaluate one request against its detector chain. See How it works for the pipeline behind it.

​
Authentication

POST /v1/guard
Authorization: Bearer <collector-api-key>
Content-Type: application/json
The collector is resolved from the API key. Do not send a collector_id in the body.

​
Request

{
  "input": {
    "messages": ["What's the weather?"],
    "attachments": [
      { "filename": "policy.pdf", "content_type": "application/pdf", "data": "<base64>" },
      { "url": "https://example.com/page" }
    ]
  },
  "direction": "input",
  "protocol": "llm",
  "session_id": "sess-123",
  "consumer_id": "[email protected]",
  "metadata": { "content_type": "application/json" }
}
FieldTypeRequiredNotes
inputobject✅Free-form payload to inspect. input.attachments is extracted separately (not sent to text detectors).
directionenum—input (default) or output. Selects which detectors run.
protocolenum—all (default) · llm · mcp · a2a. Selects which detectors run.
session_idstring—Conversation key for stateful detectors (multiturn_guard). Synthesised if omitted (treated as single-turn).
consumer_idstring—Actor identifier used by anomaly_detector for per-actor tracking.
metadataobject—Free-form. metadata.content_type overrides the content type used to skip inapplicable detectors.
Unknown top-level fields are rejected with 400 (strict decoding).

​
Attachments & SSRF

Each attachment provides either base64 data or a url:
  • URL fetches are HTTPS-only and bounded (10s timeout, 50 MiB cap, max 5 redirects).
  • A strict SSRF guard resolves DNS before dialing and rejects loopback, private, link-local, multicast, CGNAT (100.64/10), 0.0.0.0/8, and cloud-metadata (169.254.169.254) targets. Proxy env vars are ignored.
  • Attachment bytes are never persisted.

​
Response

Always 200 for a detection — TrustGuard never drops traffic. 
{
  "is_flagged": false,
  "transformed_payload": { "email": "[MASKED_EMAIL]" },
  "findings": [
    {
      "detection_type": "pii",
      "confidence": 0.95,
      "rule_name": "",
      "is_flagged": false,
      "details": { "masked": 1, "entities": ["email"] }
    }
  ],
  "trace_id": "f1e2…",
  "request_id": "a9b8…"
}
FieldTypeNotes
is_flaggedbooleanOR over all findings; true only when a block-mode detector fired.
transformed_payloadobject | nullThe rewritten payload; null unless a redact-mode mutable detector changed it.
findings[]arrayOne entry per detector that reported, sorted by detector type.
findings[].detection_typestringe.g. pii, secret, jailbreak, injection, toxicity.
findings[].confidencenumberDetector-specific score.
findings[].rule_namestringOptional, set by some detectors.
findings[].is_flaggedbooleanWhether this finding’s detector was in block mode.
findings[].detailsobjectFree-form, detector-specific context (e.g. matched entities, masked count).
trace_id / request_idstringCorrelation IDs (also on logs and telemetry).

​
Status codes

CodeWhen
200Always, for any detection (including block findings). The caller enforces.
400Invalid body, unknown fields, bad direction/protocol.
401Missing or invalid API key.
403Key found but inactive/expired.
500A detector errored and the deployment is configured fail-closed (opt-in). With the fail-open default you get 200.

​
Enforcing the verdict

TrustGuard is advisory. Your collector inspects the response and decides: 
if response.is_flagged                  → block / 4xx the original request
else if response.transformed_payload    → forward the masked payload instead
else                                    → forward unchanged
When TrustGuard runs behind TrustGate, the gateway performs this enforcement for you.