AI Classification API
The AI Classification API creates reviewable field classification suggestions for catalog products. It combines built-in pattern matching, optional LLM inference, and optional lineage propagation, then stores suggestions for steward review.
All paths below are under /api/v1.0/ai. The API is feature-gated by ai.classification_enabled.
Endpoints
| Method | Endpoint | Description |
|---|---|---|
POST | /classify/product/{product_id} | Run classification for all fields in a product. |
GET | /classify/suggestions | List classification suggestions with filters and pagination. |
POST | /classify/suggestions/{suggestion_id}/review | Accept or reject one suggestion. |
POST | /classify/suggestions/bulk-review | Accept or reject multiple suggestions. |
Permissions
| Endpoint | Required access |
|---|---|
| Run product classification | Product edit permission. |
List by product_id | Product view permission. |
List by space_id | Space access. |
| List without product or space filter | Suggestions from the caller's accessible spaces only. |
| Review or bulk review | Product edit permission for the suggestion's product. |
Classification Sources
Classification can produce suggestions from three sources:
| Source | Behavior |
|---|---|
pattern | Matches field names against built-in PII patterns. |
llm | Uses the configured AI provider for fields not already matched or explicitly classified. |
lineage | Propagates sensitivity, PII, PHI, or confidential flags from upstream products with same-named fields. |
Fields with explicit sensitivity are skipped for LLM classification. Lineage propagation inspects up to the first 10 upstream product IDs in the product lineage metadata.
Run Product Classification
POST /api/v1.0/ai/classify/product/{product_id}
Request Body
{
"include_llm": true,
"include_lineage": true
}
| Field | Type | Description |
|---|---|---|
include_llm | boolean | Use the AI provider for fields not matched by pattern rules. Default true. |
include_lineage | boolean | Propagate classifications from upstream lineage when possible. Default true. |
Response
{
"product_id": "550e8400-e29b-41d4-a716-446655440000",
"total_suggestions": 3,
"pattern_matches": 1,
"llm_suggestions": 1,
"lineage_suggestions": 1,
"suggestions": [
{
"id": "941077a0-60c3-441b-8905-427db7599b40",
"product_id": "550e8400-e29b-41d4-a716-446655440000",
"field_id": "7c3d9b10-f1f8-4388-9d47-9f1f37c2ed8a",
"field_name": "customer_email",
"space_id": "2a2423bd-c759-48cf-9588-7f21c12fba8c",
"suggestion_type": "pii_flag",
"suggested_value": "true",
"confidence": "high",
"confidence_score": 0.95,
"source": "pattern",
"source_detail": {
"pattern_name": "email",
"matched_field": "customer_email"
},
"status": "pending",
"reviewed_by_id": null,
"reviewed_at": null,
"created_at": "2026-06-29T09:00:00Z"
}
]
}
List Suggestions
GET /api/v1.0/ai/classify/suggestions?product_id={product_id}&status=pending&skip=0&limit=50
Query Parameters
| Parameter | Type | Description |
|---|---|---|
product_id | UUID | Filter by product. Requires product view permission. |
space_id | UUID | Filter by space. Requires space access. |
status | string | Filter by suggestion status. Common values are pending, accepted, and rejected. |
skip | integer | Number of suggestions to skip. Default 0. |
limit | integer | Number of suggestions to return. Default 50, maximum 200. |
Suggestions are ordered newest first.
Review One Suggestion
POST /api/v1.0/ai/classify/suggestions/{suggestion_id}/review
Request Body
{
"action": "accepted"
}
action must be accepted or rejected.
Accepting a suggestion stores reviewed_by_id and reviewed_at, changes the suggestion status, and applies supported field or product metadata changes:
| Suggestion type | Accepted side effect |
|---|---|
sensitivity with field_id | Updates DataField.sensitivity. |
sensitivity without field_id | Updates DataProduct.sensitivity. |
pii_flag or is_pii | Updates DataField.is_pii. |
phi_flag or is_phi | Updates DataField.is_phi. |
confidential_flag or is_confidential | Updates DataField.is_confidential. |
tag | Records review status only; product tag mutation is not applied by this endpoint. |
Rejecting a suggestion records review metadata but does not mutate product or field metadata.
Bulk Review
POST /api/v1.0/ai/classify/suggestions/bulk-review
Request Body
{
"suggestion_ids": [
"941077a0-60c3-441b-8905-427db7599b40",
"a5f3ca83-d058-4020-9e3e-af854d9ed842"
],
"action": "accepted"
}
Bulk review only updates suggestions that are still pending. The response reports how many rows were updated.
Response
{
"updated_count": 2,
"action": "accepted"
}
Errors
| Status | Description |
|---|---|
400 | Invalid bulk review action or mixed suggestion access failure. |
401 | Authentication is missing or invalid. |
403 | Feature is unavailable, or the caller lacks required product or space access. |
404 | Suggestion was not found for single review. |
422 | Request body or query parameters failed validation. |