AI Prompt Templates API

Endpoints

• List AI Prompt Templates - List built-in and custom entries
• Get AI Prompt Template - Get a single entry by name
• Create AI Prompt Template - Create or update an entry (upsert)
• Update AI Prompt Template - Update an existing entry
• Delete AI Prompt Template - 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 ADMIN role). This is a platform-level catalog; a project-scoped AI_DEVELOPMENT token 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 template name within the visible scope
messages	array	Yes	Ordered message list; each entry carries a role (system/user/assistant) and content
parameters	array	No	Declared parameters the messages interpolate
description	string	No	Free-text description
enabled	boolean	No	Whether the template is active (defaults to true)
projectId	string	read-only	Scope the template 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

Bound policies are updated. Unlike the preset catalogs, a prompt template keeps a binding to the policies that use it; updating a template propagates the change to those policies (AiPromptTemplatePropagationService). These endpoints do not add to or change that behaviour — they expose the same service that the Manager screens already call.

Shipped templates are editable and deletable, and deletion is permanent. Mongock deduplicates changesets by id and no seed changeset is runAlways=true, so a deleted shipped template does not reappear on a version upgrade — it returns only if a future release ships an explicit re-seed changeset.

Project-Scoped Surface

Besides the admin/global endpoints above (/apiops/settings/ai-prompt-templates/...), 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-prompt-templates/
GET    /apiops/projects/{projectName}/ai-prompt-templates/{entryName}/
POST   /apiops/projects/{projectName}/ai-prompt-templates/{entryName}/
PUT    /apiops/projects/{projectName}/ai-prompt-templates/{entryName}/
DELETE /apiops/projects/{projectName}/ai-prompt-templates/{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
• Prompt Templates - What the policy does with these templates
• AI Content-Safety Categories API - Manage content-safety categories
• AI Prompt-Decorator Presets API - Manage prompt-decorator presets