Security Scan & Redact
These endpoints provide direct access to PromptGuard’s threat detection and PII redaction engines. Unlike the Guard API (which accepts structured messages), these endpoints accept raw text strings, making them ideal for simple integrations, pipelines, and batch processing.Scan Endpoint
Analyze a text string for prompt injection, jailbreak attempts, and other threats.Authentication
Request Body
Response
Field naming. Success bodies from
/api/v1/security/scan and /api/v1/security/redact are camelCase (threatType, eventId, processingTimeMs). The shared error envelope and the proxy’s response metadata are snake_case (event_id, threat_type). This split is intentional and frozen: the camelCase shape is what the SDKs parse, and renaming it would break every released client. Do not write a client that accepts both, pick the one for the surface you are calling.Examples
Redact Endpoint
Strip PII (personally identifiable information) from a text string and return both the original and redacted versions.Authentication
Request Body
Supported PII Types
Common targets:phone, ip_address and passport are families that expand to several
detectors. You can also name a detector directly (phone_us, ipv4,
us_passport) along with any of the other 40-odd entity types — national ID
numbers, bank identifiers, driving licences — enumerated in the
OpenAPI spec.
An unrecognized name is rejected with a 400; it is never ignored, so a typo
cannot quietly return text that was left unscanned.
Response
Examples
piiFound reports the concrete detectors that matched, not the names you
sent. Asking for the phone family comes back as phone_us or phone_intl
depending on what was in the text.Selective Redaction
Omitpii_types to redact the entities your policy is configured for, or pass a
subset to target specific types:
["email"] finds email even on a preset that would not normally scan
for it. It also governs api_key — leave that name out and API keys in the
text are left alone.
Reserved-domain addresses
An email at a domain reserved for documentation and testing is never redacted:example.com, example.net, example.org, and any domain ending in
.example, .test, .invalid or .localhost (RFC
2606 and RFC
6761). No such address can belong to
a person, and masking them corrupted text that quotes them, such as “our
support address is help@example.com”. The response says so in skipped, one
entry per address left:
jane.doe@acme-corp.com. The Guard API and the
MCP server’s promptguard_redact report the
same skipped. A match is reported only when its type was being redacted: a
call that asks for ["ssn"] reports no skipped email.
Guard API vs Scan vs Redact
Error Responses
Each code links to its entry in the error code reference througherror.doc_url.
429 body
The two quota-related 429s carryretry_after, and the response also sends a standard Retry-After header with the same value in seconds. On a plan sold in usage credit, monthly_quota_exceeded reports credit_usd, credit_used_usd and credit_remaining_usd, and requests_limit is null. It also carries on_demand_url: the link to raise your spend cap, on plans that sell overage; on Free it is absent and the message names only the upgrade. spending_limit_exceeded carries settings_url, where the cap is raised. The same body is returned by the proxy, /api/v1/guard and the ChatGPT app tools, which surface the dictionary as-is.
subscription_inactive has a different shape, because it is a different refusal:
requests_used / requests_limit: nothing was exceeded, and a
subscription can be refused this way with zero requests used. It carries no
retry_after, because waiting does not change it, and no on_demand_url:
raising a spend cap does not restore service on a subscription that has
ended. Reactivate the subscription.
A valid self-host licence removes the cap on
/api/v1/security/scan, /api/v1/security/redact and the ChatGPT app tools. Requests are still counted (the licence audit and true-up read the counter) but are never rejected with a 429.Security Testing (Red Team) Endpoints
Run a fixed corpus of known attacks against a named policy preset and report how much of it the policy blocks. This is the surface the CLI’spromptguard redteam and the SDK red-team
clients call, and the one to gate a CI job on.
X-API-Key header; the key needs the proxy scope
(the run spends engine time like a scan does). The same operations are
available to a dashboard session at /dashboard/security-testing/*, where
running tests also needs the Member role or higher in the organization.
Running tests is included from the Developer plan up. On the Free plan,
run-all, run-custom and run/{test_name} return 403 with the code
FEATURE_NOT_ENTITLED, and no tests run. GET /tests works on every plan.
Every run counts toward your plan’s usage: one request for each test prompt
it can send to the detection engine, with that prompt’s billed tokens (see
How Usage Is Calculated). A full run sends
each attack and its variations, so it counts dozens of requests. The prompts
are fixed before the run starts. Past your allowance, a run is refused with
the same 429 and error body as any other request, before any test runs.
Request Body
Response (run-all)
Errors
target_preset — including the bare
strict the CLI documents — was silently replaced with default:moderate,
and the report carried the name you sent. Every run made with a preset other
than default:moderate before that date was scored against default:moderate.
The 503 body uses the same envelope as the Guard API’s
detection_unavailable:
Report version 2
report_version was added on 2026-09-03 with value 2. There was never a
report_version: 1 on the wire; the number exists so a CI job can tell which
arithmetic it is reading if the meaning changes again.
Before version 2, a probe the engine could not complete was graded by the text
of the exception: a proxy error whose message contained “denied” scored as a
block, and a timeout scored as a discovered vulnerability. Neither was
a verdict. Version 2 reports such probes as decision: "error" with
errored: true, counts them in errored_count, and leaves them out of
total_tests and block_rate.
Scores can move in both directions as a result. A run that used to hit
proxy errors will report a lower block rate than before; a run that used to
time out will report a higher one. Neither number was measuring your policy.
If a CI job gates on this endpoint, gate on both numbers: fail when
block_rate is below your bar, and fail when errored_count is above zero
(or above a tolerance you choose), so “the scan did not complete” cannot pass
as “nothing got through”.
The red-team engine is a cloud feature; it is stripped from self-host images at build time. See Self-host vs cloud.