Prompt Templates

Prompt templates define AI generation parameters used by triggers to generate message variants. A template specifies the system role, objective, tone, and channel-specific settings (SMS emoji/segments, email subject style/length). Templates track usageCount — how many triggers reference them — and cannot be deleted while in use.

All endpoints require authentication via the X-API-Key header. See Authentication.

Create a prompt template

POST /trigger-prompt-templates

Request body

Field	Type	Required	Notes
`name`	string	Yes
`description`	string	Yes
`category`	string	Yes	`welcome_thankyou`, `reengagement`, `milestone`, `highvalue`, `lowengagement`, `general`, or `custom`.
`type`	string	Yes	`sms`, `email`, or `video_script`.
`systemRole`	string	Yes	AI system instructions.
`messageObjective`	string	Yes	What the generated message should achieve.
`tone`	string	Yes	`warm_personal`, `professional`, `casual`, `grateful`, or `urgent`.
`promptTemplate`	string	Yes	The AI prompt text with placeholders.
`smsIncludeEmoji`	boolean	Yes	Whether to include emoji in SMS output.
`emailSubjectStyle`	string	Yes	`short`, `descriptive`, or `curiosity`.
`smsSegmentLimit`	number	Yes	Min 1. Max SMS segments.
`emailLength`	string	Yes	`brief`, `moderate`, or `detailed`.
`variantsCount`	number	Yes	1–3. Number of message variants to generate.
`createdBy`	string	Yes	User ID.

Example request

curl -X POST https://<host>/api/trigger-prompt-templates \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Donor Thank You",
    "description": "Thank donors for recent contributions",
    "category": "welcome_thankyou",
    "type": "sms",
    "systemRole": "You are a grateful fundraising coordinator.",
    "messageObjective": "Thank the donor and reinforce their impact",
    "tone": "grateful",
    "promptTemplate": "Write a thank you message for {{firstName}} who donated {{lastTransactionAmount}}.",
    "smsIncludeEmoji": true,
    "emailSubjectStyle": "short",
    "smsSegmentLimit": 3,
    "emailLength": "brief",
    "variantsCount": 2,
    "createdBy": "675a..."
  }'

Response

{
  "success": true,
  "data": {
    "_id": "675a...",
    "name": "Donor Thank You",
    "category": "welcome_thankyou",
    "type": "sms",
    "tone": "grateful",
    "variantsCount": 2,
    "usageCount": 0,
    "createdAt": "2026-03-24T12:00:00.000Z"
  }
}

Errors

Status	Message	Cause
400	Validation error	Missing required fields or invalid enum values.

List prompt templates

GET /trigger-prompt-templates

Returns templates sorted by createdAt descending.

Query parameters

Parameter	Type	Default	Notes
`category`	string	—	Filter by category.
`type`	string	—	Filter: `sms`, `email`, `video_script`.
`tone`	string	—	Filter by tone.
`page`	number	0	0-indexed.
`perPage`	number	50	Items per page.

Example request

curl "https://<host>/api/trigger-prompt-templates?type=sms&page=0" \
  -H "X-API-Key: your-api-key"

Response

{
  "success": true,
  "data": [
    {
      "_id": "675a...",
      "name": "Donor Thank You",
      "category": "welcome_thankyou",
      "type": "sms",
      "tone": "grateful",
      "variantsCount": 2,
      "usageCount": 1,
      "createdAt": "2026-03-24T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 0,
    "perPage": 50,
    "totalItems": 5,
    "totalPages": 1
  }
}

Get a prompt template

GET /trigger-prompt-templates/:id

Path parameters

Parameter	Type	Description
`id`	string	Template ID.

Example request

curl "https://<host>/api/trigger-prompt-templates/675a..." \
  -H "X-API-Key: your-api-key"

Errors

Status	Message	Cause
404	Not found	Template does not exist.

Update a prompt template

PUT /trigger-prompt-templates/:id

All fields from create are accepted as optional.

Path parameters

Parameter	Type	Description
`id`	string	Template ID.

Example request

curl -X PUT https://<host>/api/trigger-prompt-templates/675a... \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tone": "professional",
    "variantsCount": 3
  }'

Response

Returns the updated template.

Errors

Status	Message	Cause
404	Not found	Template does not exist.

Delete a prompt template

DELETE /trigger-prompt-templates/:id

Cannot delete a template that is in use by triggers (usageCount > 0).

Path parameters

Parameter	Type	Description
`id`	string	Template ID.

Example request

curl -X DELETE https://<host>/api/trigger-prompt-templates/675a... \
  -H "X-API-Key: your-api-key"

Response

{
  "success": true,
  "message": "Success"
}

Errors

Status	Message	Cause
400	Cannot delete template that is in use	`usageCount > 0` — template is referenced by active triggers.
404	Not found	Template does not exist.

Response envelope

All endpoints use the standard envelope:

{
  "error": false,
  "success": true,
  "message": "...",
  "code": 200,
  "data": "...",
  "pagination": {}
}

Error responses:

{
  "error": true,
  "success": false,
  "message": "...",
  "code": 400,
  "data": null
}

data is null for a general failure, such as a database error or an upstream timeout. When the request is rejected because of a specific field, data carries the field(s) at fault instead:

{
  "error": true,
  "success": false,
  "message": "phone: Phone parse failed: The string supplied did not seem to be a phone number (input: <masked>)",
  "code": 400,
  "data": {
    "issues": [
      {
        "path": "phone",
        "message": "Phone parse failed: The string supplied did not seem to be a phone number (input: <masked>)"
      }
    ]
  }
}

Each issue carries a path (the dotted path into the request body) and a message. A label is added when the path is not self-describing, which today means custom fields only, for example "path": "fields.68b0a1f39c2e4d0012ab77e5", "label": "Class Year". issues is an array, but treat it as holding at most one entry: validation stops at the first failure.

On this page