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"
  ]
}
'
import requests

url = "https://api.truthlocks.com/v1/guardrails/check"

payload = {
    "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"]
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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']
  })
};

fetch('https://api.truthlocks.com/v1/guardrails/check', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.truthlocks.com/v1/guardrails/check",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.truthlocks.com/v1/guardrails/check"

	payload := strings.NewReader("{\n  \"agent_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"action\": \"invoke_tool\",\n  \"context\": {\n    \"tool_name\": \"database-query\",\n    \"query\": \"SELECT * FROM users\"\n  },\n  \"rules\": [\n    \"no-wildcard-queries\",\n    \"pii-access-control\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.truthlocks.com/v1/guardrails/check")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"action\": \"invoke_tool\",\n  \"context\": {\n    \"tool_name\": \"database-query\",\n    \"query\": \"SELECT * FROM users\"\n  },\n  \"rules\": [\n    \"no-wildcard-queries\",\n    \"pii-access-control\"\n  ]\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.truthlocks.com/v1/guardrails/check")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"action\": \"invoke_tool\",\n  \"context\": {\n    \"tool_name\": \"database-query\",\n    \"query\": \"SELECT * FROM users\"\n  },\n  \"rules\": [\n    \"no-wildcard-queries\",\n    \"pii-access-control\"\n  ]\n}"

response = http.request(request)
puts response.read_body
{
  "allowed": true,
  "violations": [
    {
      "rule": "<string>",
      "description": "<string>"
    }
  ],
  "receipt_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}
{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}
{
  "code": "AUTH_REQUIRED",
  "message": "Authentication required",
  "http_status": 401
}
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>