Skip to main content

Zen Input Endpoint

tip

Generate API key from the ZenGuard Console.

The zen API endpoints allow to integrate all ZenGuard Trust Layer detectors using a single API endpoint. This enpdoint is dedicated to safeguard the inputs to the LLM. To safeguard the outputs from the LLM, please use the /v2/zen/out endpoint.

Using /v2/zen/in endpoint you can scan the prompts that are coming from:

  • Users
  • AI Agents
  • LLM Applications

After receiveing the response from the /v2/zen/in endpoint, your application can take appropriate actions, such as:

  • Blocking the prompt
  • Warning the user
  • Generating security alert
  • etc.

API Endpoint​

Note that this API is available only for the enterprise customers using their dedicated endpoints.

https://<your-dedicated-endpoint>.zenguard.ai/v2/zen/in

Policies​

The configuration of the detectors that is used to scan the prompt, the logic behind them are controlled by the API key Policy. Please, refer to the ZenGuard Policies Page for more information on how to configure the policies.

API​

Request Format​

The endpoint requires the following headers:

headers = {
    "x-api-key": "<ZEN_API_KEY>",
    "Content-Type": "application/json"
}

At minimum, the endpoint accepts the following request body:

{
    "messages": [
        "My SSN is 233-63-4577 and email is test@gmail.com. Thank you. "  
    ],
}
  • messages: List, required
    • The list of messages usually contains a single prompt to scan. However, it also can contain the conversation history.

​ZenGuard Trust Layer assumes that earlier interactions in the conversation have already been screened to prevent a conversation from being permanently blocked due to a previously detected threat. Hence, only the latest message is scanned.

To use the full functionality of the endpoint, you might want to provide the following additional fields:

{
    "messages": [
        "My SSN is 233-63-4577 and email is test@gmail.com. Thank you. "  
    ],
    "conversation_id": "123e4567-e89b-12d3-a456-426614174000",
    "actor_id": "user_123"
}

These optional fields allow ZenGuard Trust Layer to create enhanced insights into the conversation and user behavior.

  • conversation_id: String, optional
    • The Conversation ID uniquely identifies the conversation thread.
  • actor_id: String, optional
    • The Actor ID uniquely identifies the agent, user or another entity that is performing the conversation.

Example​

import os
import requests

prompt = "My SSN is 233-63-4577 and email is test@gmail.com. Thank you. "  
session = requests.Session()

response = session.post(
    "https://<your-dedicated-endpoint>.zenguard.ai/v2/zen/in",
    json={"messages": [prompt]},
    headers={"x-api-key": os.getenv("ZEN_API_KEY")}
)

if response.json()["is_detected"]:
    print("The prompt is flagged. Please take an appropriate action.")
else:
    print("The prompt is safe to proceed with.")

Sample Response:

{
    "is_detected": true,
    "prompt_attack": {
        "is_detected": false,
        "score": 0.0,
        "latency": 27.58089828491211,
        "extra": null
    },
    "pii": {
        "is_detected": true,
        "score": 1.0,
        "latency": 27.34817886352539,
        "extra": {
            "sanitized_message": "My SSN is SSN_1 and email EMAIL_1. Thank you.",
            "detected_pii": [
                {
                    "text": "is test@gmail.com",
                    "type": "email"
                },
                {
                    "text": "233-63-4577",
                    "type": "ssn"
                }
            ]
        }
    }
}

Response Format​

  • is_detected(bool): Indicates whether any threats were detected across all detectors. Returns true if any detector finds an issue.

  • prompt_attack(object): Contains results from the prompt attack detector

    • is_detected(bool): Whether a prompt attack was detected
    • score(float: 0.0 - 1.0): Confidence level of the detection
    • latency(float): Server-side latency in milliseconds
    • extra(object or null): Additional detector-specific information

  • pii(object): Contains results from the PII detector

    • is_detected(bool): Whether PII was detected
    • score(float: 0.0 - 1.0): Confidence level of the detection
    • latency(float): Server-side latency in milliseconds
    • extra(object): Additional PII-specific information including:
      • sanitized_message(string): The prompt with PII entities redacted according to the Policy.
      • detected_pii(list): List of detected PII entities, each containing:
        • text(string): The detected PII text
        • type(string): The type of PII detected (e.g., "email", "ssn")

Error Codes:

    - 401 Unauthorized: API key is missing or invalid.
    - 400 Bad Request: Request body is malformed.
    - 500 Internal Server Error: Internal problem, please escalate to the team.

Latency​

ZenGuard strives to provide the best latency for all APIs. We are continuosly working on both software and hardware optimizations.

In general, the latency of the API response depends heavily on the lenght of the prompt as well as the detectors that are run since some of the detectors inherently slower than others. As the rule of thumb, we strive to provide the server-side latency of less than 50ms for 100 token requests across all detectors.

Contents