ListGuardrails CreateGuardrail GetGuardrail UpdateGuardrail DeleteGuardrail TestGuardrail ListGuardrailEvents Request Parameters Guardrail Rule Detection Enforcement Enforcement Behavior Fallback Behavior

Guardrails

Define safety rules that monitor conversation content and enforce behavior like masking, modifying, rerouting, or flagging when violations are detected.

ListGuardrails
CreateGuardrail
GetGuardrail
UpdateGuardrail
DeleteGuardrail
TestGuardrail
ListGuardrailEvents
Request Parameters
Guardrail Rule
Detection
Enforcement
Enforcement Behavior
Fallback Behavior

ListGuardrails

Lists all guardrails in the workspace.

Input

Parameter	Type	Required
`nextToken`	string	No
`maxResults`	integer	No

Sample Request


await client.send(new ListGuardrailsCommand({}));

Output


{
  "items": [
    {
      "guardrailId": "g1a2b3c4-5678-90ab-cdef-1234567890ab",
      "name": "PII Filter",
      "trigger": "output",
      "description": "Masks personally identifiable information in bot responses",
      "active": true,
      "rules": [
        {
          "id": "r1a2b3c4-...",
          "name": "Email detection",
          "detection": { "method": "regex", "pattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}" },
          "enforcement": { "action": "mask", "behavior": {"maskText": "[REDACTED]" } },
          "active": true
        }
      ],
      "metadata": { "path": "/safety", "tags": ["pii"] },
      "createdAt": "2026-08-01T12:00:00.000Z",
      "updatedAt": "2026-08-01T12:00:00.000Z",
      "lastUpdatedBy": "ci-deploy-bot"
    }
  ]
}

Errors

ValidationException (400)
InternalServerException (500)

CreateGuardrail

Creates a new guardrail.

Input

Parameter	Type	Required
`name`	string	Yes
`rules`	array	Yes
`trigger`	string	Yes
`description`	string	No
`active`	boolean	No
`metadata`	object	No
`fallbackBehavior`	object	No

Sample Request


await client.send(new CreateGuardrailCommand({
  name: "PII Filter",
  trigger: "output",
  description: "Masks PII in bot responses",
  active: true,
  rules: [
    {
      name: "Email detection",
      detection: {
        method: "regex",
        pattern: "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
      },
      enforcement: {
        action: "mask",
        behavior: {maskText: "[REDACTED]"},
      },
      active: true,
    },
  ],
  metadata: { path: "/safety", tags: ["pii"] },
}));

Output


{
    "guardrailId": "g1a2b3c4-5678-90ab-cdef-1234567890ab",
    "name": "PII Filter",
    "trigger": "output",
    "description": "Masks PII in bot responses",
    "active": true,
    "rules": [
      {
        "id": "r1a2b3c4-...",
        "name": "Email detection",
        "detection": { "method": "regex", "pattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}" },
        "enforcement": { "action": "mask", "behavior": {"maskText": "[REDACTED]" } },
        "active": true
      }
    ],
    "metadata": { "path": "/safety", "tags": ["pii"] },
    "createdAt": "2026-08-01T12:00:00.000Z",
    "updatedAt": "2026-08-01T12:00:00.000Z",
    "lastUpdatedBy": "ci-deploy-bot"
}

Errors

ValidationException (400)
ConflictException (409)
InternalServerException (500)

GetGuardrail

Gets a single guardrail by ID.

Sample Request


await client.send(new GetGuardrailCommand({
  guardrailIdentifier: "g1a2b3c4-5678-90ab-cdef-1234567890ab"
}));

Input

Parameter	Type	Required
`guardrailIdentifier`	string	Yes

Output


{
    "guardrailId": "g1a2b3c4-5678-90ab-cdef-1234567890ab",
    "name": "PII Filter",
    "trigger": "output",
    "description": "Masks personally identifiable information in bot responses",
    "active": true,
    "rules": [
      {
        "id": "r1a2b3c4-...",
        "name": "Email detection",
        "detection": { "method": "regex", "pattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}" },
        "enforcement": { "action": "mask", "behavior": {"maskText": "[REDACTED]" } },
        "active": true
      }
    ],
    "metadata": { "path": "/safety", "tags": ["pii"] },
    "createdAt": "2026-08-01T12:00:00.000Z",
    "updatedAt": "2026-08-01T12:00:00.000Z",
    "lastUpdatedBy": "ci-deploy-bot"
}

Errors

ValidationException (400)
ResourceNotFoundException (404)
InternalServerException (500)

UpdateGuardrail

Updates an existing guardrail. Only include fields you want to change.

Input

