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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

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

401 Unauthorized

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

Includes a WWW-Authenticate header.

500 Internal Server Error

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

502 Bad Gateway

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

curl Example

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.