Get Guardrail by ID

GET /admin/v1/guardrails/{id}

Interactive request editor loads with JavaScript.

Authorization

AdminBearer

AuthorizationBearer <token>

Admin key from config.admin.admin_keys.

In: header

Path Parameters

id*string

Guardrail resource ID, as assigned by the active resource source (a UUIDv5 derived from the entry name in file mode; the etcd key's ID segment otherwise).

Response Body

`application/json`

curl -X GET "http://127.0.0.1:3001/admin/v1/guardrails/b0c04774-216f-4fb2-96f0-5f7f0a75b76a"

{
  "id": "string",
  "revision": 0,
  "value": {
    "created_at": "2019-08-24T14:15:22Z",
    "direction": "both",
    "enabled": true,
    "enforcement_mode": "block",
    "fail_open": false,
    "hook_point": "both",
    "kind": "keyword",
    "name": "string",
    "patterns": [
      {
        "kind": "literal",
        "value": "string"
      }
    ]
  }
}

Missing or invalid admin key

{
  "error_msg": "string"
}

Resource not found

{
  "error_msg": "string"
}

Configuration store operation failed

{
  "error_msg": "string"
}

Complete operation details and schema variants

GET /admin/v1/guardrails/{id}

Get Guardrail by ID

Get a guardrail resource by ID.

Parameters

id (path, string, required): Guardrail resource ID, as assigned by the active resource source (a UUIDv5 derived from the entry name in file mode; the etcd key's ID segment otherwise).

Responses

200: OK
id (string, required): Resource ID, as assigned by the active resource source.
revision (integer, required): Monotonic resource revision: the etcd mod_revision of the entry, or the load generation in file mode.
value (object, required): Stored guardrail configuration.
allOf variant 1
value.created_at (string, optional): RFC3339 creation timestamp. When present, guardrails are evaluated from oldest to newest. Resources without this timestamp sort after resources that have it.
value.direction (string, optional): Attachment direction hint. Guardrail execution still follows hook_point.
value.enabled (boolean, optional): When false, the chain skips this rule entirely. Allows operators to stage a rule before enabling it.
value.enforcement_mode (string, optional): How AISIX handles matching content. Enforcing mode applies the guardrail verdict; monitor mode records what would have happened without blocking or redacting the caller-visible response.
value.fail_open (boolean, optional): Behavior when this guardrail cannot complete its check. Two causes: a remote provider that is unreachable, timing out, throttling, or rejecting the call; and a body the gateway could not give the guardrail at all — one that does not decode as UTF-8 or does not parse, which the proxy would otherwise refuse with unscannable_body. true allows the request; false (the default) blocks with 422.

Both causes apply to EVERY kind: the second one is the gateway failing to produce scannable text, which happens before any guardrail runs and so reaches all of them. keyword and pii never call out, so only the second can arise for them; a kind that calls out can meet either.

The per-hook split follows the same line. A kind that calls out carries its own output_fail_open for the output hook, leaving this field to govern the input hook. keyword and pii have no output_fail_open, so this one value governs both of their hooks.

Defaults to fail-closed so an unchecked request is never released on the strength of a guardrail that did not run: an operator who prefers availability over enforcement opts in explicitly. This matches output_fail_open and on_buffer_exceeded, which have always defaulted closed (AISIX-Cloud#1382).

value.hook_point (object, optional): Where in the lifecycle this rule runs.
allOf variant 1
oneOf variant 1: Input
oneOf variant 2: Output
oneOf variant 3: Both
value.name (string, required): Operator-facing name that surfaces in metric labels and error reasons.
oneOf variant 1: Keyword
value.created_at (string, optional): RFC3339 creation timestamp. When present, guardrails are evaluated from oldest to newest. Resources without this timestamp sort after resources that have it.
value.direction (string, optional): Attachment direction hint. Guardrail execution still follows hook_point.
value.enabled (boolean, optional): When false, the chain skips this rule entirely. Allows operators to stage a rule before enabling it.
value.enforcement_mode (string, optional): How AISIX handles matching content. Enforcing mode applies the guardrail verdict; monitor mode records what would have happened without blocking or redacting the caller-visible response.
value.fail_open (boolean, optional): Behavior when this guardrail cannot complete its check. Two causes: a remote provider that is unreachable, timing out, throttling, or rejecting the call; and a body the gateway could not give the guardrail at all — one that does not decode as UTF-8 or does not parse, which the proxy would otherwise refuse with unscannable_body. true allows the request; false (the default) blocks with 422.

value.hook_point (object, optional): Where in the lifecycle this rule runs.
allOf variant 1
oneOf variant 1: Input
oneOf variant 2: Output
oneOf variant 3: Both
value.kind (string, required): Guardrail provider type for literal and regular expression matching.
value.name (string, optional): Operator-facing name that surfaces in metric labels and error reasons.
value.patterns (array, required): Blocklist patterns. An empty list is valid and allows every request, equivalent to enabled: false.
oneOf variant 1: Literal
value.patterns[].kind (string, required): Pattern type for matching the value as plain text.
value.patterns[].value (string, required): Literal string to match.
oneOf variant 2: Regex
value.patterns[].kind (string, required): Pattern type for matching the value as a regular expression.
value.patterns[].value (string, required): Regular expression pattern to match.
oneOf variant 2: AWS Bedrock
value.aws_credentials (object, required): IAM credentials for Bedrock requests.
allOf variant 1
oneOf variant 1: Static credentials
value.aws_credentials.access_key_id (string, required): AWS access key ID for static Bedrock guardrail credentials.
value.aws_credentials.kind (string, required): Credential mode for explicitly configured AWS access keys.
value.aws_credentials.secret_access_key (string, required): AWS secret access key used to authenticate requests to Amazon Bedrock. The gateway does not log the plaintext value.
value.created_at (string, optional): RFC3339 creation timestamp. When present, guardrails are evaluated from oldest to newest. Resources without this timestamp sort after resources that have it.
value.direction (string, optional): Attachment direction hint. Guardrail execution still follows hook_point.
value.enabled (boolean, optional): When false, the chain skips this rule entirely. Allows operators to stage a rule before enabling it.
value.enforcement_mode (string, optional): How AISIX handles matching content. Enforcing mode applies the guardrail verdict; monitor mode records what would have happened without blocking or redacting the caller-visible response.
value.fail_open (boolean, optional): Behavior when this guardrail cannot complete its check. Two causes: a remote provider that is unreachable, timing out, throttling, or rejecting the call; and a body the gateway could not give the guardrail at all — one that does not decode as UTF-8 or does not parse, which the proxy would otherwise refuse with unscannable_body. true allows the request; false (the default) blocks with 422.

value.guardrail_id (string, required): Guardrail identifier issued by the AWS console.
value.guardrail_version (string, required): Version label: DRAFT, 1, 2, ...
value.hook_point (object, optional): Where in the lifecycle this rule runs.
allOf variant 1
oneOf variant 1: Input
oneOf variant 2: Output
oneOf variant 3: Both
value.kind (string, required): Guardrail provider type for Amazon Bedrock Guardrails.
value.latency_mode (object, required): Bedrock guardrail latency policy. Timed mode caps wait time with timeout_ms.
allOf variant 1
oneOf variant 1: Serial
value.latency_mode.kind (string, required): Latency mode that waits for the Bedrock guardrail response.
oneOf variant 2: Timed
value.latency_mode.kind (string, required): Latency mode that stops waiting after timeout_ms.
value.latency_mode.timeout_ms (integer, required): Maximum time in milliseconds to wait for the Bedrock guardrail response.
value.name (string, optional): Operator-facing name that surfaces in metric labels and error reasons.
value.output_fail_open (boolean, optional): Fail-open policy for the output hook. When disabled (the default), a Bedrock outage blocks model output instead of releasing unscanned content. The input hook continues to use the top-level fail_open policy.
value.region (string, required): AWS region for the Bedrock endpoint, such as us-east-1.
oneOf variant 3: Azure AI Content Safety Prompt Shield
value.api_key (string, required): Azure subscription key sent with the Ocp-Apim-Subscription-Key header. Decrypted before projection. Plaintext is held in memory only and is not logged.
value.created_at (string, optional): RFC3339 creation timestamp. When present, guardrails are evaluated from oldest to newest. Resources without this timestamp sort after resources that have it.
value.direction (string, optional): Attachment direction hint. Guardrail execution still follows hook_point.
value.enabled (boolean, optional): When false, the chain skips this rule entirely. Allows operators to stage a rule before enabling it.
value.endpoint (string, required): Azure Cognitive Services resource endpoint, e.g. https://my-resource.cognitiveservices.azure.com. The gateway appends /contentsafety/text:shieldPrompt?api-version=2024-09-01.
value.enforcement_mode (string, optional): How AISIX handles matching content. Enforcing mode applies the guardrail verdict; monitor mode records what would have happened without blocking or redacting the caller-visible response.
value.fail_open (boolean, optional): Behavior when this guardrail cannot complete its check. Two causes: a remote provider that is unreachable, timing out, throttling, or rejecting the call; and a body the gateway could not give the guardrail at all — one that does not decode as UTF-8 or does not parse, which the proxy would otherwise refuse with unscannable_body. true allows the request; false (the default) blocks with 422.

value.hook_point (object, optional): Where in the lifecycle this rule runs.
allOf variant 1
oneOf variant 1: Input
oneOf variant 2: Output
oneOf variant 3: Both
value.kind (string, required): Guardrail provider type for Azure Prompt Shield.
value.name (string, optional): Operator-facing name that surfaces in metric labels and error reasons.
value.output_fail_open (boolean, optional): Fail-open policy for the output hook. When disabled (the default), an Azure outage blocks model output instead of releasing unscanned content. The input hook continues to use the top-level fail_open policy.
value.timeout_ms (integer, optional): HTTP call timeout in milliseconds. A value of 0 triggers the timeout immediately.
oneOf variant 4: Azure AI Content Safety Text Moderation
value.api_key (string, required): Azure subscription key sent with the Ocp-Apim-Subscription-Key header. Plaintext is held in memory only and is not logged.
value.blocklist_names (array, optional): Azure CS blocklist names to match against.
value.categories (array, optional): Categories to analyze.
value.created_at (string, optional): RFC3339 creation timestamp. When present, guardrails are evaluated from oldest to newest. Resources without this timestamp sort after resources that have it.
value.direction (string, optional): Attachment direction hint. Guardrail execution still follows hook_point.
value.enabled (boolean, optional): When false, the chain skips this rule entirely. Allows operators to stage a rule before enabling it.
value.endpoint (string, required): Azure Cognitive Services resource endpoint. The gateway appends /contentsafety/text:analyze?api-version=2024-09-01.
value.enforcement_mode (string, optional): How AISIX handles matching content. Enforcing mode applies the guardrail verdict; monitor mode records what would have happened without blocking or redacting the caller-visible response.
value.fail_open (boolean, optional): Behavior when this guardrail cannot complete its check. Two causes: a remote provider that is unreachable, timing out, throttling, or rejecting the call; and a body the gateway could not give the guardrail at all — one that does not decode as UTF-8 or does not parse, which the proxy would otherwise refuse with unscannable_body. true allows the request; false (the default) blocks with 422.

value.halt_on_blocklist_hit (boolean, optional): Forwarded to Azure's haltOnBlocklistHit.
value.hook_point (object, optional): Where in the lifecycle this rule runs.
allOf variant 1
oneOf variant 1: Input
oneOf variant 2: Output
oneOf variant 3: Both
value.kind (string, required): Guardrail provider type for Azure text moderation.
value.max_buffer_bytes (integer, optional): Max bytes buffered in buffer_full mode before on_buffer_exceeded applies.
value.name (string, optional): Operator-facing name that surfaces in metric labels and error reasons.
value.on_buffer_exceeded (string, optional): Buffer-overflow policy for streamed output when the buffer cap is hit.
value.output_fail_open (boolean, optional): Fail-open policy for the output hook. When disabled, an Azure outage does not release unscanned model output.
value.output_type (string, optional): Severity scale used for Azure category scores. The four-level scale returns even severities; the eight-level scale returns every integer severity.
value.severity_threshold (integer, optional): General severity threshold. A category at or above it blocks.
value.severity_threshold_by_category (object, optional): Per-category threshold overrides. These take precedence over the general threshold.
value.stream_processing_mode (string, optional): Streaming output moderation mode: sliding-window incremental release or whole-response hold-back.
value.text_source (string, optional): Input-hook text selection. The default scans user messages only; the alternate mode includes all message content. Ignored on the output hook.
value.timeout_ms (integer, optional): HTTP call timeout in milliseconds. fail_open and output_fail_open govern the verdict when it elapses. A value of 0 triggers the timeout immediately.
value.window_overlap_size (integer, optional): Chars carried between windows so a span split across a boundary is still caught.
value.window_size (integer, optional): Sliding-window size in characters for window mode.
oneOf variant 5: Aliyun Text Moderation
value.access_key_id (string, required): Aliyun AccessKey ID.
value.access_key_secret (string, required): Aliyun AccessKey secret. Decrypted before projection. Plaintext is held in memory only and is not logged. Used to sign the request.
value.created_at (string, optional): RFC3339 creation timestamp. When present, guardrails are evaluated from oldest to newest. Resources without this timestamp sort after resources that have it.
value.direction (string, optional): Attachment direction hint. Guardrail execution still follows hook_point.
value.enabled (boolean, optional): When false, the chain skips this rule entirely. Allows operators to stage a rule before enabling it.
value.endpoint (string, optional): Explicit endpoint override as a full URL with no trailing slash. When set, it takes precedence over region.
value.enforcement_mode (string, optional): How AISIX handles matching content. Enforcing mode applies the guardrail verdict; monitor mode records what would have happened without blocking or redacting the caller-visible response.
value.fail_open (boolean, optional): Behavior when this guardrail cannot complete its check. Two causes: a remote provider that is unreachable, timing out, throttling, or rejecting the call; and a body the gateway could not give the guardrail at all — one that does not decode as UTF-8 or does not parse, which the proxy would otherwise refuse with unscannable_body. true allows the request; false (the default) blocks with 422.

value.hook_point (object, optional): Where in the lifecycle this rule runs.
allOf variant 1
oneOf variant 1: Input
oneOf variant 2: Output
oneOf variant 3: Both
value.kind (string, required): Guardrail provider type for Aliyun text moderation.
value.max_buffer_bytes (integer, optional): Max bytes buffered in buffer_full mode before on_buffer_exceeded applies.
value.name (string, optional): Operator-facing name that surfaces in metric labels and error reasons.
value.on_buffer_exceeded (string, optional): Buffer-overflow policy for streamed output when the buffer cap is hit.
value.output_fail_open (boolean, optional): Fail-open policy for the output hook. When disabled, an Aliyun outage does not release unscanned model output.
value.region (string, required): Aliyun region the guardrail lives in, e.g. cn-shanghai. The gateway builds the endpoint https://green-cip.<region>.aliyuncs.com.
value.risk_level_threshold (string, optional): Minimum risk level that triggers a block. A returned level at or above this threshold blocks.
value.stream_processing_mode (string, optional): Streaming output moderation mode: sliding-window incremental release or whole-response hold-back.
value.timeout_ms (integer, optional): HTTP call timeout in milliseconds. fail_open and output_fail_open govern the verdict when it elapses. A value of 0 triggers the timeout immediately.
value.window_overlap_size (integer, optional): Chars carried between windows so a span split across a boundary is still caught.
value.window_size (integer, optional): Sliding-window size in characters when window mode is used. Aliyun limits each llm_response_moderation call to 2,000 characters.
oneOf variant 6: Aliyun AI Guardrails
value.access_key_id (string, required): Aliyun AccessKey ID.
value.access_key_secret (string, required): Aliyun AccessKey secret. Decrypted before projection. Plaintext is held in memory only and is not logged. Used to sign the request.
value.created_at (string, optional): RFC3339 creation timestamp. When present, guardrails are evaluated from oldest to newest. Resources without this timestamp sort after resources that have it.
value.direction (string, optional): Attachment direction hint. Guardrail execution still follows hook_point.
value.enabled (boolean, optional): When false, the chain skips this rule entirely. Allows operators to stage a rule before enabling it.
value.endpoint (string, optional): Explicit endpoint override as a full URL with no trailing slash. When set, it takes precedence over region.
value.enforcement_mode (string, optional): How AISIX handles matching content. Enforcing mode applies the guardrail verdict; monitor mode records what would have happened without blocking or redacting the caller-visible response.
value.fail_open (boolean, optional): Behavior when this guardrail cannot complete its check. Two causes: a remote provider that is unreachable, timing out, throttling, or rejecting the call; and a body the gateway could not give the guardrail at all — one that does not decode as UTF-8 or does not parse, which the proxy would otherwise refuse with unscannable_body. true allows the request; false (the default) blocks with 422.

value.hook_point (object, optional): Where in the lifecycle this rule runs.
allOf variant 1
oneOf variant 1: Input
oneOf variant 2: Output
oneOf variant 3: Both
value.kind (string, required): Guardrail provider type for Aliyun AI Guardrails policy-driven moderation.
value.max_buffer_bytes (integer, optional): Max bytes buffered in buffer_full mode before on_buffer_exceeded applies.
value.name (string, optional): Operator-facing name that surfaces in metric labels and error reasons.
value.on_buffer_exceeded (string, optional): Buffer-overflow policy for streamed output when the buffer cap is hit.
value.output_fail_open (boolean, optional): Fail-open policy for the output hook. When disabled, an Aliyun outage does not release unscanned model output.
value.region (string, required): Aliyun region the guardrail lives in, e.g. cn-shanghai. The gateway builds the endpoint https://green-cip.<region>.aliyuncs.com.
value.service_level (string, optional): Which AI Guardrails service tier to call: pro uses query_security_check_pro / response_security_check_pro, basic uses query_security_check / response_security_check. Must match the tier activated on the Aliyun account.
value.stream_processing_mode (string, optional): Streaming output moderation mode: sliding-window incremental release or whole-response hold-back.
value.timeout_ms (integer, optional): HTTP call timeout in milliseconds. fail_open and output_fail_open govern the verdict when it elapses. A value of 0 triggers the timeout immediately.
value.window_overlap_size (integer, optional): Chars carried between windows so a span split across a boundary is still caught.
value.window_size (integer, optional): Sliding-window size in characters when window mode is used. Aliyun limits each MultiModalGuard call to 2,000 characters of text.
oneOf variant 7: PII Detection and Redaction
value.created_at (string, optional): RFC3339 creation timestamp. When present, guardrails are evaluated from oldest to newest. Resources without this timestamp sort after resources that have it.
value.custom_patterns (array, optional): Operator-supplied regex detectors, evaluated after the built-ins.
value.custom_patterns[].action (string, optional): Per-pattern action override. Falls back to the guardrail's default_action when omitted.
value.custom_patterns[].name (string, required): Detector name surfaced in the mask token ([<NAME>_REDACTED]), telemetry counts, and block reasons. Never the matched value.
value.custom_patterns[].regex (string, required): Regular expression AISIX compiles when building the guardrail chain. An invalid pattern makes AISIX log and skip the guardrail.

When the expression declares at least one capture group, a mask action rewrites only the first capture group of each match and keeps the rest of the match unchanged. Use this to replace a value while preserving its surrounding key or label, for example "version"\s*:\s*"([^"]*)". Without capture groups, the whole match is rewritten.

value.custom_patterns[].replacement (string, optional): Literal text that replaces the masked span, such as ***. When omitted, the span is rewritten to [<NAME>_REDACTED]. An empty string removes the span. Only valid when the pattern's effective action is mask.
value.default_action (string, optional): Action for detectors that do not set their own override.
value.detectors (array, optional): Built-in detectors to enable. The resource schema rejects unknown detector ids, so a typo cannot silently disable the policy.
value.detectors[].action (string, optional): Per-detector action override. Falls back to the guardrail's default_action when omitted.
value.detectors[].type (string, required): Built-in detector to enable for this PII guardrail entry.
value.direction (string, optional): Attachment direction hint. Guardrail execution still follows hook_point.
value.enabled (boolean, optional): When false, the chain skips this rule entirely. Allows operators to stage a rule before enabling it.
value.enforcement_mode (string, optional): How AISIX handles matching content. Enforcing mode applies the guardrail verdict; monitor mode records what would have happened without blocking or redacting the caller-visible response.
value.fail_open (boolean, optional): Behavior when this guardrail cannot complete its check. Two causes: a remote provider that is unreachable, timing out, throttling, or rejecting the call; and a body the gateway could not give the guardrail at all — one that does not decode as UTF-8 or does not parse, which the proxy would otherwise refuse with unscannable_body. true allows the request; false (the default) blocks with 422.

value.hook_point (object, optional): Where in the lifecycle this rule runs.
allOf variant 1
oneOf variant 1: Input
oneOf variant 2: Output
oneOf variant 3: Both
value.kind (string, required): Guardrail provider type for in-process sensitive-data detection and redaction.
value.max_buffer_bytes (integer, optional): Max bytes buffered for a streamed response before on_buffer_exceeded applies.
value.name (string, optional): Operator-facing name that surfaces in metric labels and error reasons.
value.on_buffer_exceeded (string, optional): Buffer-overflow policy for streamed output when the buffer cap is hit.
oneOf variant 8: Lakera Guard
value.api_key (string, required): Lakera API key sent as a Authorization: Bearer header. Decrypted before projection. Plaintext is held in memory only and is not logged.
value.created_at (string, optional): RFC3339 creation timestamp. When present, guardrails are evaluated from oldest to newest. Resources without this timestamp sort after resources that have it.
value.direction (string, optional): Attachment direction hint. Guardrail execution still follows hook_point.
value.enabled (boolean, optional): When false, the chain skips this rule entirely. Allows operators to stage a rule before enabling it.
value.endpoint (string, optional): Endpoint override, e.g. a regional or self-hosted Lakera deployment. The gateway appends /v2/guard. Defaults to https://api.lakera.ai.
value.enforcement_mode (string, optional): How AISIX handles matching content. Enforcing mode applies the guardrail verdict; monitor mode records what would have happened without blocking or redacting the caller-visible response.
value.fail_open (boolean, optional): Behavior when this guardrail cannot complete its check. Two causes: a remote provider that is unreachable, timing out, throttling, or rejecting the call; and a body the gateway could not give the guardrail at all — one that does not decode as UTF-8 or does not parse, which the proxy would otherwise refuse with unscannable_body. true allows the request; false (the default) blocks with 422.

value.hook_point (object, optional): Where in the lifecycle this rule runs.
allOf variant 1
oneOf variant 1: Input
oneOf variant 2: Output
oneOf variant 3: Both
value.kind (string, required): Guardrail provider type for Lakera Guard screening.
value.max_buffer_bytes (integer, optional): Max bytes buffered for a streamed response before on_buffer_exceeded applies.
value.name (string, optional): Operator-facing name that surfaces in metric labels and error reasons.
value.on_buffer_exceeded (string, optional): Buffer-overflow policy for streamed output when the buffer cap is hit.
value.output_fail_open (boolean, optional): Fail-open policy for the output hook. When disabled (the default), a Lakera outage blocks model output instead of releasing unscanned content. The input hook continues to use the top-level fail_open policy.
value.project_id (string, optional): Lakera project whose policy applies (project-...). Omitted → the account's default policy.
value.timeout_ms (integer, optional): HTTP call timeout in milliseconds. fail_open and output_fail_open govern the verdict when it elapses. A value of 0 triggers the timeout immediately.
oneOf variant 9: OpenAI Moderation
value.api_key (string, required): OpenAI API key sent as a Authorization: Bearer header. Decrypted before projection. Plaintext is held in memory only and is not logged.
value.category_thresholds (object, optional): Per-category score thresholds, e.g. {"violence": 0.5}. When set, only the listed categories are enforced and a category blocks when its score reaches the threshold. When empty (the default), the provider's flagged decision determines whether to block.
value.created_at (string, optional): RFC3339 creation timestamp. When present, guardrails are evaluated from oldest to newest. Resources without this timestamp sort after resources that have it.
value.direction (string, optional): Attachment direction hint. Guardrail execution still follows hook_point.
value.enabled (boolean, optional): When false, the chain skips this rule entirely. Allows operators to stage a rule before enabling it.
value.endpoint (string, optional): Endpoint override, such as an Azure OpenAI deployment. AISIX appends /moderations. Defaults to https://api.openai.com/v1.
value.enforcement_mode (string, optional): How AISIX handles matching content. Enforcing mode applies the guardrail verdict; monitor mode records what would have happened without blocking or redacting the caller-visible response.
value.fail_open (boolean, optional): Behavior when this guardrail cannot complete its check. Two causes: a remote provider that is unreachable, timing out, throttling, or rejecting the call; and a body the gateway could not give the guardrail at all — one that does not decode as UTF-8 or does not parse, which the proxy would otherwise refuse with unscannable_body. true allows the request; false (the default) blocks with 422.

value.hook_point (object, optional): Where in the lifecycle this rule runs.
allOf variant 1
oneOf variant 1: Input
oneOf variant 2: Output
oneOf variant 3: Both
value.kind (string, required): Guardrail provider type for the OpenAI Moderation API.
value.model (string, optional): Moderation model sent to the provider. The default is omni-moderation-latest; provider model names are not restricted by AISIX.
value.name (string, optional): Operator-facing name that surfaces in metric labels and error reasons.
value.output_fail_open (boolean, optional): Fail-open policy for the output hook. When disabled (the default), an OpenAI outage blocks model output instead of releasing unscanned content. The input hook continues to use the top-level fail_open policy.
value.timeout_ms (integer, optional): HTTP call timeout in milliseconds. fail_open and output_fail_open govern the verdict when it elapses. A value of 0 triggers the timeout immediately.
oneOf variant 10: Presidio
value.analyzer_url (string, required): Presidio analyzer base URL, e.g. http://presidio-analyzer:3000. The gateway appends /analyze.
value.anonymizer_url (string, required): Presidio anonymizer base URL, e.g. http://presidio-anonymizer:3000. The gateway appends /anonymize. Only called when a detected entity's effective action is mask.
value.created_at (string, optional): RFC3339 creation timestamp. When present, guardrails are evaluated from oldest to newest. Resources without this timestamp sort after resources that have it.
value.default_action (string, optional): Action for entities that do not set their own override.
value.direction (string, optional): Attachment direction hint. Guardrail execution still follows hook_point.
value.enabled (boolean, optional): When false, the chain skips this rule entirely. Allows operators to stage a rule before enabling it.
value.enforcement_mode (string, optional): How AISIX handles matching content. Enforcing mode applies the guardrail verdict; monitor mode records what would have happened without blocking or redacting the caller-visible response.
value.entities (array, optional): Entities to detect. Empty (the default) analyzes with Presidio's full recognizer set and applies default_action to every hit.
value.entities[].action (string, optional): Per-entity action override. Falls back to the guardrail's default_action when omitted.
value.entities[].type (string, required): Presidio entity type, e.g. EMAIL_ADDRESS, PERSON, US_SSN.
value.fail_open (boolean, optional): Behavior when this guardrail cannot complete its check. Two causes: a remote provider that is unreachable, timing out, throttling, or rejecting the call; and a body the gateway could not give the guardrail at all — one that does not decode as UTF-8 or does not parse, which the proxy would otherwise refuse with unscannable_body. true allows the request; false (the default) blocks with 422.

value.hook_point (object, optional): Where in the lifecycle this rule runs.
allOf variant 1
oneOf variant 1: Input
oneOf variant 2: Output
oneOf variant 3: Both
value.kind (string, required): Guardrail provider type for PII detection and anonymization by a customer-run Presidio.
value.language (string, optional): Analyzer language code.
value.max_buffer_bytes (integer, optional): Max bytes buffered for a streamed response before on_buffer_exceeded applies.
value.name (string, optional): Operator-facing name that surfaces in metric labels and error reasons.
value.on_buffer_exceeded (string, optional): Buffer-overflow policy for streamed output when the buffer cap is hit.
value.operator (string, optional): Anonymize operator applied to masked entities.
value.output_fail_open (boolean, optional): Fail-open policy for the output hook. When disabled (the default), a Presidio outage blocks model output instead of releasing unscanned content. The input hook continues to use the top-level fail_open policy.
value.score_threshold (number, optional): Minimum analyzer confidence for a hit to count. Omitted → every result the analyzer returns counts (Presidio's own per-recognizer defaults apply).
value.timeout_ms (integer, optional): HTTP call timeout in milliseconds, applied per analyzer/anonymizer call. fail_open and output_fail_open govern the verdict when it elapses. A value of 0 triggers the timeout immediately.
oneOf variant 11: Semantic Screening
value.allow_examples (array, optional): Example texts whose meaning is PERMITTED. When non-empty, a screened text that clears none of them blocks — an allow-list narrows traffic to the listed topics. Empty (the default) means "no allow-list": only deny_examples can block.
value.allow_threshold (number, optional): Cosine-similarity threshold for allow_examples, in [-1, 1]. RAISE it to block more — a text must reach it to be admitted. Required whenever allow_examples is non-empty, and only then: a row with no allow-list has nothing for this number to decide. See deny_threshold for why there is no portable value.
value.created_at (string, optional): RFC3339 creation timestamp. When present, guardrails are evaluated from oldest to newest. Resources without this timestamp sort after resources that have it.
value.deny_examples (array, optional): Example texts whose meaning must be REFUSED. A screened text scoring at or above deny_threshold against any of them blocks.
value.deny_threshold (number, optional): Cosine-similarity threshold for deny_examples, in [-1, 1]. Lower it to block more. Required whenever deny_examples is non-empty.

There is no portable value. Cosine scores are not comparable across embedding models — the same pair of texts can fall on opposite sides of a fixed threshold depending on which model produced the vectors, and a threshold carried over from another model under-screens without any sign that it is doing so. Measure one against the model named in embedding_model, on your own traffic: a request that emits a usage event reports what it scored in guardrail_scores, including the requests this guardrail allowed. Not every surface can produce that sample. /a2a, rerank, /v1/embeddings, /v1/images/*, /v1/videos, /v1/audio/speech and /v1/messages/count_tokens run the INPUT hook only, so an output-hook row scores nothing on them (audio transcription and translation do run both); /a2a also resolves no model and no MCP server, so only a row attached at the environment, API-key or team scope reaches it at all.

value.direction (string, optional): Attachment direction hint. Guardrail execution still follows hook_point.
value.embedding_model (string, required): Alias of an embedding-kind Model used to embed both the examples and the screened text. Must resolve in the same environment as this guardrail.

Defaulted at the TYPE level and required by the strict write schema instead: a row the loader cannot deserialize is skipped whole, and a screening row that vanishes is a guardrail that stopped screening. Empty resolves to nothing, so the row degrades per fail_open — fail-closed by default — rather than disappearing.

value.enabled (boolean, optional): When false, the chain skips this rule entirely. Allows operators to stage a rule before enabling it.
value.enforcement_mode (string, optional): How AISIX handles matching content. Enforcing mode applies the guardrail verdict; monitor mode records what would have happened without blocking or redacting the caller-visible response.
value.fail_open (boolean, optional): Behavior when this guardrail cannot complete its check. Two causes: a remote provider that is unreachable, timing out, throttling, or rejecting the call; and a body the gateway could not give the guardrail at all — one that does not decode as UTF-8 or does not parse, which the proxy would otherwise refuse with unscannable_body. true allows the request; false (the default) blocks with 422.

value.hook_point (object, optional): Where in the lifecycle this rule runs.
allOf variant 1
oneOf variant 1: Input
oneOf variant 2: Output
oneOf variant 3: Both
value.kind (string, required): Guardrail provider type for embedding-similarity screening against example texts, using an embedding-kind Model.
value.max_buffer_bytes (integer, optional): Max bytes buffered for a streamed response before on_buffer_exceeded applies.
value.max_screened_texts (integer, optional): Cap on how many texts ONE request screens, bounding the embedding tokens a single request can spend. The input hook screens the MOST RECENT messages first and drops the rest: an earlier turn was already screened as the latest message of an earlier request, so the dropped tail is seen history rather than unread content.
value.name (string, optional): Operator-facing name that surfaces in metric labels and error reasons.
value.on_buffer_exceeded (string, optional): Buffer-overflow policy for streamed output when the buffer cap is hit.
value.output_fail_open (boolean, optional): Fail-open policy for the output hook. When disabled, an embedding outage does not release unscreened model output.
value.text_source (string, optional): Input-hook text selection. The default screens user messages only; the alternate mode screens every message. Ignored on the output hook.
value.timeout_ms (integer, optional): Per-call deadline for the embedding request in milliseconds.
allOf variant 1
allOf variant 2
oneOf variant 12: Custom Script
value.created_at (string, optional): RFC3339 creation timestamp. When present, guardrails are evaluated from oldest to newest. Resources without this timestamp sort after resources that have it.
value.direction (string, optional): Attachment direction hint. Guardrail execution still follows hook_point.
value.enabled (boolean, optional): When false, the chain skips this rule entirely. Allows operators to stage a rule before enabling it.
value.enforcement_mode (string, optional): How AISIX handles matching content. Enforcing mode applies the guardrail verdict; monitor mode records what would have happened without blocking or redacting the caller-visible response.
value.fail_open (boolean, optional): Behavior when this guardrail cannot complete its check. Two causes: a remote provider that is unreachable, timing out, throttling, or rejecting the call; and a body the gateway could not give the guardrail at all — one that does not decode as UTF-8 or does not parse, which the proxy would otherwise refuse with unscannable_body. true allows the request; false (the default) blocks with 422.

value.hook_point (object, optional): Where in the lifecycle this rule runs.
allOf variant 1
oneOf variant 1: Input
oneOf variant 2: Output
oneOf variant 3: Both
value.kind (string, required): Guardrail provider type for screening by an operator-supplied script the gateway runs in a sandboxed engine.
value.max_buffer_bytes (integer, optional): Max bytes buffered in buffer_full mode before on_buffer_exceeded applies.
value.max_memory_bytes (integer, optional): Memory ceiling for the script engine, in bytes. A script that exceeds it is terminated and the hook's fail-open policy applies.
value.name (string, optional): Operator-facing name that surfaces in metric labels and error reasons.
value.on_buffer_exceeded (string, optional): Buffer-overflow policy for streamed output when the buffer cap is hit.
value.output_fail_open (boolean, optional): Fail-open policy for the output hook. When disabled (the default), a script failure blocks model output instead of releasing unscanned content. The input hook uses the top-level fail_open policy.
value.script (string, required): The script source, as an ES module exporting checkInput and/or checkOutput. A hook whose function the module does not export is skipped, so a script may cover one direction only.

Required on both the write schema and the read one, so a row that omits it is refused rather than loaded: unlike the fields that are write-path-only, a custom row with no script screens nothing either way, and rejecting it is what puts it in /status/config's rejected list where an operator can see it.

A script that is whitespace-only or does not compile passes the schema — minLength counts characters, so a whitespace-only value is non-empty — and is refused when the chain is built instead. aisix validate reports that and exits non-zero; a serving gateway reports the runtime rejection through config status (api7/aisix#1084).

value.secrets (object, optional): Values the script reads as ctx.secrets.<NAME>, for credentials the screening service requires. Stored encrypted and decrypted before projection; plaintext is held in memory only and is never logged.
value.stream_processing_mode (string, optional): Streaming output moderation mode: sliding-window incremental release or whole-response hold-back.
value.timeout_ms (integer, optional): Wall-clock budget for one hook invocation, in milliseconds, covering the script's own execution and every call it makes. fail_open and output_fail_open govern the verdict when it elapses. Per-call timeouts within the budget are the script's own to set.
value.window_overlap_size (integer, optional): Chars carried between windows so a span split across a boundary is still caught.
value.window_size (integer, optional): Sliding-window size in characters for window mode.
401: Missing or invalid admin key
error_msg (string, required): Human-readable error message.
404: Resource not found Response fields (application/json): identical to GET /admin/v1/guardrails/{id}, response 401 above.
500: Configuration store operation failed Response fields (application/json): identical to GET /admin/v1/guardrails/{id}, response 401 above.

cURL

curl -X GET 'http://127.0.0.1:3001/admin/v1/guardrails/{id}'

Get Guardrail by ID

Authorization

Path Parameters

Response Body

200application/json

401application/json

404application/json

500application/json

GET /admin/v1/guardrails/{id}

Parameters

Responses

cURL

`application/json`

`application/json`

`application/json`

`application/json`