AI Prompt-Decorator Presets API

Endpoints

• List AI Prompt-Decorator Presets - List built-in and custom prompt-decorator presets
• Get AI Prompt-Decorator Preset - Get a single prompt-decorator preset by name
• Create AI Prompt-Decorator Preset - Create a preset, or update one (built-in or custom) with the same name (upsert)
• Update AI Prompt-Decorator Preset - Update an existing preset, built-in or custom
• Delete AI Prompt-Decorator Preset - Delete a preset, built-in or custom

Authentication

All endpoints require authentication using a Personal API Access Token.

Permissions

• Admin Only - All endpoints require admin privileges (sysAdmin user or a user with the ADMIN role). Presets are a platform-level catalog; a project-scoped AI_DEVELOPMENT token is not sufficient.

Preset Fields

Field	Type	Required	Description
name	string	Yes	Unique preset name within the visible scope
content	string	Yes	The instruction text injected into the request's message list
role	string	No	Role tag of the injected message: system (default), user or assistant
position	string	No	PREPEND (default) or APPEND — where the block lands relative to the client's own messages
category	string	No	Optional grouping label shown in the catalog
description	string	No	Optional description shown in the catalog
enabled	boolean	No	Whether the preset is active (defaults to true)
projectId	string	read-only	Scope the preset belongs to (admin for global)
builtIn	boolean	read-only	true for Mongock-seeded rows, false for user-created

Blank role / position values normalize to system / PREPEND; any other value is rejected. builtIn is server-owned and ignored in request bodies — a client cannot forge a built-in preset.

Built-in Presets Are Editable

A seeded preset (builtIn: true) is not read-only: PUT and DELETE on this surface accept it the same as a custom preset, gated by the same admin permission every endpoint here requires. Deleting one is permanent — Mongock deduplicates seed changesets by id and none of them are runAlways=true, so a deleted built-in preset does not reappear on a version upgrade; it returns only if a future release ships an explicit re-seed changeset. See Prompt Decorator for the same behavior as seen from the Manager UI.

Import Semantics

Importing a preset into a Prompt Decorator policy copies its values into a new, independent block. The block keeps no reference back to the catalog entry, so editing or deleting a preset afterwards never changes a policy that already imported it, and no redeploy is implied by any endpoint on this page.

Project-Scoped Surface

Besides the admin/global endpoints above (/apiops/settings/ai-prompt-decorator-presets/...), the same preset family is also exposed under a project-scoped path, so a project's own AI_DEVELOPMENT token can read the effective catalog and manage its own custom presets without needing platform ADMIN privileges:

GET    /apiops/projects/{projectName}/ai-prompt-decorator-presets/
GET    /apiops/projects/{projectName}/ai-prompt-decorator-presets/{presetName}/
POST   /apiops/projects/{projectName}/ai-prompt-decorator-presets/{presetName}/
PUT    /apiops/projects/{projectName}/ai-prompt-decorator-presets/{presetName}/
DELETE /apiops/projects/{projectName}/ai-prompt-decorator-presets/{presetName}/

Same 5-endpoint shape, request/response bodies and field surface as the admin endpoints documented on this page — 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	Presets in the resolved scope only	Union of built-in presets ∪ admin-shared custom presets ∪ this project's own custom presets
Write visibility	Any preset in the resolved scope, including built-in	Only presets this project owns. A name that only resolves to a built-in or admin-shared preset is treated as not existing for this project: POST creates a new project-owned preset (and fails on the name collision), while PUT/DELETE report the preset as not found

Related Documentation

• Authentication Guide - How to obtain and use API tokens
• Error Handling - Error response formats
• Prompt Decorator - What the policy does with these blocks
• AI Prompt-Guard Presets API - Manage AI prompt-guard presets
• AI Privacy Presets API - Manage AI privacy (PII) presets
• AI DLP Presets API - Manage AI DLP (secret/credential) presets