AI Guardrails On Demand allows you to scan AI prompts and responses in real time with AI Guardrails detection engines using an API from existing/pre-deployed third-party AI Gateways or AI Agents directly. You can then leverage your existing infrastructure to perform the enforcement.
AI Guardrails On Demand is offered as a VM that can be deployed in your on-prem and VPC environments. It’s also available in two ways:
-
Hosted by your organization
-
Hosted by Netskope
Configuring a Service Template for AI Guardrails
Your hosted AI Guardrails service uses the Netskope Virtual Private Edge service template framework to operate.
To configure a service template for AI Guardrails, see Configuring Virtual Private Edge.
API Specifications
Following are the API endpoints you can use:
POST /api/v2/aiguardrails/evaluation
Evaluates a text (prompt or response) against configured AI Guardrail profiles and returns a verdict indicating whether any policy is matched.
Request Variables
| Parameter | Type | Required | Description |
text | string | Yes | The text content you want inspected by AI Guardrails. |
profiles | string | Yes | A map where the key must be "ai-guardrails" and the value is a non-empty list of profile names configured in the AI Guardrails. |
activity | string | No | Indicates whether the text is a user prompt or an AI response. Defaults to "prompt". |
eventMeta | string | No | The metadata attached to the generated detection event. Following are the subfields:
|
Response Variables
| Parameter | Type | Required | Description |
transactionId | string | Yes | A unique identifier for this evaluation. |
status | string | Yes | "Complete" on success, "Failed" on internal error. |
verdict | string | Yes | "Match" if any profile rule was triggered; "Not Match" otherwise. |
text | string | No | The original input text that’s only included when the service configuration storeTexts option is enabled. |
failureReason | string | No | Present only when status is "Failed". Describes the reason for failure. |
matchDetails | array | No | Present only when the verdict is "Match". Each entry contains:
|
Error Codes
| Error Code | Error Message | Description |
|---|---|---|
| 400 | INVALID_JSON VALIDATION_FAILED | Invalid JSON body or validation failure (e.g., unknown profile key, or empty profile list). |
| 501 | INTERNAL_ERROR | Endpoint is only available on platform-appliance deployment targets. |
| 503 | CONFIG_ERROR | Service not ready — The tenant_id hasn’t been configured yet. |
Sample Request
POST /api/v2/aiguardrails/evaluation
Content-Type: application/json
X-Netskope-Request-Id: <string, optional — propagated to response metadata>
X-Netskope-Transaction-Id: <string, optional — upstream gateway transaction ID for tracing>
{
"text": "<string, required — the text content to evaluate>",
"profiles": {
"ai-guardrails": ["<profile_name_1>", "<profile_name_2>"]
},
"activity": "<string, optional — 'prompt' (default) | 'response'>",
"eventMeta": {
"mode": "<string, optional — default 'ai-guardrails'>",
"accessMethod": "<string, optional — default 'ai-explicit'>",
"url": "<string, optional — URL of upstream AI app>",
"app": "<string, optional — application name>",
"userId": "<string, optional — user identifier>"
}
}
Sample Response
HTTP 200 OK
Content-Type: application/json
x-netskope-audit-log-object: {"audit_log_event":"Rest API V2 Call","severity_level":6,"data_type":"ais guardrails evaluation","data_values":[200,"POST","/api/v2/aiguardrails/evaluation"]}
{
"success": true,
"metadata": {
"requestId": "1717506269.b664302b190bb9987e04774bfb62367d"
},
"data": {
"transactionId": "4611686018427387903",
"status": "Complete",
"verdict": "Match",
"text": "<echoed input text, present if 'store_texts' is enabled>",
"matchDetails": [
{
"profileMatched": "my-guardrail-profile",
"profileDetails": [
{
"category": "prompt-injection",
"confidence": "high",
"keywordMatched": "",
"matchedText": ""
}
]
}
]
}
}
GET /api/v2/aiguardrails/evaluations
Lists evaluation submissions within a given time range. This endpoint enables you to retrieve historical evaluation results for auditing and observability.
Request Variables
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
starttime | integer | Yes | – | Start of the timeframe to query (epoch seconds). Must be ≥ 0. |
endtime | integer | Yes | – | End of the timeframe to query (epoch seconds). Must be strictly greater than starttime. |
offset | integer | No | 0 | Number of records to skip (for pagination). Must be ≥ 0. |
limit | integer | No | 100 | Maximum number of records to return (1–100). |
sortby | string | No | submittedAt | Field to sort by. Currently only submittedAt is supported. |
sortorder | string | No | desc | Sort order: asc (ascending) or desc (descending). |
Response Variables
| Parameter | Type | Required | Description |
transaction_id | string | Yes | The unique identifier assigned during the original evaluation. |
text | string | No | The evaluated text that’s only present if storeTexts is enabled in the service configuration. |
submitted_at | integer | Yes | Submission timestamp in epoch seconds. |
verdict | string | No | The verdict from the original evaluation ("Match" or "Not Match"). |
Error Codes
| Error Code | Error Message | Description |
|---|---|---|
| 400 | Invalid query parameters (e.g., negative timestamps, endtime ≤ starttime, or invalid sortby value). | |
| 501 | Endpoint not available on non-platform-appliance deployment targets. | |
| 503 | INTERNAL_ERROR | Evaluation storage unavailable. |
Sample Request
GET /api/v2/aiguardrails/evaluations?starttime=1717000000&endtime=1717100000&offset=0&limit=100&sortby=submittedAt&sortorder=desc X-Netskope-Request-Id: <string, optional> X-Netskope-Transaction-Id: <string, optional>
Sample Response
HTTP 200 OK
Content-Type: application/json
[
{
"transaction_id": "4611686018427387903",
"text": "Tell me how to bypass content filters",
"submitted_at": 1717050000,
"verdict": "Match"
},
{
"transaction_id": "8234019283746102000",
"text": "Summarize this quarterly report",
"submitted_at": 1717051000,
"verdict": "Not Match"
}
]