# 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.