Test Guardrail Connection

POST /environments/{env_id}/guardrails/test-connection

Interactive request editor loads with JavaScript.

Authorization

BearerAdminToken

AuthorizationBearer <token>

Organization-scoped admin token. Read operations require a valid token, and write operations require a token with write permission.

In: header

Path Parameters

env_id*string

Environment ID that scopes the request.

Formatuuid

Request Body

application/json

Probe a remote guardrail provider before saving. Mirrors the create body's kind + config.

kind*GuardrailKind

Guardrail provider kind. Fixed at creation.

Value in

"keyword"
"pii"
"bedrock"
"azure_content_safety"
"azure_content_safety_text_moderation"
"aliyun_text_moderation"
"aliyun_ai_guardrail"
"lakera"
"openai_moderation"
"presidio"
"semantic"
"custom"

config?

Kind-specific credentials and connection settings to test. When guardrail_id is supplied, supported providers can reuse the stored secret instead of receiving it again.

guardrail_id?string

Optional existing guardrail whose stored secret is reused.

Formatuuid

[key: string]?any

Response Body

`application/json`

curl -X POST "$AISIX_CP/environments/$ENV_ID/guardrails/test-connection" \  -H "Authorization: Bearer $AISIX_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "kind": "keyword"  }'

{
  "ok": true,
  "message": "Connected — endpoint reachable and API key accepted."
}

Request body or parameters failed validation.

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Missing or invalid bearer.

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "no org context"
  }
}

Authenticated request is not permitted.

{
  "error": {
    "code": "CUSTOM_KEY_DISABLED",
    "message": "custom API key values are disabled for this organization"
  }
}

Resource not found.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "provider key not found"
  }
}

Complete operation details and schema variants

POST /environments/{env_id}/guardrails/test-connection

Test Guardrail Connection

Probe a remote-API guardrail provider (Bedrock, Azure Content Safety, Aliyun, Lakera, OpenAI Moderation, …) with the supplied credentials before saving the guardrail. The request mirrors the create body's kind + config; the exact config shape is provider-specific and validated by the server.

Parameters

env_id (path, string, required): Environment ID that scopes the request.

Request body

Content type: application/json

kind (string, required): Guardrail provider kind. Fixed at creation.
config (object, optional): Kind-specific credentials and connection settings to test. When guardrail_id is supplied, supported providers can reuse the stored secret instead of receiving it again.
guardrail_id (string, optional): Optional existing guardrail whose stored secret is reused.

Responses

200: OK
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 POST /environments/{env_id}/guardrails/test-connection, response 400 above.
403: Authenticated request is not permitted. Response fields (application/json): identical to POST /environments/{env_id}/guardrails/test-connection, response 400 above.
404: Resource not found. Response fields (application/json): identical to POST /environments/{env_id}/guardrails/test-connection, response 400 above.

cURL

curl -X POST '$AISIX_CP/environments/{env_id}/guardrails/test-connection' -H 'Authorization: Bearer $AISIX_TOKEN'

Test Guardrail Connection

200application/json

400application/json

401application/json

403application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`