Guardrails API

Guardrails are rules the AI Gateway applies to a model's requests: to the text sent to the model (input) and to what it returns (output). A rule can block the request, change the text (mask personal data, replace words, truncate) or only log what it found. Each rule is made from a template and carries that template's settings per direction. A model's guardrails are on or off as a whole; turning them off keeps their rules.

Guardrails apply to chat, completion and multimodal models. All endpoints require authentication via the X-API-Key header and the scope shown.

---

Templates

Template	Directions	What it does
pii-filter	input, output	Masks, blocks or logs personal data: SSNs, payment card numbers, emails, phone numbers, passport and driver's license numbers
data-leak-prevention	input, output	Stops sensitive identifiers leaving in responses (the PII detectors, usually on output)
toxicity-filter	input, output	Blocks, replaces or logs the toxic words, phrases and patterns you list
prompt-injection	input, output	Blocks, replaces or logs the injection phrases and patterns you list
content-filter	input, output	Blocks, replaces or logs the inappropriate words, phrases and patterns you list
profanity-filter	input, output	Replaces, blocks or logs the profanity you list
token-limit	input, output	Truncates or blocks text longer than a number of tokens or characters
rate-limiter	input	Limits requests to the model per minute, hour and day, per user or shared

Two more are listed with available: false and the reason: the gateway cannot enforce them yet (hallucination-detector, language-filter). A rule that names one is refused.

Rule Object

{
  "id": "rule-1",
  "template": "pii-filter",
  "name": "Mask personal data",
  "enabled": true,
  "priority": 1,
  "config": {
    "output": {
      "enabled": true, "action": "mask", "mask_type": "char", "mask_char": "*", "mask_length": "full",
      "detect_ssn": true, "detect_credit_card": true, "detect_email": true,
      "detect_phone": false, "detect_passport": false, "detect_drivers_license": false
    }
  }
}

Field	Type	Description
id	string	Your id for the rule, unique among the model's rules
template	string	An available template id
name	string	Its name
enabled	boolean	A disabled rule is kept and does nothing
priority	number	Lower runs first
config	object	The template's settings by direction (input, output, only those the template has); a rate limiter's settings are config itself

Settings

Every setting of a template is given, in snake_case as the gateway reads it; an unknown or missing setting is refused, naming it.

Templates	Settings
pii-filter, data-leak-prevention	enabled; action: mask, block or log; mask_type: char, uuid or labeled_uuid; mask_char (one character); mask_length: full or partial; detect_ssn, detect_credit_card, detect_email, detect_phone, detect_passport, detect_drivers_license (booleans; an enabled block detects at least one)
toxicity-filter, prompt-injection, content-filter, profanity-filter	enabled; keywords (words and phrases); regex_patterns; case_sensitive; action: block, modify (replace with replacement_text) or log; replacement_text (an enabled block has a keyword or a pattern)
token-limit	enabled; max_tokens and max_characters (positive whole numbers or null; an enabled block has one); action: truncate or block; truncation_message
rate-limiter	enabled; limits: { period: minute | hour | day, limit }, one per period; per_user (each user counted apart, or shared); burst_limit (or null); cooldown_minutes; error_message

---

GET /api/v1/ai-gateway/guardrails/templates

The templates, each with its id, name, category, directions, description, available and unavailableReason (null when available).

Scope: guardrails:read

Response 200 OK: every template, in one list.

---

GET /api/v1/ai-gateway/guardrails

The models whose requests guardrails can check, each with its guardrails, and the totals.

Scope: guardrails:read

Response 200 OK

{
  "data": {
    "models": [
      {
        "id": "2e4a85074d1cb2ea2d461843",
        "name": "Support Chat",
        "type": "third-party",
        "provider": "openai",
        "modelType": "chat",
        "status": "active",
        "canEdit": true,
        "guardrails": {
          "enabled": true, "rules": 2, "inputRules": 2, "outputRules": 1,
          "blocked24h": 3, "modified24h": 12, "logged24h": 0,
          "lastTriggered": "2026-10-11T08:12:00Z"
        }
      }
    ],
    "totals": { "protectedModels": 1, "rules": 2, "blocked24h": 3, "modified24h": 12, "logged24h": 0 },
    "since": "2026-10-10T09:00:00Z"
  },
  "meta": { "requestId": "req_abc123" }
}

The counts are of the last 24 hours (since). canEdit is whether you may change the model's guardrails.

---

GET /api/v1/ai-gateway/guardrails/statistics

What guardrails did across your models in the last 24 hours: protectedModels, rules, blocked24h, modified24h, logged24h and since.

Scope: guardrails:read

Response 200 OK

---

GET /api/v1/ai-gateway/models/:id/guardrails

A model's guardrails: modelId, enabled, its rules, updatedAt, updatedBy, and the model it belongs to.

Scope: guardrails:read

Parameter	Type	Required	Description
id	string	Yes	The model

Response 200 OK

---

PUT /api/v1/ai-gateway/models/:id/guardrails

Replace a model's guardrails with the state you give.

Scope: guardrails:write

Parameter	Type	Required	Description
id	string	Yes	The model

Request Body

Field	Type	Required	Description
enabled	boolean	Yes	Whether the guardrails are on
rules	array	Yes	Every rule the model is to have

A rule whose template is unknown or unavailable, or whose settings the template cannot apply, is refused with 400, naming the rule.

Response 200 OK: the model's guardrails, as GET shows them.

---

PATCH /api/v1/ai-gateway/models/:id/guardrails

Turn a model's guardrails on or off, keeping its rules.

Scope: guardrails:write

Parameter	Type	Required	Description
id	string	Yes	The model

Request Body

Field	Type	Required	Description
enabled	boolean	Yes	true to turn them on, false to turn them off

Response 200 OK: the model's guardrails.

---

POST /api/v1/ai-gateway/models/:id/guardrails/test

Run rules on a sample text exactly as the gateway applies them to requests, without a model call. Nothing is recorded. Use it to check rules before saving them. A rate limiter counts requests, not text, so it has no test (400).

Scope: guardrails:write

Parameter	Type	Required	Description
id	string	Yes	The model the rules are for

Request Body

Field	Type	Required	Description
input	string	Yes	The sample text
direction	string	Yes	input (sent to the model) or output (returned by it)
rules	array	Yes	The rules to run

Response 200 OK: blocked (whether the rules block the text), modified (whether they change it), output (the text after them) and events (each rule that fired, with its action and findings).

---

GET /api/v1/ai-gateway/models/:id/guardrail-logs

What a model's guardrails did, newest first: one record per request and direction in which a rule fired, with timestamp, userId, requestId, direction, blocked, modified and the events.

Scope: guardrails:read

Parameter	Type	Required	Description
id	string	Yes	The model
limit	integer	No	Results per page (default 50, at most 200)
cursor	string	No	meta.nextCursor of the previous page

Response 200 OK: a page of records, meta.nextCursor set while more remain.