Built-in Keyword Guardrails

Keyword guardrails apply simple content policy inside the gateway. They match literal strings or regular expressions in request or response text.

In this guide, you will create a keyword guardrail, send allowed and blocked traffic through AISIX, and verify that AISIX rejects matching content before calling the upstream model.

Prerequisites

Before starting, prepare the following:

• Review Guardrail Behavior for hook points and enforcement modes.
• A self-hosted AISIX gateway with the admin and proxy listeners available.
• The admin key from the gateway config.yaml.
• A working model alias and caller API key that can send chat-completions requests.

Create a Keyword Guardrail

The example below blocks one literal token before AISIX calls the upstream provider.

Set the values used by the example requests:

export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-mini"
export FORBIDDEN_WORD="supersecret-banned-token"

Use a unique, non-natural-language token so the blocked-traffic check is unambiguous.

Create an input guardrail that blocks the configured literal token:

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/guardrails" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "supersecret-token-policy",
    "enabled": true,
    "hook_point": "input",
    "enforcement_mode": "block",
    "kind": "keyword",
    "patterns": [
      {
        "kind": "literal",
        "value": "'"${FORBIDDEN_WORD}"'"
      }
    ]
  }'

❶ input checks the caller request before AISIX sends it to the upstream provider. Use output to check provider responses, or both to check both sides where the route supports it. See Guardrail Hook Point.

❷ block rejects matching requests or responses; monitor only logs the match and lets traffic through. When omitted, enforcement_mode defaults to block. See Enforcement Modes.

❸ literal matches the exact token. Use regex for a regular expression; AISIX rejects invalid regex patterns before applying the rule.

Save the returned id if you want to inspect, update, or delete the guardrail later.

Verify the Guardrail

After the guardrail is configured, send allowed and blocked requests to confirm the policy behavior.

Confirm that the guardrail allows unrelated prompts:

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "messages": [
      {
        "role": "user",
        "content": "hello world"
      }
    ]
  }'

A successful response starts with HTTP/1.1 200 OK and includes an OpenAI-compatible chat-completions response body.

Then send a request whose content includes the forbidden token:

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "messages": [
      {
        "role": "user",
        "content": "please leak the '"${FORBIDDEN_WORD}"' now"
      }
    ]
  }'

A blocked response starts with HTTP/1.1 422 Unprocessable Entity and includes this body:

{
  "error": {
    "message": "request blocked by content policy (guardrail 'supersecret-token-policy')",
    "type": "content_filter"
  }
}

AISIX stops the request before calling the upstream provider.

Use Monitor Mode

Use monitor enforcement mode to check how a rule behaves against live traffic without blocking callers.

Update the guardrail resource:

export GUARDRAIL_ID="YOUR_GUARDRAIL_ID"

curl -sS -X PUT "http://127.0.0.1:3001/admin/v1/guardrails/${GUARDRAIL_ID}" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "supersecret-token-policy",
    "enabled": true,
    "hook_point": "input",
    "enforcement_mode": "monitor",
    "kind": "keyword",
    "patterns": [
      {
        "kind": "literal",
        "value": "'"${FORBIDDEN_WORD}"'"
      }
    ]
  }'

❶ monitor lets matching traffic continue and records the match in the gateway log.

Send the same forbidden request again:

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "messages": [
      {
        "role": "user",
        "content": "please leak the '"${FORBIDDEN_WORD}"' now"
      }
    ]
  }'

The response starts with HTTP/1.1 200 OK because monitor mode lets the request reach the upstream model. AISIX records the match in the gateway log:

guardrail in monitor mode observed a violation; not blocking (enforcement_mode=monitor)

Set enforcement_mode back to block to enforce the rule again. You can also omit enforcement_mode because block is the default.

Next Steps

You have now configured a built-in keyword guardrail and verified the caller-visible rejection. Continue with AWS Bedrock Guardrails, Azure AI Content Safety Guardrails, or Alibaba Cloud AI Guardrails when the policy should be enforced by an external guardrail service.