Parameter	Type	Required
`guardrailIdentifier`	string	Yes
`name`	string	No
`rules`	array	No
`trigger`	string	No
`description`	string	No
`active`	boolean	No
`metadata`	object	No
`fallbackBehavior`	object	No

Sample Request


await client.send(new UpdateGuardrailCommand({
  guardrailIdentifier: "g1a2b3c4-5678-90ab-cdef-1234567890ab",
  name: "PII Filter",
  trigger: "output",
  description: "Updated - masks PII patterns",
  active: false,
  rules: [
    {
      name: "Email detection",
      detection: {
        method: "regex",
        pattern: "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}",
      },
      enforcement: {
        action: "mask",
        behavior: {maskText: "[REDACTED]"},
      },
      active: true,
    },
  ],
  metadata: { path: "/safety", tags: ["pii"] },
}));

Output


{
    "guardrailId": "g1a2b3c4-5678-90ab-cdef-1234567890ab",
    "name": "PII Filter",
    "trigger": "output",
    "description": "Updated - masks PII patterns",
    "active": false,
    "rules": [
      {
        "id": "r1a2b3c4-...",
        "name": "Email detection",
        "detection": { "method": "regex", "pattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}" },
        "enforcement": { "action": "mask", "behavior": {"maskText": "[REDACTED]" } },
        "active": true
      }
    ],
    "metadata": { "path": "/safety", "tags": ["pii"] },
    "createdAt": "2026-08-01T12:00:00.000Z",
    "updatedAt": "2026-08-01T12:00:00.000Z",
    "lastUpdatedBy": "ci-deploy-bot"
}

Errors

ResourceNotFoundException (404)
ValidationException (400)
InternalServerException (500)

DeleteGuardrail

Deletes a guardrail.

Input

Parameter	Type	Required
`guardrailIdentifier`	string	Yes

Sample Request


await client.send(new DeleteGuardrailCommand({
  guardrailIdentifier: "2be7442d-3cb4-4f45-940a-20335a339f70",
}));

Output

No response body.

Errors

ValidationException (400)
ResourceNotFoundException (404)
InternalServerException (500)

TestGuardrail

Tests a guardrail against sample input without affecting live conversations.

Input

Parameter	Type	Required
`guardrailIdentifier`	string	Yes
`input`	string	Yes
`trigger`	string	No

Sample Request


await client.send(new TestGuardrailCommand({
  guardrailIdentifier: created.guardrailId,
  input: "My email is john@example.com",
}));

Output


{
  "input": "My email is john@example.com",
  "processedInput": "My email is [REDACTED]",
  "output": "My email is [REDACTED]",
  "blocked": false,
  "terminalRuleId": null,
  "violations": [
    {
      "ruleId": "r1a2b3c4-...",
      "ruleName": "Email detection",
      "action": "mask",
      "behavior": {"maskText": "[REDACTED]" },
      "metadata": { "pattern": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}" },
      "latencyMs": 12
    }
  ]
}

Errors

ValidationException (400)
ResourceNotFoundException (404)
InternalServerException (500)

ListGuardrailEvents

Lists historical guardrail trigger events.

Input

Parameter	Type	Required
`startTimestamp`	string	Yes
`endTimestamp`	string	Yes
`guardrailIdentifier`	string	No
`behaviorType`	enum	No
`userId`	string	No
`applicationId`	string	No
`conversationId`	string	No
`languageCode`	enum	No
`ruleId`	string	No
`sortBy`	enum	No
`sortOrder`	enum	No
`timezone`	string	No

Sample Request


const now = new Date();
  const sevenDaysAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
  const events = await client.send(new ListGuardrailEventsCommand({
    startTimestamp: sevenDaysAgo.toISOString(),
    endTimestamp: now.toISOString(),
}));

Output


{
  "items": [
    {
      "timestamp": "2026-08-01T12:05:00.000Z",
      "applicationId": "05c3fcc2-...",
      "conversationId": "conv-uuid",
      "userId": "user-123",
      "guardrailId": "g1a2b3c4-...",
      "guardrailName": "PII Filter",
      "behaviorType": "mask",
      "ruleId": "r1a2b3c4-...",
      "ruleName": "Email detection",
      "originalResponse": "My email is john@example.com",
      "ruleOutput": "My email is [REDACTED]",
      "responseTime": 15.2
    }
  ]
}

Errors

ValidationException (400)
InternalServerException (500)

Request Parameters

guardrailIdentifier

Type: String

The guardrail ID used in Get, Update, Delete, and Test operations.

guardrailId

Type: String

The unique guardrail identifier (assigned on creation).

name

Type: String

Guardrail name. 1–100 characters.

trigger

Type: String

When to evaluate the guardrail. One of: input (check user messages), output (check bot responses).

