98 lines
3.0 KiB
Markdown
98 lines
3.0 KiB
Markdown
# Description Blocks API
|
|
|
|
Base path: `/api/v1/blocks`
|
|
|
|
All endpoints require `Authorization: Bearer <jwt>`.
|
|
|
|
Related: [[02 - Description Engine]], [[04 - Templates API]], [[04 - Database Schema]]
|
|
|
|
---
|
|
|
|
## GET /blocks
|
|
|
|
List all description blocks for the current team.
|
|
|
|
**Response:** `DescriptionBlock[]`
|
|
|
|
---
|
|
|
|
## GET /blocks/:id
|
|
|
|
Get a single block including its version history.
|
|
|
|
**Response:** `DescriptionBlock` with `versions: BlockVersion[]`
|
|
|
|
---
|
|
|
|
## POST /blocks
|
|
|
|
Create a new description block. Requires `EDITOR` role.
|
|
|
|
**Request body:**
|
|
|
|
```json
|
|
{
|
|
"name": "string",
|
|
"type": "STATIC|VARIABLE|CAMPAIGN|COLLABORATOR|CONDITIONAL",
|
|
"content": "string",
|
|
"language": "de",
|
|
"campaignId": "cuid",
|
|
"compact": false,
|
|
"tags": ["string"],
|
|
"variableDefinitions": []
|
|
}
|
|
```
|
|
|
|
**Field notes:**
|
|
|
|
| Field | Notes |
|
|
|---|---|
|
|
| `type` | See block type behavior below. `GLOBAL` and `REPEATABLE` are kept in the DB enum but are not exposed in the UI. |
|
|
| `campaignId` | Only applicable when `type` is `CAMPAIGN`. Links the block to a campaign date window. |
|
|
| `compact` | Block-level default for whether a blank line precedes the block in the rendered output. Can be overridden per video in `VideoConfig.blockOverrides`. |
|
|
| `variableDefinitions` | Metadata about custom variables used in the block's content. |
|
|
|
|
**Block type behavior:**
|
|
|
|
| Type | Render behavior |
|
|
|---|---|
|
|
| `STATIC` | Raw output, no token substitution |
|
|
| `VARIABLE` | Resolves `{custom_var}`, `{video.*}`, and `{collab.*}` tokens |
|
|
| `CAMPAIGN` | Auto-included at the end of the render when the linked campaign's date window is active (`startAt <= now <= endAt`), regardless of block order |
|
|
| `COLLABORATOR` | Resolved against assigned collaborators |
|
|
| `CONDITIONAL` | Rendered based on condition evaluation |
|
|
|
|
See [[02 - Description Engine]] for full rendering pipeline details.
|
|
|
|
---
|
|
|
|
## PATCH /blocks/:id
|
|
|
|
Update a block. Creates a version snapshot before applying changes. Requires `EDITOR` role.
|
|
|
|
**Request body:** Same fields as `POST /blocks`, all optional.
|
|
|
|
---
|
|
|
|
## DELETE /blocks/:id
|
|
|
|
Delete a block. Requires `ADMIN` role.
|
|
|
|
Returns `409 Conflict` if the block is referenced in any `VideoConfig.blockOrder` or template's `defaultBlocks`. Deletion is blocked until all references are removed. The error message includes the count of affected video configs and templates.
|
|
|
|
---
|
|
|
|
## GET /blocks/:id/versions
|
|
|
|
List the version history for a block, ordered most-recent first.
|
|
|
|
**Response:** `BlockVersion[]`
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- Free-text entries in a video's block order use IDs prefixed `freetext:` — no `DescriptionBlock` row exists for these. Their content comes entirely from `blockOverrides[id].content`.
|
|
- The `{collab.youtube}` token resolves to the full YouTube URL (e.g. `https://www.youtube.com/@handle`), not just the handle. See [[05 - Collaborators API]] for all available `collab.*` tokens.
|
|
- System variable tokens (`video.*`, `collab.*`) are registered in `shared/system-variables/system-variables.registry.ts`. New tokens must be added there or they will never resolve.
|