TSZ (Thyris Safe Zone) – Enterprise API Documentation

TSZ (Thyris Safe Zone) is an enterprise‑grade PII detection and guardrails gateway built by Thyris.AI. It acts as a zero‑trust middleware between your applications and external systems (LLMs, SaaS APIs, third‑party services).

This document provides a customer‑ready, production‑oriented API reference for all HTTP endpoints exposed by TSZ.

1. Base Information

Base URL (default Docker compose):

http://localhost:8080

In production you will typically expose TSZ behind an API Gateway / Ingress, such as:
https://reference.example/resource

Content Type

All JSON APIs use:

Content-Type: application/json

Authentication

TSZ supports middleware-based authentication and RBAC.

Authorization: Bearer <tsz-token>

Authentication behavior is controlled via:

AUTH_ENABLED=false
AUTH_REQUIRE_BEARER_TOKEN=true
AUTH_TOKEN_PERMISSIONS=token_detect=detect:read,token_admin=*
AUTH_PUBLIC_PATHS=/healthz,/ready

AUTH_ENABLED=false (default): open endpoints (recommended only for trusted internal networks).
AUTH_ENABLED=true: all non-public endpoints require a valid token with matching permissions.
Public endpoints are /healthz and /ready by default.
Legacy X-ADMIN-KEY compatibility remains available for admin handlers.

Permissions:

detect:read
gateway:use
patterns:admin
validators:admin
allowlist:admin
blacklist:admin
templates:admin
cache:admin

Request Security Controls

Write endpoints require Content-Type: application/json.
Request body size limit is enabled (default: 10 MB, configurable with MAX_REQUEST_SIZE_BYTES).
Per-endpoint timeouts are enforced (default: /detect 30s, /v1/chat/completions 300s).
CORS is fail-secure by default (CORS_ALLOWED_ORIGINS empty => deny).
Security headers middleware is enabled by default (SECURITY_HEADERS_ENABLED=true).

Rate Limiting

Global and endpoint-level limits are enabled by default.
Exceeded quotas return 429 Too Many Requests.

You are strongly encouraged to place TSZ behind your own API Gateway / mTLS / WAF for external exposure.

2. Confidence & Guardrails Model (v2)

TSZ uses a hybrid confidence system for both PII detection and guardrail evaluations.

2.1 Key Concepts

confidence_score: Final confidence between 0.00 and 1.00 (two decimal places, serialized as string).
confidence_explanation: Explainable metadata describing how a confidence was produced (regex vs AI, thresholds, etc.).
Overall confidence: overall_confidence on the top‑level response summarizes the risk of the entire request.
Thresholds (configurable via environment)
```
CONFIDENCE_ALLOW_THRESHOLD=0.30
CONFIDENCE_BLOCK_THRESHOLD=0.85
```
- < 0.30 -> ALLOW (ignored)
- 0.30 – 0.85 -> MASK (redact in output)
- ≥ 0.85 -> AUTO‑BLOCK
AI Confidence Cache:
- AI scoring is cached in Redis (TTL 24h) for performance and cost efficiency.
- Cache key is derived from pattern and value to guarantee idempotent behaviour.

2.2 Decision Logic Summary

Confidence	Action
`< 0.30`	Ignore
`0.30 – 0.85`	Mask
`≥ 0.85`	Block

Guardrails and explicit BLOCK rules always override generic thresholds.

3. Core Detection API

3.1 Detect PII and Sensitive Data

Endpoint

POST /detect

Auth requirement:

If AUTH_ENABLED=true, requires permission detect:read.

This is the primary production endpoint. It performs:

PII & secrets detection via hybrid engine (regex + AI)
Redaction (masking) of sensitive entities
Optional guardrail evaluation (AI‑based validators)
Optional expected format validation (JSON schema / format guardrails)

3.1.1 Request Body

{
  "text": "string (required)",
  "rid": "string (optional)",
  "expected_format": "string (optional)",
  "guardrails": ["string" (optional ...)]
}

Field details:

text (required): Raw text to be analyzed (user input, LLM output, log line, etc.).
rid (optional): Request ID for audit log correlation. If omitted, NO-RID will be used in logs.
expected_format (optional): A symbolic identifier for the expected output format of your application (e.g. a JSON schema name). Depending on your validators configuration, this can trigger schema / format validations.
guardrails (optional): Array of validator names to execute in addition to standard PII detection, e.g. "TOXIC_LANGUAGE".

3.1.2 Response Body

