> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kaireonai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates

> Manage reusable content templates for creatives and communications.

Templates provide reusable content structures for creatives, emails, and other communications. They support variables for dynamic personalization.

## GET /api/v1/templates

List templates, optionally filtered by category.

### Query Parameters

| Parameter  | Type   | Required | Description                                                 |
| ---------- | ------ | -------- | ----------------------------------------------------------- |
| `category` | string | No       | Filter by category (e.g., `email`, `sms`, `push`, `banner`) |

### Response

```json theme={null}
[
  {
    "id": "clx...",
    "name": "Welcome Email",
    "description": "New customer welcome email template",
    "category": "email",
    "type": "html",
    "content": { "subject": "Welcome!", "body": "<h1>Hello {{name}}</h1>..." },
    "variables": { "name": "string", "offer_name": "string" },
    "isSystem": false,
    "tenantId": "my-tenant",
    "createdAt": "2026-03-18T12:00:00.000Z"
  }
]
```

***

## POST /api/v1/templates

Create a new template. **Editor or Admin.**

### Request Body

| Field         | Type    | Required | Description                                                |
| ------------- | ------- | -------- | ---------------------------------------------------------- |
| `name`        | string  | Yes      | Template name (max 255 chars, unique per tenant)           |
| `description` | string  | No       | Template description                                       |
| `category`    | string  | Yes      | Template category (e.g., `email`, `sms`, `push`, `banner`) |
| `type`        | string  | Yes      | Content type (e.g., `html`, `text`, `json`)                |
| `content`     | object  | Yes      | Template content (structure depends on type)               |
| `variables`   | object  | No       | Variable definitions with types                            |
| `isSystem`    | boolean | No       | Mark as system template (default: false)                   |

### Example

```bash theme={null}
curl -X POST https://playground.kaireonai.com/api/v1/templates \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: my-tenant" \
  -d '{
    "name": "Promotional Banner",
    "category": "banner",
    "type": "json",
    "content": {
      "headline": "{{headline}}",
      "cta": "{{cta_text}}",
      "image_url": "{{image}}"
    },
    "variables": {
      "headline": "string",
      "cta_text": "string",
      "image": "string"
    }
  }'
```

### Response (201)

Returns the created template object.

***

## GET /api/v1/templates/{id}

Get a single template by ID.

***

## PUT /api/v1/templates/{id}

Update a template. **Editor or Admin.**

### Request Body

Same fields as POST, all optional.

***

## DELETE /api/v1/templates/{id}

Delete a template. System templates cannot be deleted. **Admin only.**

### Response

`204 No Content` on success.

### Error — System Template (`400`)

```json theme={null}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "System templates cannot be deleted"
  }
}
```