POST

/v1/guardrail/check

The primary guardrail evaluation endpoint. Submit an AI agent's proposed output for analysis. Returns a complete risk assessment including a numeric score, violation flags, and a redacted version of the text.

Base URL

https://api.guardrail.ai

Full Endpoint

POST /v1/guardrail/check

Authentication

All requests must include your API key as a Bearer token in the Authorization header.

header

Authorization: Bearer sk_your_api_key_here

⚠️ Never expose your API key in client-side code, public repositories, or logs. Treat it like a password.

Request Body

Send a JSON body with Content-Type: application/json.

Parameter	Type	Description
`agent_id`required	string	A unique identifier for the agent or service making the call. Used for telemetry and audit logs. Can be any alphanumeric string (max 64 chars).
`proposed_text`required	string	The raw text generated by your AI agent that needs to be evaluated. Maximum payload size is 32KB per request.

json (request body)

{
  "agent_id": "customer-support-v2",
  "proposed_text": "Based on your account, I can offer you a full $500 refund immediately."
}

Response Schema

On success, the API returns HTTP 200 with the following JSON body.

Field	Type	Description
`risk_score`	integer	0–100. Composite danger score. 0 = completely safe. 100 = maximum risk. Evaluated across all active detection modules.
`status`	string	One of: `approved` (score 0–30), `flagged` (score 31–69), or `rejected` (score 70–100). Use this for simple allow/block logic.
`flags`	string[]	Array of human-readable explanation strings. One entry per violation detected. Empty array if no violations found.
`redacted_text`	string	The original proposed_text with all sensitive data replaced by anonymized placeholders. Safe to log, store, and display.

json (response)

{
  "risk_score": 72,
  "status": "rejected",
  "flags": [
    "Financial commitment: unauthorized refund of $500 mentioned",
    "Brand safety: language may create false expectations with customer"
  ],
  "redacted_text": "Based on your account, I can offer you a full $*** refund immediately."
}

HTTP Error Codes

Code	Status	Cause
200	OK	Request evaluated successfully. Check risk_score and status in response body.
401	Unauthorized	API key is missing, invalid, or has been revoked.
402	Payment Required	Your credit balance is below $0.01. Top up via the billing dashboard.
422	Unprocessable Entity	Request body is malformed or missing required fields (agent_id or proposed_text).
429	Too Many Requests	Rate limit exceeded. Sandbox: 10 req/min. Startup/Scale: unlimited.
500	Internal Server Error	Unexpected server error. Retry after 10 seconds. Contact support if it persists.