Skip to main content
POST
Guard Content

Authorizations

X-API-Key
string
header
required

PromptGuard API key for developer endpoints. Keys start with pg_live_ and are created in the dashboard.

Headers

X-End-User
string | null

Your end user's id. Attributes the event to them on the End Users page, and with context.session_id names one session.

x-api-key
string | null

Body

application/json

Request body for the guard endpoint.

messages
GuardMessage · object[]
required

Messages to scan (OpenAI-style message array). When their text is more than one scan can read, the newest messages that fit are scanned and every older one is listed in unscanned as over_size_budget; only a newest message too large on its own is refused with 413.

Required array length: 1 - 512 elements
direction
string
default:input

Scan direction: 'input' (pre-LLM) or 'output' (post-LLM)

Pattern: ^(input|output)$
model
string | null

Model being used (for logging)

context
GuardContext · object | null

Optional framework context

retrieved_context
ContextDoc · object[] | null

RAG-retrieved documents to scan for knowledge poisoning. Each document is scanned individually; the first poisoned one blocks the request, and its position and source are returned in the event metadata so you know which document to drop. Scanning stops at that point, so a request with several poisoned documents reports the first. Optional; backwards-compatible.

Maximum array length: 32
media
MediaPartSchema · object[] | null

Media attachments to scan for steganographic payloads, adversarial patches, and font injection. Optional.

Maximum array length: 8
images
string[] | null

Image URLs or data: URIs to scan, as LiteLLM's PromptGuard guardrail sends them. Scanned like an image_url block on a message.

Maximum array length: 8
override
GuardOverride · object | null

A Shadow AI Device reporting an Override: the person sent a prompt the Device coached (a block that rested on one detector) anyway, with a reason. Sent with every message empty and nothing else to scan; any content is refused with 422. Recorded as an event with the decision override, its threat type and the reason, alerted on like a block and delivered to the SIEM, and not metered. The answer is allow: nothing was scanned.

agreement
boolean | null

Count how many independent detectors agree on a block. With true, a confident finding is put to the rest of the detectors for a second opinion and detectors_agreeing counts them, at the cost of the ML layer's latency on every such block. With false, the scan stops at its first detection and asks no second opinion, so detectors_agreeing counts only the detectors that had found the threat when the scan decided. The decision, threat type and deciding rule are the same either way. Left out (or null), agreement is counted, and the response carries Deprecation and Sunset headers: from 2027-02-11 leaving it out means false. A Shadow AI Device's credential always counts.

device_findings
DeviceFinding · object[] | null

What the calling Device's own masker caught before sending, as {category, count} pairs, never the values. category is one of the threat types this API returns (e.g. api_key_leak, pii_leak) and appears at most once; count is a positive integer. Any other key is rejected with 422. Recorded on this request's event, attributed to the Device, and shown in the fleet views; it does not change the decision. A block an injection model decided on a request whose findings include a secret is reported as that secret (threat_type secret_key_leak or api_key_leak), with the model's verdict kept as a finding that did not decide. Optional; clients that omit it are unaffected.

Maximum array length: 37

Response

Successful Response

Response from the guard endpoint.

decision
string
required

Policy decision: 'allow', 'block', or 'redact'

event_id
string
required

Unique event identifier for tracking

confidence
number
required

Confidence score of the decision

latency_ms
number
required

Processing time in milliseconds

dashboard_url
string | null

The dashboard page of the event this decision recorded, in its project: the page the proxy names in x-promptguard-dashboard-url. Null when no event was recorded (a pgshadow doctor probe is answered but not recorded), so there is no page to open.

weighted_score
number | null

Aggregate decision-driving score (severity * confidence, clamped to [0, 1]) when a severity-carrying detector decided the verdict; null otherwise. Raw confidence stays in the confidence field.

threat_type
string | null

Primary threat type detected

reason
string | null

