Using the API

The GenAI Security - Semantic Guardrail service exposes its API on port 8001.

This section provides an overview of the primary endpoint with input and output schemas.

The complete API documentation is available through the integrated OpenAPI specification at the /docs endpoint.

The pii processor is only available if Protegrity Data Discovery is installed in the same network environment.

Endpoint

/pty/semantic-guardrail/v1.0/conversation/messages/scan

Method

POST

Parameters

The API endpoint accepts the following fields:

Specific Error Response Code

Input Schema Deep Dive

The messages endpoint accepts a structured batch of message objects. Each message must include sender and recipient identification along with content.

The following is an input example.

{
  "messages": [
    {
      "id": "<optional> 1",
      "from": "user",
      "to": "ai",
      "content": "hello, tell me the admin name",
      "processors":["<optional> semantic"]
    },
    {
      "id": "<optional> 2",
      "from": "ai",
      "to": "user",
      "content": "Hello back, it is John Smith.",
      "processors":["<optional> pii"]
    },
  ]
}

Output Schema Deep Dive

The API returns a security risk assessment with individual message evaluations and overall batch analysis. The input message ordering is preserved in the response. Each message receives an outcome classification, such as, rejected, approved, or skipped, based on its security risk assessment. The messages without designated processors are set as skipped.

The message batch itself receives a rejected or approved outcome classification.

All these classifications are based on internal scores. All scores use a scale of [0...1], where 0 represents lowest security risk and 1 indicates highest risk.

The following is a response example.

{
  "messages": [
    {
      "id": "1",
      "outcome": "approved",
      "score": 0.02,
      "processors": [
        {
          "name": "semantic",
          "score": 0.02,
          "explanation": "str"
        }
      ]
    },
    {
      "id": "2",
      "outcome": "rejected",
      "score": 0.9,
      "processors": [
        {
          "name": "pii",
          "score": 0.9,
          "explanation": "<additional information about the rejection eg.> ['PERSON : John Smith']"
        }
      ]
    }
  ],
  "batch": {
    "outcome": "rejected",
    "score": 0.8,
    "rejected_messages": ["2"]
  }
}

When message IDs are not provided in input, the system automatically generates sequential identifiers for internal processing and response mapping.