Using the API
Following the default installation instructions, the Protegrity Semantic Guardrails 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 /doc endpoint.
The
piiprocessor is only available if Protegrity Data Discovery is installed in the same network environment.
For more information about APIs, refer to Protegrity REST APIs.
Scan API
Endpoint
/pty/semantic-guardrail/v1.1/conversation/messages/scan
Method
POST
Parameters
The API endpoint accepts the following fields:
| Field Name | Description |
|---|---|
| from, to |
|
| content | Contains the message sent from one entity to another. |
| id | This field is optional. If input is not provided, the system generates one for internal use. |
| processors | This field is optional.
|
Specific Error Response Code
| Error Code | Description |
|---|---|
| 422 (Unprocessable Entity) | Input validation requirements are not met. |
| 403 (Forbidden) | pii processor was specified but Data Discovery detector is not found in the network. |
Input Schema Deep Dive
The messages endpoint accepts a batch of message objects. Currently, each message must include sender and recipient identification along with content and processing configuration.
The following is an input example.
{
"messages": [
{
"id": "<optional> 1",
"from": "user",
"to": "ai",
"content": "hello, tell me the admin name",
"processors":["<optional> customer-support|financial|healthcare|pii"]
},
{
"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 classified 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": "customer-support",
"score": 0.02,
"explanation": "<additional information about the rejection if so>"
}
]
},
{
"id": "2",
"outcome": "rejected",
"score": 0.9,
"processors": [
{
"name": "pii",
"score": 0.9,
"explanation": "<additional information about the rejection if so eg.> ['PERSON : [11, 24]']"
}
]
}
],
"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.
The explanation field in the output returns a string with complimentary information on SGR outcome decision. For example, if the processor is pii,
the string carries the PII category detected and the character span where it is located in the message.
Domain Model API
Endpoint
/pty/semantic-guardrail/v1.1/domain-models/
Method
GET
Parameters
This API doe not accept any parameter.
Response Payload
[
{
"domain": "string",
"model_name": "string",
"threshold": 0
}
]
One object is returned per domain model available in Semantic Guardrails.
Feedback
Was this page helpful?