description

Type: String

Guardrail description. Max 100 characters.

active

Type: Boolean

Whether the guardrail is active.

rules

Type: Array

List of rules (max 50). See Guardrail Rule.

fallbackBehavior

Type: Object

What to do if guardrail processing fails. See Fallback Behavior.

input

Type: String

Sample input text to test against the guardrail (TestGuardrail only).

metadata

Type: Object

Organizational metadata. See Common Types.

startTimestamp

Type: String

Start of time range for events (ISO 8601).

endTimestamp

Type: String

End of time range for events (ISO 8601).

behaviorType

Type: String

Filter events by enforcement action. One of: mask, modify, route, flag.

userId

Type: String

Filter events by end-user ID. Max 255 characters.

applicationId

Type: String

Filter events by application.

conversationId

Type: String

Filter events by conversation.

languageCode

Type: String

Filter events by language. See Common Types.

ruleId

Type: String

Filter events by a specific rule.

sortBy

Type: String

Sort events by field. timestamp.

sortOrder

Type: String

Sort direction: asc or desc.

timezone

Type: String

Timezone for the time range filter.

nextToken

Type: String

Pagination token. See Common Types.

maxResults

Type: Integer

Max items per page (1–500). See Common Types.

createdAt

Type: String

When the guardrail was created (ISO 8601).

updatedAt

Type: String

When the guardrail was last modified (ISO 8601).

lastUpdatedBy

Type: String

The identity of who last modified the guardrail.

Guardrail Rule

Field	Type	Required
`id`	string	No
`name`	string	Yes
`detection`	object	Yes
`enforcement`	object	Yes
`description`	string	No
`active`	boolean	No
`stateModifications`	array	No
`tags`	array	No

id

Type: String

Rule identifier. Server-generated if omitted on create.

name

Type: String

Rule name. Max 100 characters.

detection

Type: Object

How to detect violations. See Detection.

enforcement

Type: Object

What to do when triggered. See Enforcement.

description

Type: String

Rule description. Max 100 characters.

active

Type: Boolean

Whether this rule is active.

stateModifications

Type: Array

State changes to apply when the rule triggers.

tags

Type: Array

Analytics tags to apply when triggered: [{ "label": "tag_name" }].

Detection

Field	Type	Required
`method`	enum	Yes
`pattern`	string	No
`keywords`	array	No
`prompt`	string	No
`threshold`	float	No

method

Type: String

Detection method. One of: regex, keyword, llmJudge.

pattern

Type: String

Regex pattern (for regex method). Max 200 characters.

keywords

Type: Array

Keyword list (for keyword method). Max 200 keywords, each max 50 characters.

prompt

Type: String

LLM evaluation prompt (for llmJudge method). Max 4000 characters.

threshold

Type: Number

Confidence threshold for llmJudge detection (0–1).

Enforcement

Field	Type	Required
`action`	enum	Yes
`behavior`	object	No
`tags`	array	No

action

Type: String

What to do when the rule triggers. One of: mask, modify, route, flag.

behavior

Type: Object

Action-specific configuration. Provide the variant matching the action. See Enforcement Behavior.

tags

Type: Array

Tags to apply when triggered.

Enforcement Behavior

Fields depend on the enforcement action:

For mask or flag:


{ "maskChar": "*", "maskText": "[REDACTED]" }

maskChar: Single character to use for masking.

maskText: Text to replace matched content with. Max 50 characters.

For modify:


{ "message": "I can't help with that.", "prompt": "...", "flowId": "..." }

message: Static replacement message. Max 500 characters.

prompt: LLM prompt to generate a replacement. Max 1000 characters.

flowId: Flow to route to after modification.

For route:


{ "flowId": "EscalationFlow" }

flowId: Flow to route the conversation to (required).

Fallback Behavior

What to do if guardrail processing itself fails (e.g., LLM timeout).

type

Type: String

One of: continue (proceed without guardrail), routeToFlow (route to a safe flow).

flowId

Type: String

Flow to route to (required when type is routeToFlow).

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Flows

Knowledge Bases

Guardrails

Contents

ListGuardrails

Input

Sample Request

Output

Errors

CreateGuardrail

Input

Sample Request

Output

Errors

GetGuardrail

Sample Request

Input

Output

Errors

UpdateGuardrail

Input

Sample Request

Output

Errors

DeleteGuardrail

Input

Sample Request

Output

Errors

TestGuardrail

Input

Sample Request

Output

Errors

ListGuardrailEvents

Input

Sample Request

Output

Errors

Request Parameters

Request Parameters

Guardrail Rule

Detection

Enforcement

Enforcement Behavior

Fallback Behavior