103 lines
3.6 KiB
Markdown
103 lines
3.6 KiB
Markdown
# Video Configs API
|
|
|
|
Base path: `/api/v1/video-configs`
|
|
|
|
All endpoints require `Authorization: Bearer <jwt>`.
|
|
|
|
Related: [[02 - Videos API]], [[07 - Render Engine]], [[04 - Templates API]]
|
|
|
|
---
|
|
|
|
## GET /video-configs/:videoId
|
|
|
|
Returns the current `VideoConfig` for a video.
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"id": "cuid",
|
|
"videoId": "cuid",
|
|
"templateId": "cuid or null",
|
|
"blockOrder": ["blockId1", "freetext:abc123"],
|
|
"blockOverrides": {
|
|
"blockId1": { "content": "override text", "active": true, "compact": false }
|
|
},
|
|
"variableValues": {
|
|
"sponsor_name": "Acme Corp"
|
|
},
|
|
"version": 3,
|
|
"renderHash": "sha256hex or null",
|
|
"renderedAt": "ISO datetime or null",
|
|
"createdAt": "ISO datetime",
|
|
"updatedAt": "ISO datetime"
|
|
}
|
|
```
|
|
|
|
Returns `null` if the video has no config yet.
|
|
|
|
---
|
|
|
|
## PUT /video-configs/:videoId
|
|
|
|
Save (create or update) the description config for a video. Requires `EDITOR` role.
|
|
|
|
This is the endpoint the video editor calls when the user saves their block configuration.
|
|
|
|
**Request body:**
|
|
|
|
```json
|
|
{
|
|
"blockOrder": ["blockId1", "freetext:abc123"],
|
|
"blockOverrides": {
|
|
"blockId1": { "content": "override text", "active": true, "compact": false },
|
|
"freetext:abc123": { "content": "free text content", "compact": false }
|
|
},
|
|
"variableValues": {
|
|
"sponsor_name": "Acme Corp"
|
|
},
|
|
"templateId": "cuid",
|
|
"collaboratorIds": ["collabId1"],
|
|
"autoRender": true
|
|
}
|
|
```
|
|
|
|
| Field | Required | Notes |
|
|
|---|---|---|
|
|
| `blockOrder` | Yes | Ordered array of block IDs. May include `freetext:<id>` entries — these have no DB block; content comes from `blockOverrides`. |
|
|
| `blockOverrides` | Yes | Per-block overrides for content, active state, and compact flag. |
|
|
| `variableValues` | Yes | Video-level custom variable values. Override team variables on name collision. |
|
|
| `templateId` | No | Associates the config with a template. Does not re-apply template defaults — it is a reference only. |
|
|
| `collaboratorIds` | No | Updates `Video.collaboratorIds` on the video row. Controls which collaborators are resolved during description rendering. |
|
|
| `autoRender` | No | If `true`, enqueues a background render job after saving. Updates `Video.renderedDescription` asynchronously. |
|
|
|
|
**Response:** The saved `VideoConfig` row (same shape as GET response above).
|
|
|
|
**Notes:**
|
|
- `version` is auto-incremented on every save.
|
|
- `collaboratorIds` in the request body updates `Video.collaboratorIds` — this is handled separately from the `VideoConfig` fields. The VideoConfig row itself does not store collaborator IDs.
|
|
- If `autoRender` is omitted or `false`, the description is not re-rendered immediately. The rendered description updates only when a sync job runs or the render queue processes a background render.
|
|
|
|
---
|
|
|
|
## POST /video-configs/:videoId/render-preview
|
|
|
|
Render the description using the provided config, without saving anything. Used by the video editor's live preview panel.
|
|
|
|
**Request body:** Same shape as `PUT /video-configs/:videoId`.
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"rendered": "Full rendered description string",
|
|
"hash": "sha256hex"
|
|
}
|
|
```
|
|
|
|
**Notes:**
|
|
- Nothing is persisted. The video's `renderedDescription`, `lastSyncedHash`, and `VideoConfig` row are all unchanged.
|
|
- The preview renders against live data: the video's current metadata, active campaigns, and team variables at the time of the call.
|
|
- `collaboratorIds` in the request body is used for the preview render directly — it does not need to match the currently saved `Video.collaboratorIds`. This allows the editor to preview with a collaborator selection before saving.
|
|
- Active campaign blocks are appended automatically if their date window is currently active.
|