> ## 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.

# POST /classifications/v1

Classify text for sensitive data patterns (PII, credentials, phone numbers, addresses, etc.). Returns match positions, confidence scores, and classifier identifiers.

## Endpoint

```
POST /classifications/v1
```

## Authentication

Requires `Authorization: Bearer <token>` header. Returns `401 Unauthorized` with a `WWW-Authenticate` header if the token is missing or invalid.

## Request Body

```json
{
  "context": {
    "actor": "user",
    "agent_id": "my-agent",
    "platform": "AMAZON_BEDROCK"
  },
  "classifierDescription": {
    "type": "profile",
    "uuid": "7dbf380f-0af8-4276-acb0-85413db2dbff",
    "version": 1
  },
  "structured": false,
  "metadata": {
    "objectName": "object",
    "parentObjectName": "parent",
    "xPath": "path",
    "fileExtension": "extension"
  },
  "text": "phone 321-507-0525 number"
}
```

### Request Fields

| Field                   | Type      | Required | Description                                                                                       |
| ----------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------- |
| `context`               | `object`  | Yes      | Context metadata passed through to metrics                                                        |
| `context.actor`         | `string`  | Yes      | `"user"` or `"agent"` — identifies the source of the text                                         |
| `context.agent_id`      | `string`  | Yes      | Unique identifier for the calling agent                                                           |
| `context.platform`      | `string`  | Yes      | AI platform: `AMAZON_BEDROCK`, `AMAZON_SAGEMAKER`, `AZURE_FOUNDRY`, `DATABRICKS`, or `GCP_VERTEX` |
| `classifierDescription` | `object`  | Yes      | Specifies which classifiers to use (see below)                                                    |
| `structured`            | `boolean` | Yes      | Whether the text is structured data                                                               |
| `metadata`              | `object`  | No       | Optional metadata about the content source                                                        |
| `text`                  | `string`  | Yes      | The text to classify                                                                              |

### Classifier Description Types

#### Profile-Based

```json
{
  "type": "profile",
  "uuid": "7dbf380f-0af8-4276-acb0-85413db2dbff",
  "version": 1
}
```

| Field     | Type            | Required | Description                 |
| --------- | --------------- | -------- | --------------------------- |
| `type`    | `string`        | Yes      | `"profile"`                 |
| `uuid`    | `string (UUID)` | Yes      | Classification profile UUID |
| `version` | `integer`       | Yes      | Profile version number      |

#### Code-Based

```json
{
  "type": "codes",
  "codes": [
    { "code": "C1", "version": 1 },
    { "code": "C2", "version": 2 }
  ]
}
```

| Field             | Type      | Required | Description                     |
| ----------------- | --------- | -------- | ------------------------------- |
| `type`            | `string`  | Yes      | `"codes"`                       |
| `codes`           | `array`   | Yes      | List of classifier code objects |
| `codes[].code`    | `string`  | Yes      | Classifier code                 |
| `codes[].version` | `integer` | Yes      | Classifier version              |

#### JSON-Based

```json
{
  "type": "json",
  "classifiers": [
    { "name": "A" },
    { "name": "B" }
  ]
}
```

| Field         | Type     | Required | Description                          |
| ------------- | -------- | -------- | ------------------------------------ |
| `type`        | `string` | Yes      | `"json"`                             |
| `classifiers` | `array`  | Yes      | Inline classifier definition objects |

### Metadata Fields

| Field              | Type     | Description                  |
| ------------------ | -------- | ---------------------------- |
| `objectName`       | `string` | Name of the content object   |
| `parentObjectName` | `string` | Name of the parent object    |
| `xPath`            | `string` | XPath to the content         |
| `fileExtension`    | `string` | File extension of the source |

## Response

### 200 OK — Successful Classification

```json
{
  "context": {
    "actor": "user",
    "agent_id": "my-agent",
    "platform": "AMAZON_BEDROCK"
  },
  "matches": [
    {
      "start": 6,
      "end": 18,
      "confidence": 100,
      "text": "321-507-0525",
      "classifier": "US_PHONE_NUMBER"
    }
  ]
}
```

### Response Fields

| Field                  | Type      | Description                                                          |
| ---------------------- | --------- | -------------------------------------------------------------------- |
| `context`              | `object`  | The context from the request, passed through                         |
| `matches`              | `array`   | List of classification matches (empty if no sensitive data detected) |
| `matches[].start`      | `integer` | Starting character position of the match                             |
| `matches[].end`        | `integer` | Ending character position of the match                               |
| `matches[].confidence` | `integer` | Confidence score (0–100)                                             |
| `matches[].text`       | `string`  | The matched text content                                             |
| `matches[].classifier` | `string`  | Name of the classifier that matched                                  |

### Error Responses

#### 400 Bad Request

```json
{
  "code": 400,
  "message": "Invalid classifier description"
}
```

#### 401 Unauthorized

```json
{
  "code": 401,
  "message": "Invalid or missing bearer token"
}
```

Includes a `WWW-Authenticate` header.

#### 500 Internal Server Error

```json
{
  "code": 500,
  "message": "Classification engine error"
}
```

#### 502 Bad Gateway

```json
{
  "code": 502,
  "message": "Upstream classification service unavailable"
}
```

## curl Example

```bash
curl -X POST https://localhost:4443/classifications/v1 \
  --pinnedpubkey "sha256//x48Lk2iu3R3nAhSiz07bExGHTusDRjHqBx9ArK3cFGE=" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "context": { "actor": "user", "agent_id": "my-agent", "platform": "AMAZON_BEDROCK" },
    "classifierDescription": {
      "type": "profile",
      "uuid": "7dbf380f-0af8-4276-acb0-85413db2dbff",
      "version": 1
    },
    "structured": false,
    "metadata": {
      "objectName": "object",
      "parentObjectName": "parent",
      "xPath": "path",
      "fileExtension": "extension"
    },
    "text": "phone 321-507-0525 number"
  }'
```

## SDK Usage

For Python SDK usage, see [Classify Text](https://developer.onetrust.com/onetrust/docs/ai-guard-classification).