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:

{
  "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:

{
  "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.