SDKs & API
API reference
Every endpoint, request field, response shape, error code, and webhook event.
About 10 minutes hands-on
What this guide does not cover
- A reference, not a tutorial. It assumes you already have a working call.
- Documents the current stable surface. Endpoints marked beta or labs can change without a major version bump.
Endpoints
POST
/api/guard/inputGuard user input. Body: { message, userId?, sessionId?, metadata? }
POST
/api/guard/outputGuard AI output. Body: { aiResponse, sessionId?, metadata? }
POST
/api/guard/analyzeAnalyze text. Public, rate-limited per IP. Body: { text, direction }
GET
/api/badge/<slug>Public badge status. Returns monthly counts and last activity only.
Response Shape
JSON
{
"allowed": false,
"action": "BLOCK",
"decision": "BLOCK",
"riskScore": 85,
"riskTypes": ["PROMPT_INJECTION", "SYSTEM_PROMPT_LEAK_ATTEMPT"],
"reason": "Blocked because high-risk patterns were detected...",
"safeText": null,
"redactedText": null,
"findings": []
}decision is a normalized 4-value field (ALLOW | REDACT | BLOCK | HUMAN_REVIEW). The raw action is also available.
Risk Types
| Risk Type | Description | Severity |
|---|---|---|
| PROMPT_INJECTION | User attempts to override system instructions | HIGH |
| JAILBREAK | Attempt to bypass safety rules (developer mode, role-play) | HIGH |
| SYSTEM_PROMPT_LEAK_ATTEMPT | User asks the model to reveal its system prompt | CRITICAL |
| SYSTEM_PROMPT_LEAKAGE | Model output contains system prompt fragments | CRITICAL |
| PII_DETECTED | Personally identifiable information detected | MEDIUM |
| INDIA_PII_DETECTED | India-specific PII (Aadhaar, PAN, UPI) | HIGH |
| SECRET_DETECTED | API keys, tokens, or credentials detected | CRITICAL |
| UNSAFE_OUTPUT | Model output contains harmful or policy-violating content | HIGH |
| RATE_LIMIT | Per-minute or monthly usage limit exceeded | LOW |
| TOKEN_ABUSE | Unusual token usage pattern detected | MEDIUM |
Actions
ALLOWALLOW_WITH_REDACTIONREWRITEBLOCKHUMAN_REVIEW
Error Codes
| Code | Error | Description |
|---|---|---|
| 400 | validation_error | Payload failed validation |
| 401 | auth_error | Missing or invalid x-api-key |
| 403 | auth_error | API key inactive |
| 404 | not_found | Project, webhook, or badge does not exist |
| 409 | conflict | Signing secret no longer available; rotate to issue a new one |
| 429 | rate_limited | Per-minute or monthly limit hit. See Retry-After header |
| 500 | server_error | Unexpected failure (original details are not leaked) |
Webhook Events
guard.prompt_injection.blockedguard.jailbreak.detectedguard.secret.detectedguard.pii.redactedguard.system_prompt_leak.blockedguard.unsafe_output.blockedusage.limit.warningusage.limit.exceededWebhook Headers
x-soter-event— event namex-soter-timestamp— unix seconds at signing timex-soter-signature—t=...,v1=<hmac-sha256>