126 lines
2.9 KiB
Markdown
126 lines
2.9 KiB
Markdown
# 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`
|