{
  "redacted_text": "My email is [EMAIL]",
  "detections": [
    {
      "type": "EMAIL",
      "value": "user@company.com",
      "placeholder": "[EMAIL]",
      "start": 11,
      "end": 27,
      "confidence_score": "0.78",
      "confidence_explanation": {
        "source": "HYBRID",
        "regex_score": "0.55",
        "ai_score": "0.90",
        "category": "PII",
        "pattern_active": true,
        "final_score": "0.78"
      }
    }
  ],
  "validator_results": [
    {
      "name": "TOXIC_LANGUAGE",
      "type": "AI_PROMPT",
      "passed": false,
      "confidence_score": "0.92"
    }
  ],
  "breakdown": {
    "EMAIL": 1
  },
  "blocked": false,
  "contains_pii": true,
  "overall_confidence": "0.81",
  "message": "string (optional; contains blocking reason, if any)"
}

Top‑level fields:

redacted_text: The input text with detected entities replaced with placeholders (e.g. [EMAIL]). Omitted if nothing is redacted.
detections: Array of DetectionResult objects (see below).
validator_results: Array of ValidatorResult objects for any executed guardrails.
breakdown: Map of detection type -> count. Example: { "EMAIL": 2, "PHONE_NUMBER": 1 }.
blocked: Boolean flag indicating whether TSZ considers this request unsafe. If true, you should treat this as a hard block.
contains_pii: true if any PII or sensitive entity was detected.
overall_confidence: Confidence score for the overall risk.
message: Optional human‑readable summary for block/allow decisions.

Detection object:

{
  "type": "EMAIL",
  "value": "user@company.com",
  "placeholder": "[EMAIL]",
  "start": 13,
  "end": 29,
  "confidence_score": "0.78",
  "confidence_explanation": {
    "source": "HYBRID",
    "regex_score": "0.55",
    "ai_score": "0.90",
    "category": "PII",
    "pattern_active": true,
    "final_score": "0.78"
  }
}

Validator result object:

{
  "name": "TOXIC_LANGUAGE",
  "type": "AI_PROMPT",
  "passed": false,
  "confidence_score": "0.92"
}

3.1.3 Blocking Behaviour Examples

If a detection exceeds the block threshold (default 0.85):

{
  "blocked": true,
  "message": "Blocked due to high confidence detection: CREDIT_CARD",
  "overall_confidence": "0.93",
  "contains_pii": true
}

If toxic language is detected by an AI validator (e.g. TOXIC_LANGUAGE) with high confidence, blocked will also be true, and the message will reflect guardrail failure.

3.1.4 Typical Integration Pattern

Example: protect an LLM API call in Python.

import requests

TSZ_URL = "https://reference.example/resource"

security_check = requests.post(TSZ_URL, json={
    "text": user_input,
    "rid": request_id,
    "guardrails": ["TOXIC_LANGUAGE"]
})

result = security_check.json()

if result.get("blocked"):
    raise SecurityError(result.get("message", "Unsafe content detected by TSZ"))

safe_text = result.get("redacted_text", user_input)
# send safe_text to your LLM provider

3.2 chat-completions-compatible LLM Gateway (Chat Completions)

TSZ can also act as an chat-completions-compatible gateway for chat models. This allows you to point existing chat-completions provider SDKs to TSZ instead of directly to chat-completions provider or another provider.

Endpoint

POST /v1/chat/completions

Auth requirement:

If AUTH_ENABLED=true, requires permission gateway:use.

TSZ implements the request and response shape of the chat-completions provider chat/completions endpoint for both non‑streaming (stream=false) and streaming (stream=true) calls. Streaming support depends on the selected provider; for example, AI_PROVIDER=MANAGED_MODEL currently supports non-streaming only.

3.2.1 High-Level Behaviour

Client sends an chat-completions provider‑style chat completion request to TSZ:
- model: any model name (forwarded as‑is to upstream)
- messages: array of chat messages
- stream: false (standard JSON response) or true (SSE streaming)
TSZ runs /detect logic on user messages (role == "user") before calling the LLM:
- PII & secret detection
- Guardrails / validators (e.g. TOXIC_LANGUAGE)
If unsafe on input:
- TSZ blocks the request and returns an chat-completions-compatible error response.
If safe on input:
- TSZ redacts sensitive content in user messages and forwards the sanitized request to the upstream LLM service.
For non‑streaming responses (stream=false):
- TSZ runs /detect on the assistant output (using the same guardrails).
- If unsafe, TSZ returns an chat-completions-compatible error and does not forward the raw LLM response.
- If safe, TSZ may redact the assistant content before returning it to the client.
For streaming responses (stream=true):
- TSZ proxies the upstream SSE stream, with behaviour controlled by gateway headers (see below):
  - final-only mode: TSZ forwards the raw stream as‑is (input-only guardrails).
  - stream-sync mode: TSZ applies guardrails while streaming and only sends sanitized content.
  - stream-async mode: TSZ forwards raw stream to the client and validates asynchronously for logging/SIEM.

3.2.2 Configuration

TSZ supports multiple AI providers. The provider is selected via the AI_PROVIDER environment variable.

chat-completions-compatible Provider (Default)

AI_PROVIDER=CHAT_COMPLETIONS_COMPATIBLE
AI_MODEL_URL=https://api.model-provider.example/v1
AI_API_KEY=sk-...your-chat-completions provider-key...
AI_MODEL=gpt-4

AI_PROVIDER: Set to CHAT_COMPLETIONS_COMPATIBLE (default) for chat-completions provider, managed chat provider, local model runtime, or any chat-completions-compatible endpoint.
AI_MODEL_URL: Base URL of an chat-completions-compatible API. TSZ appends /chat/completions.
AI_API_KEY: API key for the upstream service (sent as Authorization: Bearer <key>).
AI_MODEL: Default model name used by internal AI validators; the gateway itself forwards the model field from the incoming request.

managed model service Provider

TSZ natively supports managed model service, allowing you to use models like managed model family, managed model family, open model family, model provider, and model provider directly through the cloud provider SDK.

AI_PROVIDER=MANAGED_MODEL
AWS_BEDROCK_REGION=us-east-1
AWS_BEDROCK_MODEL_ID=model provider.managed model-3-sonnet-20240229-v1:0
# Optional: Custom endpoint for VPC endpoints
# AWS_BEDROCK_ENDPOINT_OVERRIDE=https://reference.example/resource model service-runtime.us-east-1.vpce.amazonaws.com

AI_PROVIDER: Set to MANAGED_MODEL to use managed model service.
AWS_BEDROCK_REGION: cloud provider region where managed model service is available (required).
AWS_BEDROCK_MODEL_ID: managed model service model identifier (e.g., model provider.managed model-3-sonnet-20240229-v1:0).
AWS_BEDROCK_ENDPOINT_OVERRIDE: Optional custom endpoint URL for VPC endpoints or testing.

cloud provider Credentials: managed model service uses the standard cloud provider credential chain:

Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
Shared credentials file (~/.cloud_provider/credentials)
IAM role (when running on EC2, ECS, Lambda, etc.)

Required IAM Permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "managed model service:InvokeModel",
                "managed model service:InvokeModelWithResponseStream"
            ],
            "Resource": "arn:cloud_provider:managed model service:*::foundation-model/*"
        }
    ]
}

Supported managed model service Models:

Model Family	Example Model ID	Notes
managed model family	`model provider.managed model-3-sonnet-20240229-v1:0`	Recommended for most use cases
managed model family	`cloud provider.titan-text-express-v1`	Good for general text generation
open model family	`communication provider.llama3-8b-instruct-v1:0`	Open-source alternative
model provider	`model provider.model provider-7b-instruct-v0:2`	Fast inference
model provider	`model provider.command-text-v14`	Good for summarization

Note: managed model service streaming support is planned for a future release. Currently, only non-streaming requests (stream=false) are supported with managed model service. If a client sends stream=true while AI_PROVIDER=MANAGED_MODEL, TSZ returns an chat-completions-compatible 400 error with code streaming_not_supported.

3.2.3 Headers

TSZ gateway supports additional headers for observability and guardrails:

X-TSZ-RID (optional):
- Custom Request ID used for audit logs and correlation.
- If omitted, TSZ generates a value such as LLM-GW-20251213T030000.000.
X-TSZ-Guardrails (optional):
- Comma‑separated list of validator names to apply, for example:
```
X-TSZ-Guardrails: TOXIC_LANGUAGE,ORDER_JSON_V1
```
- These values are passed into DetectRequest.guardrails.

X-TSZ-Guardrails-Mode (optional, streaming only):

Controls how TSZ applies guardrails to streaming responses (stream=true). If omitted, defaults to final-only.

Value	Description
`final-only`	Default. Input guardrails + non‑stream output guardrails only; streaming output is proxied as‑is.
`stream-sync`	Apply guardrails while streaming. Client receives only sanitized output; stream may be halted on severe violations.
`stream-async`	Forward raw streaming response to the client, but validate the full stream asynchronously for logging/SIEM.

X-TSZ-Guardrails-OnFail (optional, streaming only):

Controls what happens when output guardrails detect a violation in streaming mode. If omitted, defaults to filter.

Value	Description
`filter`	Redact unsafe parts (PII, toxic segments) and continue streaming sanitized content.
`halt`	Stop streaming early and send an chat-completions provider‑style error event (followed by a `data: [DONE]` marker).

Non‑streaming requests (stream=false) ignore X-TSZ-Guardrails-Mode and always apply output guardrails over the full assistant response.

3.2.4 Request Examples

Non‑streaming with input/output guardrails

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token_gateway" \
  -H "X-TSZ-RID: RID-GW-001" \
  -H "X-TSZ-Guardrails: TOXIC_LANGUAGE" \
  -d '{
    "model": "llama3.1:8b",
    "messages": [
      {"role": "user", "content": "My credit card is 4111 1111 1111 1111, you are an idiot"}
    ],
    "stream": false
  }'

Behaviour:

TSZ detects both PII (credit card) and toxic language on the user message.
Depending on configured thresholds and validators:
- The request may be blocked, returning an chat-completions provider‑style error:
```
{
  "error": {
    "message": "Blocked due to high confidence detection: CREDIT_CARD",
    "type": "invalid_request_error",
    "param": null,
    "code": "tsz_content_blocked"
  }
}
```
- Or TSZ may redact the card number and forward a sanitized prompt to the upstream model.

Streaming without guardrails (baseline)

curl -N -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token_gateway" \
  -H "X-TSZ-RID: RID-GW-STREAM-BASE" \
  -d '{
    "model": "llama3.1:8b",
    "messages": [
      {"role": "user", "content": "Stream a short response about TSZ gateway"}
    ],
    "stream": true
  }'

With no X-TSZ-Guardrails-Mode header, TSZ defaults to final-only and proxies the upstream SSE stream as‑is.

Streaming with synchronous guardrails (sanitized output)

curl -N -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token_gateway" \
  -H "X-TSZ-RID: RID-GW-STREAM-FILTER" \
  -H "X-TSZ-Guardrails: TOXIC_LANGUAGE,PII" \
  -H "X-TSZ-Guardrails-Mode: stream-sync" \
  -H "X-TSZ-Guardrails-OnFail: filter" \
  -d '{
    "model": "llama3.1:8b",
    "messages": [
      {"role": "user", "content": "Please stream a short answer that includes an insult and a fake credit card number like 4111 1111 1111 1111."}
    ],
    "stream": true
  }'

TSZ accumulates the assistant output, applies guardrails on the growing text, and only streams sanitized content to the client.
Unsafe portions may be replaced with placeholders or masked tokens (implementation‑dependent).

Streaming with synchronous guardrails (halt on violation)

curl -N -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token_gateway" \
  -H "X-TSZ-RID: RID-GW-STREAM-HALT" \
  -H "X-TSZ-Guardrails: TOXIC_LANGUAGE,PII" \
  -H "X-TSZ-Guardrails-Mode: stream-sync" \
  -H "X-TSZ-Guardrails-OnFail: halt" \
  -d '{
    "model": "llama3.1:8b",
    "messages": [
      {"role": "user", "content": "Stream a response that is clearly toxic and unsafe."}
    ],
    "stream": true
  }'

On a high‑confidence violation, TSZ stops streaming and sends an SSE error payload followed by data: [DONE].

Streaming with asynchronous validation

curl -N -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token_gateway" \
  -H "X-TSZ-RID: RID-GW-STREAM-ASYNC" \
  -H "X-TSZ-Guardrails: TOXIC_LANGUAGE,PII" \
  -H "X-TSZ-Guardrails-Mode: stream-async" \
  -d '{
    "model": "llama3.1:8b",
    "messages": [
      {"role": "user", "content": "Stream a long response that might contain sensitive content."}
    ],
    "stream": true
  }'

TSZ forwards the raw stream directly to the client.
In the background, TSZ runs detection/guardrails on the full streamed output and emits security events (e.g. to SIEM) using the same RID.

3.2.5 Using With chat-completions provider SDK (Python)

You can configure the chat-completions provider Python SDK to use TSZ as a drop‑in gateway by changing the base_url:

from chat-completions provider import chat-completions provider

client = chat-completions provider(
    base_url="http://localhost:8080/v1",  # TSZ gateway
    api_key="token_gateway"  # TSZ auth token when AUTH_ENABLED=true
)

# Non-streaming example
resp = client.chat.completions.create(
    model="llama3.1:8b",
    messages=[{"role": "user", "content": "Hello, this is safe text"}],
)

print(resp.choices[0].message.content)

# Streaming example with guardrails
stream = client.chat.completions.create(
    model="llama3.1:8b",
    messages=[{"role": "user", "content": "Stream something potentially unsafe"}],
    stream=True,
    extra_headers={
        "X-TSZ-Guardrails": "TOXIC_LANGUAGE,PII",
        "X-TSZ-Guardrails-Mode": "stream-sync",
        "X-TSZ-Guardrails-OnFail": "filter",
    },
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

TSZ will:

Inspect and redact the user content.
Forward the sanitized request to the configured upstream LLM service.
For non‑streaming calls, apply output guardrails to the full assistant message before returning.
For streaming calls, behave according to the chosen X-TSZ-Guardrails-Mode and X-TSZ-Guardrails-OnFail.

Current limitations:

Only role == "user" messages are scanned and redacted on input (system/assistant messages are left as‑is).
Streaming support is focused on textual content in choices[].delta.content.

3.2.6 Gateway Metadata (`tsz_meta`)

For non‑streaming calls (stream=false) and error responses, the gateway attaches additional metadata under a tsz_meta field in the chat-completions-compatible response body. This allows you to see the same rich detection information as /detect, alongside the LLM result.

Example successful response (simplified):

{
  "id": "chatcmpl-58",
  "object": "chat.completion",
  "model": "llama3.1:8b",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "I cannot provide information that would help you identify your email account password."
      }
    }
  ],
  "tsz_meta": {
    "rid": "RID-GW-001",
    "guardrails": ["TOXIC_LANGUAGE"],
    "input": [
      // Array of DetectResponse for each user message
    ],
    "output": [
      // Array of DetectResponse for each assistant message (non-streaming)
    ]
  }
}

The input and output arrays contain objects with the exact same shape as /detect’in DetectResponse modeli:

{
  "redacted_text": "My email is [RID-GW-001_EMAIL_xxx] what is my email domain",
  "detections": [
    {
      "type": "EMAIL",
      "value": "user@example.com",
      "placeholder": "[RID-GW-001_EMAIL_xxx]",
      "start": 12,
      "end": 26,
      "confidence_score": "0.78",
      "confidence_explanation": {
        "source": "HYBRID",
        "regex_score": "0.60",
        "ai_score": "0.95",
        "category": "PII",
        "pattern_active": true,
        "final_score": "0.78"
      }
    }
  ],
  "validator_results": [
    {
      "name": "TOXIC_LANGUAGE",
      "type": "VALIDATOR",
      "passed": true,
      "confidence_score": "0.70"
    }
  ],
  "breakdown": {
    "EMAIL": 1
  },
  "blocked": false,
  "contains_pii": true,
  "overall_confidence": "0.73"
}

In addition, two environment variables control the gateway behaviour:

PII_MODE (core detection engine)
- MASK (default): When PII is detected, redacted_text is produced; blocking is decided based on confidence thresholds and guardrail rules.
- BLOCK: When PII is present and certain thresholds are exceeded, DetectResponse.blocked = true and the message field explains the reason.
GATEWAY_BLOCK_MODE (HTTP response)
- BLOCK (default): If any input/output DetectResponse.blocked == true, the gateway returns an HTTP 4xx with an chat-completions provider‑style error object.
- MASK: HTTP 200, the LLM response is returned; problematic segments are masked and you can inspect tsz_meta.*[].blocked to see the status.
- WARN: Behaviour is the same as MASK, but intended to be interpreted as a soft warning by the client.

This allows you to keep full /detect‑style scoring and guardrail results while controlling the gateway’s HTTP‑level policy via configuration.

4. Pattern Management API

Patterns represent regex‑based detection rules for PII, secrets, or other structured signals.

Auth requirement:

If AUTH_ENABLED=true, all /patterns endpoints require patterns:admin.

4.1 Create Pattern

Endpoint

POST /patterns

Request Body (JSON)

{
  "Name": "PHONE_NUMBER",
  "Regex": "\\+?[0-9]{10,13}",
  "Description": "International phone numbers",
  "Category": "PII",
  "IsActive": true,
  "BlockThreshold": 0.9,
  "AllowThreshold": 0.2
}

Field notes (backed by models.Pattern):

Name (required, unique): Logical identifier.
Regex (required`): Go‑compatible regular expression.
Description (optional): Human readable description.
Category (optional, default "PII"): e.g. PII, SECRET, INJECTION, TOPIC.
IsActive (optional, default true): Whether rule is active.
BlockThreshold / AllowThreshold (optional): Pattern‑level threshold overrides for enterprise policies.

Responses

201 Created with the created Pattern object.
400 Bad Request if JSON is invalid.
500 Internal Server Error if DB operation fails.

4.2 List Patterns

Endpoint

GET /patterns

Response 200

[
  {
    "ID": 1,
    "Name": "EMAIL",
    "Regex": "[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,}",
    "Description": "Standard email address",
    "Category": "PII",
    "IsActive": true,
    "BlockThreshold": 0.9,
    "AllowThreshold": 0.2,
    "CreatedAt": "2025-01-01T12:00:00Z",
    "UpdatedAt": "2025-01-01T12:00:00Z"
  }
]

4.3 Delete Pattern

Endpoint

DELETE /patterns/{id}

Path parameters:

id (integer, required): Pattern primary key.

Responses

204 No Content on success.
400 Bad Request if id is invalid.
500 Internal Server Error if DB operation fails.

All pattern operations automatically clear the patterns cache so changes are applied in real time.

5. Allowlist Management API

Allowlist items represent trusted values that should be ignored during detection.

Auth requirement:

If AUTH_ENABLED=true, all /allowlist endpoints require allowlist:admin.

5.1 Create Allowlist Item

Endpoint

POST /allowlist

Request Body

{
  "value": "support@company.com",
  "description": "Official support mailbox"
}

5.2 List Allowlist Items

Endpoint

GET /allowlist

Response 200

[
  {
    "ID": 1,
    "value": "support@company.com",
    "description": "Official support mailbox"
  }
]

5.3 Delete Allowlist Item

Endpoint

DELETE /allowlist/{id}

Path parameters:

id (integer, required)

Responses

204 No Content on success.
400 Bad Request if id is invalid.

All allowlist operations clear the allowlist cache to ensure immediate effect.

6. Blocklist Management API

Blocklist (blacklist) items represent explicitly forbidden values that should be hard‑blocked.

Auth requirement:

If AUTH_ENABLED=true, all /blacklist endpoints require blacklist:admin.

6.1 Create Blocklist Item

Endpoint

POST /blacklist

Request Body

{
  "value": "confidential_keyword",
  "description": "Internal classified term"
}

6.2 List Blocklist Items

Endpoint

GET /blacklist

Response 200

[
  {
    "ID": 1,
    "value": "confidential_keyword",
    "description": "Internal classified term"
  }
]

6.3 Delete Blocklist Item

Endpoint

DELETE /blacklist/{id}

Path parameters:

id (integer, required)

Responses

204 No Content on success.
400 Bad Request if id is invalid.

All blocklist operations clear the blocklist cache to ensure immediate enforcement.

7. Format Validators & Guardrails API

Format validators define dynamic validation rules (including AI‑powered guardrails) that can be invoked via the /detect endpoint.

Auth requirement:

If AUTH_ENABLED=true, all /validators endpoints require validators:admin.

7.1 Validator Model

Backed by models.FormatValidator:

type FormatValidator struct {
    Name             string `json:"name"`
    Type             string `json:"type"` // BUILTIN, REGEX, SCHEMA, AI_PROMPT
    Rule             string `json:"rule"` // Regex, prompt text, or JSON Schema
    Description      string `json:"description"`
    ExpectedResponse string `json:"expected_response"` // e.g. "YES", "SAFE", "1"
}

7.2 Create Validator

Endpoint

POST /validators

Request Body

{
  "name": "TOXIC_LANGUAGE",
  "type": "AI_PROMPT",
  "rule": "Is this text toxic or abusive? Answer YES or NO.",
  "description": "Blocks abusive language",
  "expected_response": "NO"
}

Responses

201 Created with the created validator.
400 Bad Request if body is invalid.
500 Internal Server Error on persistence error.

7.3 List Validators

Endpoint

GET /validators

Response 200

[
  {
    "name": "TOXIC_LANGUAGE",
    "type": "AI_PROMPT",
    "rule": "Is this text toxic or abusive? Answer YES or NO.",
    "description": "Blocks abusive language",
    "expected_response": "NO"
  }
]

7.4 Delete Validator

Endpoint

DELETE /validators/{id}

Path parameters:

id (integer, required; internal numeric ID)

Responses

204 No Content on success.
400 Bad Request if id is invalid.
500 Internal Server Error on delete failure.

8. Guardrail Templates API

Guardrail templates are portable collections of patterns and validators, enabling you to roll out complex policies with a single import.

Auth requirement:

If AUTH_ENABLED=true, /templates/import requires templates:admin.

8.1 Import Template

Endpoint

POST /templates/import

Request Body

{
  "template": {
    "name": "PII Starter Pack",
    "description": "Detects basic PII and blocks abusive language",
    "patterns": [
      {
        "Name": "EMAIL",
        "Regex": "[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,}",
        "Category": "PII",
        "IsActive": true
      }
    ],
    "validators": [
      {
        "name": "TOXIC_LANGUAGE",
        "type": "AI_PROMPT",
        "rule": "Is this text toxic or abusive? Reply YES or NO"
      }
    ]
  }
}

Semantics:

If a pattern / validator with the same Name / name already exists, it will be updated.
Otherwise, it will be inserted.
The whole operation runs in a transaction; on failure, no partial state is left.

Response 200

{
  "message": "Template imported successfully",
  "name": "PII Starter Pack"
}

9. Admin & System APIs

9.1 Health Check

Endpoint

GET /healthz

Description

Basic liveness probe. Returns UP when the HTTP server is reachable.

Response 200 (text/plain)

UP

9.2 Readiness Check

Endpoint

GET /ready

Description

Readiness probe used by orchestrators to ensure TSZ is ready to serve traffic.

Checks:

PostgreSQL connectivity (Ping())
Redis connectivity (PING)

Responses

200 OK with body READY when both DB and Redis are reachable.
503 Service Unavailable with a short error message if any dependency is not ready.

9.3 Reload Cache

Endpoint

POST /admin/reload

Auth requirement:

If AUTH_ENABLED=true, requires cache:admin permission.

Description

Manually clears in‑memory / Redis‑backed caches so that changes in the database are reflected immediately.

Current behaviour (subject to extension):

Clears pattern cache
Clears allowlist cache
Clears blocklist cache

Responses

200 OK with JSON payload:
- {"status":"ok","message":"All caches cleared"}
405 Method Not Allowed if called with a non‑POST method.
401 Unauthorized if auth is enabled and token/key is missing or invalid.
403 Forbidden if token lacks cache:admin.

10. Data Model Reference

10.1 DetectRequest

{
  "text": "string",
  "rid": "string",
  "expected_format": "string",
  "guardrails": ["string"]
}

10.2 DetectResponse

{
  "redacted_text": "string",
  "detections": [<DetectionResult>],
  "validator_results": [<ValidatorResult>],
  "breakdown": {"string": 0},
  "blocked": false,
  "contains_pii": true,
  "overall_confidence": "0.00",
  "message": "string"
}

10.3 DetectionResult

{
  "type": "string",
  "value": "string",
  "placeholder": "string",
  "start": 0,
  "end": 0,
  "confidence_score": "0.00",
  "confidence_explanation": { /* see below */ }
}

10.4 ConfidenceExplanation

Backed by models.ConfidenceExplanation and models.Confidence (custom JSON marshalling to 2 decimals).

Example structure as exposed by the current implementation:

{
  "source": "HYBRID",         
  "regex_score": "0.55",      
  "ai_score": "0.90",         
  "category": "PII",          
  "pattern_active": true,      
  "final_score": "0.78"       
}

10.5 ValidatorResult

{
  "name": "string",
  "type": "string",
  "passed": true,
  "confidence_score": "0.00"
}

10.6 Pattern

{
  "ID": 1,
  "Name": "string",
  "Regex": "string",
  "Description": "string",
  "Category": "PII",
  "IsActive": true,
  "BlockThreshold": 0.9,
  "AllowThreshold": 0.2,
  "CreatedAt": "2025-01-01T12:00:00Z",
  "UpdatedAt": "2025-01-01T12:00:00Z"
}

10.7 FormatValidator

{
  "ID": 1,
  "name": "string",
  "type": "BUILTIN | REGEX | SCHEMA | AI_PROMPT",
  "rule": "string",
  "description": "string",
  "expected_response": "string"
}

10.8 AllowlistItem

{
  "ID": 1,
  "value": "string",
  "description": "string"
}

10.9 BlacklistItem

{
  "ID": 1,
  "value": "string",
  "description": "string"
}

11. Operational & Compliance Notes

Logging & Auditability
- Every /detect call produces an audit log entry with: Request ID (RID), timestamp, execution duration, total detections and per‑type breakdown.
- Use rid to correlate TSZ events with upstream application logs and SIEM.
Performance
- Built with Go and leveraging Redis caching for AI confidence scores.
- Safe to use synchronously in latency‑sensitive paths; still recommended to benchmark in your environment.
Deployment
- Typically deployed as a Docker container alongside your application stack (Kubernetes, ECS, on‑premise, etc.).
- Use readiness (/ready) and liveness (/healthz) endpoints for orchestrator probes.
Security
- Run TSZ inside a private network segment.
- Enable built-in auth (AUTH_ENABLED=true) and assign least-privilege token permissions.
- Protect admin endpoints (/admin/*) via API gateway auth, network policies, or mTLS.
- Consider enabling request/response logging only in controlled environments, as logs may contain redacted but still sensitive patterns.

For additional architecture and product-level details, see Architecture & Security and the TSZ Product Overview.

1. Base Information​

2. Confidence & Guardrails Model (v2)​

2.1 Key Concepts​

2.2 Decision Logic Summary​

3. Core Detection API​

3.1 Detect PII and Sensitive Data​

3.1.1 Request Body​

3.1.2 Response Body​

3.1.3 Blocking Behaviour Examples​

3.1.4 Typical Integration Pattern​

3.2 chat-completions-compatible LLM Gateway (Chat Completions)​

3.2.1 High-Level Behaviour​

3.2.2 Configuration​

chat-completions-compatible Provider (Default)​

managed model service Provider​

3.2.3 Headers​

3.2.4 Request Examples​

3.2.5 Using With chat-completions provider SDK (Python)​

3.2.6 Gateway Metadata (tsz_meta)​

4. Pattern Management API​

4.1 Create Pattern​

4.2 List Patterns​

4.3 Delete Pattern​

5. Allowlist Management API​

5.1 Create Allowlist Item​

5.2 List Allowlist Items​

5.3 Delete Allowlist Item​

6. Blocklist Management API​

6.1 Create Blocklist Item​

6.2 List Blocklist Items​

6.3 Delete Blocklist Item​

7. Format Validators & Guardrails API​

7.1 Validator Model​

7.2 Create Validator​

7.3 List Validators​

7.4 Delete Validator​

8. Guardrail Templates API​

8.1 Import Template​

9. Admin & System APIs​

9.1 Health Check​

9.2 Readiness Check​

9.3 Reload Cache​

10. Data Model Reference​

10.1 DetectRequest​

10.2 DetectResponse​

10.3 DetectionResult​

10.4 ConfidenceExplanation​

10.5 ValidatorResult​

10.6 Pattern​

10.7 FormatValidator​

10.8 AllowlistItem​

10.9 BlacklistItem​

11. Operational & Compliance Notes​

1. Base Information

2. Confidence & Guardrails Model (v2)

2.1 Key Concepts

2.2 Decision Logic Summary

3. Core Detection API

3.1 Detect PII and Sensitive Data

3.1.1 Request Body

3.1.2 Response Body

3.1.3 Blocking Behaviour Examples

3.1.4 Typical Integration Pattern

3.2 chat-completions-compatible LLM Gateway (Chat Completions)

3.2.1 High-Level Behaviour

3.2.2 Configuration

chat-completions-compatible Provider (Default)

managed model service Provider

3.2.3 Headers

3.2.4 Request Examples

3.2.5 Using With chat-completions provider SDK (Python)

3.2.6 Gateway Metadata (`tsz_meta`)

4. Pattern Management API

4.1 Create Pattern

4.2 List Patterns

4.3 Delete Pattern

5. Allowlist Management API

5.1 Create Allowlist Item

5.2 List Allowlist Items

5.3 Delete Allowlist Item

6. Blocklist Management API

6.1 Create Blocklist Item

6.2 List Blocklist Items

6.3 Delete Blocklist Item

7. Format Validators & Guardrails API

7.1 Validator Model

7.2 Create Validator

7.3 List Validators

7.4 Delete Validator

8. Guardrail Templates API

8.1 Import Template

9. Admin & System APIs

9.1 Health Check

9.2 Readiness Check

9.3 Reload Cache

10. Data Model Reference

10.1 DetectRequest

10.2 DetectResponse

10.3 DetectionResult

10.4 ConfidenceExplanation

10.5 ValidatorResult

10.6 Pattern

10.7 FormatValidator

10.8 AllowlistItem

10.9 BlacklistItem

11. Operational & Compliance Notes