> ## Documentation Index
> Fetch the complete documentation index at: https://developer.onetrust.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

| Method | Path                  | Description                               | Auth Required |
| ------ | --------------------- | ----------------------------------------- | ------------- |
| `POST` | `/classifications/v1` | Classify text for sensitive data patterns | Yes           |
| `POST` | `/metric`             | Record a metrics event                    | Yes           |
| `GET`  | `/health`             | Health check                              | No            |

## 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](https://developer.onetrust.com/onetrust/docs/ai-guard-create-api-key) for details.

### Authorization Modes

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

| Mode              | Description                                                                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **OneTrust**      | The service validates the bearer token against a remote OneTrust endpoint. This is the default mode for production deployments. |
| **Shared Secret** | The bearer token is compared against a value loaded from a local file. Used for development and testing.                        |

## Request Format

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

```bash
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:

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

## Error Codes

| HTTP Status | Description                                               |
| ----------- | --------------------------------------------------------- |
| `200`       | Success                                                   |
| `400`       | Bad request — invalid input or metrics not enabled        |
| `401`       | Unauthorized — missing or invalid bearer token            |
| `500`       | Internal server error                                     |
| `502`       | Bad gateway — upstream classification service unavailable |

## TLS & Certificate Pinning

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

```bash
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](https://developer.onetrust.com/onetrust/docs/ai-guard-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](https://developer.onetrust.com/onetrust/docs/ai-guard-api-classify) — Classify text endpoint details
* [POST /metric](https://developer.onetrust.com/onetrust/docs/ai-guard-api-metric) — Metrics event endpoint details
* [GET /health](https://developer.onetrust.com/onetrust/docs/ai-guard-api-health) — Health check endpoint details