Skip to main content
API7.ai Logo

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.
  • One of these configuration paths:
    • AISIX Cloud with an environment, an attached gateway, and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
    • An open-source AISIX gateway that loads a declarative resources.yaml file.
  • A working model alias and caller API key that can send Chat Completions requests.
  • curl. The AISIX Cloud path also uses jq.

Create a Keyword Guardrail​

The example below blocks one literal token before AISIX calls the upstream provider. Choose one configuration path, then use the shared verification procedure.

Export the gateway values used by both paths:

# AISIX_PROXY has no trailing slash or endpoint path.
# The local quickstarts use http://127.0.0.1:3000.
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
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 marker so the blocked-traffic check is unambiguous.

AISIX Cloud​

Export the control-plane connection details:

# AISIX_CP includes /api and has no trailing slash.
# The local On-Premises quickstart uses http://localhost:8080/api.
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_BASE_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

Create an input guardrail that blocks the configured literal token, and capture its ID for later steps:

export GUARDRAIL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/guardrails" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "supersecret-token-policy",
    "enabled": false,
    "hook_point": "input",
    "enforcement_mode": "block",
    "kind": "keyword",
    "config": {
      "patterns": [
        {
          "kind": "literal",
          "value": "'"${FORBIDDEN_WORD}"'"
        }
      ]
    }
  }' | jq -r '.guardrail.id')

❶ Creating the guardrail disabled prevents it from applying globally before its attachment exists. Enable it after attaching it below.

❷ 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 records the match and lets traffic through. When omitted, enforcement_mode defaults to block. See Enforcement Modes.

❹ literal matches whenever the configured text appears, regardless of case. Use regex for a Rust-compatible regular expression; an invalid expression prevents the guardrail from entering the active chain.

Attach the guardrail to the whole environment:

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/guardrails/$GUARDRAIL_ID/attachments" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope_type": "env"
  }'

The env scope applies the guardrail to all traffic in the environment and takes no scope_id. Use model, api_key, or team with a matching scope_id to narrow the attachment.

Enable the guardrail after its attachment exists:

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/guardrails/$GUARDRAIL_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

The enabled configuration projects to attached gateways automatically.

Open-Source AISIX Gateway​

Add the guardrail to the resources file that already defines the example model and caller API key:

resources.yaml
guardrails:
  - name: supersecret-token-policy
    enabled: true
    hook_point: input
    enforcement_mode: block
    kind: keyword
    patterns:
      - kind: literal
        value: supersecret-banned-token

❶ input checks the caller request before AISIX sends it to the upstream provider.

❷ block rejects matching requests. It is also the default when enforcement_mode is omitted.

❸ Keep the literal value aligned with FORBIDDEN_WORD so the verification request triggers the guardrail. Literal matching is case-insensitive. Use regex instead when the policy needs a Rust-compatible regular expression.

Every enabled guardrail in resources.yaml applies to every request handled by that gateway. Validate the complete file, then reload the gateway. See Reload a Resources File for the runnable Docker workflow.

Verify the Guardrail​

After the guardrail is configured, send allowed and blocked requests to confirm the policy behavior. AISIX Cloud projection is asynchronous; if the first request does not reflect the new rule, wait for the gateway to apply the latest revision and retry. See Resource Projection for convergence checks.

Confirm that the guardrail allows unrelated prompts:

curl -sSi -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "model": "${AISIX_MODEL}",
    "messages": [
      {
        "role": "user",
        "content": "hello world"
      }
    ]
  }
EOF

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 "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "model": "${AISIX_MODEL}",
    "messages": [
      {
        "role": "user",
        "content": "please leak the ${FORBIDDEN_WORD} now"
      }
    ]
  }
EOF

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.

AISIX Cloud​

Update the guardrail resource through the Admin API:

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/guardrails/$GUARDRAIL_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enforcement_mode": "monitor"
  }'

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

Open-Source AISIX Gateway​

Change the guardrail's enforcement mode in resources.yaml:

resources.yaml
guardrails:
  - name: supersecret-token-policy
    enabled: true
    hook_point: input
    enforcement_mode: monitor
    kind: keyword
    patterns:
      - kind: literal
        value: supersecret-banned-token

Validate the complete file and reload the gateway before sending the request again.

Verify Monitor Mode​

Send the same forbidden request again:

curl -sSi -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "model": "${AISIX_MODEL}",
    "messages": [
      {
        "role": "user",
        "content": "please leak the ${FORBIDDEN_WORD} now"
      }
    ]
  }
EOF

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 through the same configuration path 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. Use these guides to refine or expand the policy: