API Overview

The AI Guard service exposes a synchronous REST API for real-time text classification and metrics collection. All requests and responses use JSON format.

Base URL

The AI Guard service runs on-premises within your Light Worker Node deployment. The default port is 4443 with TLS enabled.

https://<your-ai-guard-host>:4443

Endpoints

Authentication

The classification and metric endpoints require Bearer token authentication via the Authorization header:

Authorization: Bearer <your-api-key>

The API key must have Data Discovery scope. See Create an API Key for details.

Authorization Modes

The AI Guard service supports two authorization modes, configured by the administrator:

Request Format

All request bodies use Content-Type: application/json:

curl -X POST https://ai-guard.example.com:4443/classifications/v1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{ ... }'

Response Format

Successful responses return 200 OK with a JSON body. Error responses include a structured error object:

{
  "code": 400,
  "message": "Description of the error"
}

Error Codes

TLS & Certificate Pinning

When the service uses self-signed or internally-signed certificates, use certificate pinning for curl requests:

curl -X POST https://ai-guard.example.com:4443/classifications/v1 \
  --pinnedpubkey "sha256//x48Lk2iu3R3nAhSiz07bExGHTusDRjHqBx9ArK3cFGE=" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{ ... }'

See TLS & Certificate Pinning for details on extracting the pin.

Rate Limits

📘

Public Preview Release

As of this release, AI Guard is optimized for development and testing workloads. It is not recommended for large classification volumes generally seen in externally facing AI applications.

What's Next?

• POST /classifications/v1 — Classify text endpoint details
• POST /metric — Metrics event endpoint details
• GET /health — Health check endpoint details