Why the decision was reached, in the words the event records: the reason the dashboard shows for it (unless the project keeps no content, when the event keeps only the threat type). Free text, and it may quote what was found. A client that tells a person why a request was stopped names this and threat_type, not a finding of its own, so the person and the dashboard give one explanation. Null on an allow that found nothing, and on any response from an Engine older than this field.

redacted_messages
GuardMessage · object[] | null

Redacted messages (only present when decision='redact'). Always the TEXT projection: a message sent as content blocks comes back as a string. Attachments are never rewritten, we do not re-encode a PDF with the secret removed, and returning one that looked redacted would be worse than returning none. A message listed in unscanned as over_size_budget was not read, so it comes back as its text, unredacted.

threats
ThreatDetail · object[]

Detailed threat breakdown

flagged
boolean
default:false

True when a finding flagged: allowed, reported, not enforced. The flagged findings are in threats with flagged: true, each with its threat type and rule. decision stays allow for a flag that decided, so a client that does not read this field lets the traffic through as before; on a block or redact it says a flag was also found. The event is stored with the decision flag.

detectors_agreeing
integer
default:0

On a block, how many independent detectors found the threat that decided it: 1 when one detector's verdict alone decided, 2 or more when others agreed. Counted by detector, not rule. 0 on anything but a block. A Shadow AI Device coaches rather than blocks a block resting on one detector (basis detectors and 1 here): the person may send it anyway, with a reason.

basis
enum<string> | null

On a block, what it rests on: secret (a credential), organisation_rule (a policy, rule or pattern the organisation wrote), or detectors (the built-in detectors, as many as detectors_agreeing says). Null on anything but a block.

Available options:
secret,
organisation_rule,
detectors
unscanned
UnscannedAttachment · object[]

Parts that reached us and were not read: they produced nothing to scan, or the scan budget was spent first. An allow with a non-empty unscanned is NOT 'this content is clean', it is 'the text was clean and these parts were never read'. Reasons: url_only (we do not fetch caller-supplied URLs, that would be an SSRF primitive), file_id_unsupported, encrypted, no_text_extracted (a scanned/rasterised document), too_large, undecodable, unsupported_type, extractor_unavailable, unsupported_block, unsupported_tool_call (a tool call in none of the shapes we can read: index is its position among the request's tool calls), over_size_budget (a message older than the newest ones that filled the scan budget: index is its position in messages; it was not read on this call, and was the newest turn of an earlier one).

unavailable
UnavailableCheck · object[]

Unavailable checks: detectors this scan would have run but the deployment cannot, because their backing service (an ML inference endpoint, an LLM judge, a bundled model) is not configured. An allow with a non-empty unavailable is NOT 'every check passed', these detectors never looked. A detector that ran and found nothing is not listed, and neither is one the project's plan or guardrail settings leave out.

skipped
SkippedMatch · object[]

Matches deliberately not redacted, one entry per match, in the order found; an empty list when there were none. The text of a skipped match is left as it was. Reported for the text the scan's PII pass read; empty when the Project's guardrails run none.

Example:
requests_counted
integer
default:0

How many Requests this call counted as toward the monthly allowance: 1 for a scan, whatever its length. 0 for a call that is not a scan: a findings-only report, a doctor probe or an Override.

billed_tokens
integer
default:0

The tokens of content this call scanned, counted with the cl100k_base tokenizer whatever model the content is for: each scanned text is encoded on its own and the counts are added. What is scanned is the messages read with their tool calls, retrieved context and Tool definitions; for a Shadow AI Device, the Current turn, the Instructions and the Tool definitions not already checked, never an Earlier turn. Reported, not yet charged for. 0 for a call that is not a scan.

detection_level
string
default:deep

The Detection level this call ran at: always deep, every detector including the LLM judges. Every plan runs the full engine and is billed at one list price, per call and per Billed token.

Allowed value: "deep"
entitlement
GuardEntitlement · object | null

What this account is entitled to, at the instant this scan was answered. Null when the engine cannot say, an account with no subscription row, an admin key that bypasses the counter, or a row it could not read. Null is 'unknown', NOT 'unentitled': a client that reads it as a limit has invented a refusal the engine never made.