Skip to main content
POST
/
v1
/
guardrails
/
check
Check Guardrail
curl --request POST \
  --url https://api.truthlocks.com/v1/guardrails/check \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "action": "invoke_tool",
  "context": {
    "tool_name": "database-query",
    "query": "SELECT * FROM users"
  },
  "rules": [
    "no-wildcard-queries",
    "pii-access-control"
  ]
}
'
{
  "allowed": true,
  "violations": [
    {
      "rule": "<string>",
      "description": "<string>",
      "severity": "low"
    }
  ],
  "receipt_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
Evaluates content or an agent action against the tenant’s configured safety guardrails. The guardrails engine checks the input against all applicable policy rules and returns a deterministic allow/deny decision with detailed violation information. Guardrail checks are designed for inline use within orchestration flows. They execute in under 50ms for most rule sets, enabling real-time safety enforcement without significant latency overhead.

​
Circuit Breaker

The guardrails system includes a circuit breaker that automatically escalates to deny-all mode when the violation rate exceeds a configurable threshold within a rolling window. The circuit_breaker_status field in the response indicates the current state.

​
Authentication

​
X-API-Key
string
required
API key with guardrails:check scope. Alternatively, pass a Bearer JWT token in the Authorization header.
​
X-Tenant-ID
string
required
Tenant identifier for multi-tenant isolation.

​
Request

​
agent_id
string
required
MAIP agent identifier requesting the guardrail check.
​
content
string
Text content to evaluate against content safety rules. Provide either content or action_type (or both).
​
action_type
string
Action the agent intends to perform (e.g. send_email, modify_record, external_api_call, financial_transaction). Evaluated against action-level policy rules.
​
context
object
Additional context for rule evaluation. May include: - orchestration_id (string) — Parent orchestration for audit linkage - step_name (string) — Current workflow step - target_resource (string) — Resource being acted upon - user_id (string) — End user associated with the action - Any custom key-value pairs referenced by policy rules

​
Response

​
allowed
boolean
Whether the content/action is permitted. true if no violations were found, false if any blocking violation was triggered.
​
violations
array
Array of rule violations found. Each violation contains: - rule_id (string) — Identifier of the triggered rule - severity (string) — Violation severity: info, warning, error, critical - message (string) — Human-readable description of the violation
​
circuit_breaker_status
string
Current circuit breaker state: closed (normal operation), open (deny-all mode active), or half_open (recovery testing).
​
evaluated_rules
integer
Total number of rules evaluated during the check.
​
evaluation_ms
number
Time taken to evaluate all rules in milliseconds.

Authorizations

​
X-API-Key
string
header
required

API key for machine-to-machine authentication

Body

application/json
​
agent_id
string<uuid>
required

Agent requesting the action

​
action
string
required

Action being evaluated (e.g. invoke_tool, access_data)

​
context
object

Contextual information for evaluation

​
rules
string[]

Specific rule IDs to evaluate (empty = all rules)

Response

Guardrail check result

​
allowed
boolean
​
violations
object[]
​
receipt_id
string<uuid>