AI Content-Safety Categories API
Endpoints
- List AI Content-Safety Categories - List built-in and custom entries
- Get AI Content-Safety Category - Get a single entry by name
- Create AI Content-Safety Category - Create or update an entry (upsert)
- Update AI Content-Safety Category - Update an existing entry
- Delete AI Content-Safety Category - Delete an entry
Authentication
All endpoints require authentication using a Personal API Access Token.
Permissions
- Admin Only - All endpoints on this page require admin privileges (sysAdmin user or a user with the
ADMINrole). This is a platform-level catalog; a project-scopedAI_DEVELOPMENTtoken is not sufficient here. See Project-Scoped Surface below for the endpoints a project token can use.
Fields
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Unique category name within the visible scope |
| code | string | Yes | Short category code, lower-cased on save. Shipped rows use AILuminate codes (vcr, ipv, spc_hlt, …) |
| topicText | string | Yes | The canonical (English) definition used for embedding-similarity comparison |
| topicTextTr | string | No | Turkish twin of topicText |
| displayName | string | No | Label shown in the catalog; defaults to name when blank |
| displayNameTr | string | No | Turkish twin of displayName |
| group | string | No | PHYSICAL, NON_PHYSICAL or CONTEXTUAL. Blank is derived from code for shipped codes, otherwise defaults to NON_PHYSICAL; any other value is rejected |
| description | string | No | Free-text description |
| descriptionTr | string | No | Turkish twin of description |
| llamaGuardCode | string | No | Llama Guard 3 safety code (S1…S13). Leave empty for your own categories — see below |
| gdprArticle9 | boolean | No | Marks a category touching GDPR Art.9 special-category personal data |
| taxonomyVersion | string | No | Source taxonomy version for shipped rows |
| enabled | boolean | No | Whether the category is active (defaults to true) |
| projectId | string | read-only | Scope the category belongs to (admin for global) |
| builtIn | boolean | read-only | true for Mongock-seeded rows, false for user-created |
builtIn is server-owned and ignored in request bodies — a client cannot forge a built-in entry.
Notes
llamaGuardCode is optional and should stay empty on categories you add. The AILuminate-to-Llama-Guard mapping lives in product code and only covers the shipped 14 rows; a category you create has no counterpart. Inventing an S-code makes an external judge's verdict trace back to the wrong category.
Shipped categories are editable and deletable, and deletion is permanent. Mongock deduplicates changesets by id and no seed changeset is runAlways=true, so a seed that has already run does not run again — a deleted shipped category does not reappear on a version upgrade. It returns only if a future release ships an explicit re-seed changeset. Rewording one is allowed but breaks its link to the cited MLCommons standard.
No redeploy is implied. Off-Topic Protection policies snapshot-copy topicText rather than referencing a category id, so writes here never change a policy that already uses one.
Project-Scoped Surface
Besides the admin/global endpoints above (/apiops/settings/ai-topic-category-presets/...), the same family is exposed under a project-scoped path, so a project's own AI_DEVELOPMENT token can read the effective catalog and manage its own entries without platform ADMIN privileges:
GET /apiops/projects/{projectName}/ai-topic-category-presets/
GET /apiops/projects/{projectName}/ai-topic-category-presets/{entryName}/
POST /apiops/projects/{projectName}/ai-topic-category-presets/{entryName}/
PUT /apiops/projects/{projectName}/ai-topic-category-presets/{entryName}/
DELETE /apiops/projects/{projectName}/ai-topic-category-presets/{entryName}/
Same 5-endpoint shape, request/response bodies and field surface as the admin endpoints — only the base path, scope resolution and permission differ:
Admin surface (/apiops/settings/...) | Project surface (/apiops/projects/{projectName}/...) | |
|---|---|---|
| Scope resolution | Optional ?projectId= query parameter (default admin/global scope) | {projectName} path segment, resolved to the caller's own project — never a query parameter |
| Permission | System admin (sysAdmin user or ADMIN role) | AI_DEVELOPMENT + VIEW (read) / MANAGE (write) in the project |
| Read visibility | Entries in the resolved scope only | Union of built-in ∪ admin-shared ∪ this project's own entries |
| Write visibility | Any entry in the resolved scope | Only entries this project owns. A name that resolves only to a built-in or admin-shared row is treated as not existing for this project: POST creates a project-owned copy, while PUT/DELETE report it as not found |
Related Documentation
- Authentication Guide - How to obtain and use API tokens
- Error Handling - Error response formats
- Advanced Guardrails - What the catalog is for
- AI Prompt Templates API - Manage AI prompt templates
- AI DLP Presets API - Manage AI DLP presets