Get Guardrail by ID

GET /environments/{env_id}/guardrails/{guardrail_id}

Get Guardrail by ID

Return one guardrail definition in the environment. Provider credentials in the kind-specific configuration are redacted.

Parameters

• env_id (path, string, required): Environment ID that scopes the request.
• guardrail_id (path, string, required): Guardrail ID within the environment.

Responses

• 200: OK
• guardrail (object, required): A configured guardrail as returned by the API.

A guardrail inspects traffic only where an attachment puts it. Creating one attaches it to nothing, so it is enforced nowhere until you POST a guardrail attachment naming its scope; the console does this for you when you pick a scope on the create form. An enabled guardrail with no attachment is a valid state — its scope target may have been deleted — and the gateway treats it as inspecting no traffic rather than as applying everywhere.

• guardrail.id (string, required): Guardrail ID within the environment.

• guardrail.env_id (string, required): Environment that owns the guardrail.

• guardrail.name (string, required): Human-readable guardrail name, unique within the environment.

• guardrail.enabled (boolean, required): Whether connected gateways evaluate this guardrail.

• guardrail.hook_point (string, optional): Where in the request lifecycle the guardrail executes. This is the runtime control; direction is only metadata.

• guardrail.kind (string, required): Guardrail provider kind. Fixed at creation.

• guardrail.fail_open (boolean, optional): When the remote guardrail provider cannot complete its check, allow (true) or block (false) the request. Defaults to false — an unchecked request is not released. No-op for kind=keyword.

• guardrail.config (object, optional): Kind-specific configuration. Shape is validated server-side against the guardrail catalog; secrets are redacted here.

Kinds that store a secret replace it with a server-computed summary of what is held: api_key_set, access_key_secret_set, aws_credentials.secret_set or secret_names. These are read-only projections. You may send them straight back on create or update — the value is accepted when it matches what the server holds, so a read-modify-write round-trip works unchanged — but they never write anything: a value that disagrees is rejected with 400 rather than silently ignored. To change the underlying secret, send the secret field itself (api_key, access_key_secret, aws_credentials.secret_access_key, or secrets).

• guardrail.family (string, optional): Dashboard grouping metadata (not sent to the data plane).

• guardrail.provider (string, optional): Provider metadata used to select the guardrail configuration form.

• guardrail.check_type (string, optional): Check-category metadata used to select the guardrail configuration form.

• guardrail.enforcement_mode (string, optional): Whether matching content is only observed or actively enforced.

• guardrail.direction (string, optional): Input/output classification hint stored with the guardrail. Guardrail execution still follows hook_point; changing this value does not move evaluation to a different lifecycle hook.

• guardrail.created_at (string, optional): RFC3339 time when the guardrail was created.

• guardrail.updated_at (string, optional): RFC3339 time when the guardrail was last updated.

• warnings (array, optional): Present on create and update when some data plane nodes in the environment run a gateway version that will not execute part of the saved configuration — a custom pattern replacement, for example, makes an older gateway drop the whole guardrail, which then stops enforcing there entirely. Never present on reads.

• warnings[].code (string, required): How affected nodes treat the saved resource. field_ignored: the resource stays in service on those nodes but the named field has no effect there — beware when the field is restrictive, since the restriction is silently not enforced. row_rejected: those nodes refuse the whole resource, so it stops serving there entirely (or, if a previously accepted version exists, they keep serving the old values).

• warnings[].field (string, required): Dot-separated path of the field that triggered the warning, as delivered to gateway nodes.

• warnings[].min_dp_version (string, required): Oldest gateway version that fully executes the field. The literal value unreleased means no released gateway version executes it yet.

• warnings[].affected_dp_count (integer, required): Number of currently registered nodes in the environment running an older gateway version than min_dp_version.

• warnings[].affected_dp_versions (array, required): Distinct gateway versions reported by the affected nodes, capped at five entries. Nodes that report no version appear as unknown.

• 400: Request body or parameters failed validation.

• error (object, required): Error details.

• error.code (string, required): Machine-readable identifier. Examples: UNAUTHENTICATED, INVALID_REQUEST, MASTER_KEY_UNSET, INTERNAL.

• error.message (string, required): Human-readable explanation; safe to surface to operators.

• 401: Missing or invalid bearer. Response fields (application/json): identical to GET /environments/{env_id}/guardrails/{guardrail_id}, response 400 above.

• 404: Resource not found. Response fields (application/json): identical to GET /environments/{env_id}/guardrails/{guardrail_id}, response 400 above.

cURL

curl -X GET '$AISIX_CP/environments/{env_id}/guardrails/{guardrail_id}' -H 'Authorization: Bearer $AISIX_TOKEN'