Templates API

Notification templates let you define reusable title and body content that can be referenced when sending notifications. Templates are scoped to your tenant and are never shared across accounts.

POST /api/v1/templates

Creates a new notification template.

Request Body

{
  "name": "welcome-email",
  "content": {
    "title": "Welcome to Acme!",
    "body": "Thanks for signing up. Tap to get started."
  }
}

Field	Type	Required	Description
name	string	Yes	A unique, human-readable identifier for the template.
content.title	string	Yes	The notification title shown to recipients.
content.body	string	Yes	The notification body text shown to recipients.

Response — 201 Created

{
  "id": "tpl_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "welcome-email",
  "content": {
    "title": "Welcome to Acme!",
    "body": "Thanks for signing up. Tap to get started."
  },
  "created_at": "2026-04-25T12:00:00Z"
}

Error Codes

Status	Reason
401	Missing or invalid bearer token.
422	name is missing, a template with that name already exists, or one or more content fields (title, body) are absent.

---

GET /api/v1/templates

Returns a paginated list of templates for the authenticated tenant.

Query Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (1-based).
per_page	integer	20	Number of results per page.
name	string	—	Optional. Filter results to templates whose name contains this value (case-insensitive).

Response — 200 OK

{
  "data": [
    {
      "id": "tpl_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "welcome-email",
      "content": {
        "title": "Welcome to Acme!",
        "body": "Thanks for signing up. Tap to get started."
      },
      "created_at": "2026-04-25T12:00:00Z"
    }
  ],
  "total": 12,
  "page": 1
}

---

GET /api/v1/templates/:id

Retrieves a single template by its UUID.

Response — 200 OK

{
  "id": "tpl_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "welcome-email",
  "content": {
    "title": "Welcome to Acme!",
    "body": "Thanks for signing up. Tap to get started."
  },
  "created_at": "2026-04-25T12:00:00Z"
}

Error Codes

Status	Reason
401	Missing or invalid bearer token.
404	No template found with that ID, or it belongs to a different tenant.

---

PATCH /api/v1/templates/:id

Updates an existing template. At least one of name or content must be provided. All supplied fields overwrite the stored values; omitted fields are left unchanged.

Request Body

{
  "name": "welcome-push",
  "content": {
    "title": "Welcome aboard!",
    "body": "Tap here to explore your new account."
  }
}

Field	Type	Required	Description
name	string	No	New unique name for the template.
content.title	string	No	Updated notification title.
content.body	string	No	Updated notification body.

At least one field (name, content.title, or content.body) must be present or the request returns 422.

Response — 200 OK

Returns the full updated template object:

{
  "id": "tpl_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "welcome-push",
  "content": {
    "title": "Welcome aboard!",
    "body": "Tap here to explore your new account."
  },
  "created_at": "2026-04-25T12:00:00Z"
}

Error Codes

Status	Reason
401	Missing or invalid bearer token.
404	Template not found or cross-tenant access attempted.
422	Request body is empty, or the new name conflicts with an existing template.

---

DELETE /api/v1/templates/:id

Permanently deletes a template. This action is irreversible.

warning

Deleting a template does not cancel or update notification jobs that were already scheduled using it. Any scheduled notification that still references the deleted template ID will fail to send. Review and cancel affected jobs before deleting a template.

Response — 204 No Content

An empty body is returned on success.

Error Codes

Status	Reason
401	Missing or invalid bearer token.
404	Template not found or cross-tenant access attempted.