> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Check Guardrails
> Evaluate content or an agent action against configured safety guardrails and policy rules.
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
API key with `guardrails:check` scope. Alternatively, pass a Bearer JWT token
in the `Authorization` header.
Tenant identifier for multi-tenant isolation.
### Request
MAIP agent identifier requesting the guardrail check.
Text content to evaluate against content safety rules. Provide either
`content` or `action_type` (or both).
Action the agent intends to perform (e.g. `send_email`, `modify_record`,
`external_api_call`, `financial_transaction`). Evaluated against action-level
policy rules.
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
Whether the content/action is permitted. `true` if no violations were found,
`false` if any blocking violation was triggered.
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
Current circuit breaker state: `closed` (normal operation), `open` (deny-all
mode active), or `half_open` (recovery testing).
Total number of rules evaluated during the check.
Time taken to evaluate all rules in milliseconds.
## OpenAPI
````yaml mint-openapi.yaml POST /v1/guardrails/check
openapi: 3.0.3
info:
title: Truthlocks API
description: >
Truthlocks is a universal verification infrastructure for documents,
credentials, and digital assets.
This specification defines the canonical API for interacting with Truthlocks
services.
## Base URLs
- **Production**: `https://api.truthlocks.com`
- **Sandbox**: `https://sandbox-api.truthlocks.com`
## Authentication
- **API Keys**: Use `X-API-Key` header for machine-to-machine operations
- **Bearer Tokens**: Use `Authorization: Bearer ` for user-initiated
operations
## Tenant Identity
In production, tenant identity is derived from the authenticated context
(API key or JWT).
The `X-Tenant-ID` header is ignored in production to prevent spoofing.
version: 1.0.0
contact:
name: Truthlocks Support
url: https://truthlocks.com/support
email: support@truthlocks.com
servers:
- url: https://api.truthlocks.com
description: Production API
- url: https://sandbox-api.truthlocks.com
description: Sandbox Environment
security:
- APIKey: []
tags:
- name: Authentication
description: API key and token management
- name: Issuers
description: Issuer registration and trust management
- name: Keys
description: Cryptographic key management for issuers
- name: Attestations
description: Attestation lifecycle (mint, revoke, supersede)
- name: Verification
description: Attestation verification and proof bundles
- name: Governance
description: Issuer governance workflows (admin only)
- name: Identity
description: Organization, user, and role management
- name: Audit
description: Audit event queries
- name: Platform
description: Platform administration (super admin only)
- name: Platform Review
description: Staff review workflows for issuer applications
- name: Tenant Console
description: Tenant profile and lifecycle endpoints
- name: Health
description: Service health and readiness endpoints
- name: Risk
description: Risk signal ingestion and fraud detection
- name: Risk Enforcement
description: Risk enforcement actions — block, challenge, quarantine, and configuration
- name: Billing
description: Billing, subscription, and addon management
- name: Machine Identity
description: >-
Machine Agent Identity Protocol (MAIP) — agent registration, sessions,
trust, witness, compliance, orchestration, and observability
externalDocs:
description: Transparency read-only API (separate service spec)
url: >-
https://github.com/truthlocks/truthlock/blob/main/docs/transparency/openapi.yaml
paths:
/v1/guardrails/check:
post:
tags:
- Machine Identity
summary: Check Guardrail
description: >
Evaluates an agent action against a set of guardrail rules. Returns
whether
the action is allowed and any violations detected. A receipt is
generated
for auditability.
operationId: maip.guardrails.check
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- agent_id
- action
properties:
agent_id:
type: string
format: uuid
description: Agent requesting the action
action:
type: string
description: Action being evaluated (e.g. invoke_tool, access_data)
context:
type: object
additionalProperties: true
description: Contextual information for evaluation
rules:
type: array
items:
type: string
description: Specific rule IDs to evaluate (empty = all rules)
example:
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
responses:
'200':
description: Guardrail check result
content:
application/json:
schema:
$ref: '#/components/schemas/MaipGuardrailResult'
'400':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
security:
- APIKey: []
components:
schemas:
MaipGuardrailResult:
type: object
properties:
allowed:
type: boolean
violations:
type: array
items:
type: object
properties:
rule:
type: string
description:
type: string
severity:
type: string
enum:
- low
- medium
- high
- critical
receipt_id:
type: string
format: uuid
ErrorEnvelope:
type: object
required:
- code
- message
- http_status
properties:
code:
type: string
description: Machine-readable error code
enum:
- AUTH_REQUIRED
- AUTH_INVALID
- PERMISSION_DENIED
- TENANT_IDENTITY_UNVERIFIED
- NOT_FOUND
- VALIDATION_ERROR
- CONFLICT
- PAYLOAD_TOO_LARGE
- RATE_LIMIT_EXCEEDED
- QUOTA_EXCEEDED
- SERVICE_UNAVAILABLE
- INTERNAL_ERROR
message:
type: string
description: Human-readable error message
http_status:
type: integer
description: HTTP status code
retry_after_ms:
type: integer
description: Milliseconds to wait before retrying (for rate limits)
details:
type: object
description: Additional error context
example:
code: AUTH_REQUIRED
message: Authentication required
http_status: 401
securitySchemes:
APIKey:
type: apiKey
in: header
name: X-API-Key
description: API key for machine-to-machine authentication
````