# Templates API

Base path: `/api/v1/templates`

All endpoints require `Authorization: Bearer <jwt>`.

Related: [[02 - Description Engine]], [[03 - Blocks API]], [[02 - Videos API]]

---

## GET /templates

List all active templates for the current team.

**Response:** `Template[]`

---

## GET /templates/:id

Get a single template by ID.

**Response:** `Template`

---

## POST /templates

Create a new template. Requires `EDITOR` role.

**Request body:**

```json
{
  "name": "string",
  "description": "string",
  "defaultBlocks": ["blockId", "freetext:uuid"],
  "defaultOverrides": {},
  "rules": {
    "requiredLinks": ["https://..."]
  },
  "variables": {},
  "videoFields": {
    "privacyStatus": "PUBLIC",
    "tags": ["tag1"]
  }
}
```

**Field notes:**

| Field | Notes |
|---|---|
| `description` | Optional human-readable description of the template's purpose. |
| `defaultBlocks` | Ordered list of block IDs. May include `freetext:uuid` entries for inline free-text entries. |
| `defaultOverrides` | Per-block overrides in the same shape as `VideoConfig.blockOverrides`. Stores free-text content keyed by `freetext:*` ID. |
| `rules` | Optional lint/validation rules applied when the template is in use, e.g. required links. |
| `variables` | Default variable values to seed into `VideoConfig.variableValues` when the template is applied. |
| `videoFields` | Video metadata fields to apply when the template is applied to a video (e.g. `privacyStatus`, `tags`). |

---

## PATCH /templates/:id

Update a template. Requires `EDITOR` role.

**Request body:** Same fields as `POST /templates`, all optional.

---

## DELETE /templates/:id

Delete a template. Requires `ADMIN` role.

---

## POST /templates/:id/preview

Render a preview of the template's description for a given variable context. Does not require a video — useful for inspecting template output before applying.

**Request body:**

```json
{
  "variableValues": {
    "custom_var": "value"
  }
}
```

**Response:**

```json
{ "rendered": "string" }
```

---

## Version history

`TemplateVersion` rows are written to the database on every `PATCH /templates/:id` call, storing a snapshot of the template content before the update. When a template is deleted, its version rows are also deleted.

There is **no `GET /templates/:id/versions` endpoint**. The version history is stored but unreachable via the API. Template version history is not exposed to the frontend. See the backlog.

---

## POST /templates/:templateId/apply/:videoId

Apply a template to a specific video. Requires `EDITOR` role.

When applied:
- `template.defaultBlocks` is written to `VideoConfig.blockOrder`
- `template.defaultOverrides` is written to `VideoConfig.blockOverrides`
- If `applyVideoFields` is `true`, video metadata fields from `template.videoFields` are applied to the video row

**Request body:**

```json
{
  "applyVideoFields": true,
  "applyDescriptionConfig": true
}
```

**Response:** Updated `VideoDetail`