Overlays are editable timeline items that appear above video. The supported public text layer is the same layer shown in the dashboard under **Combined Text > Text**.

Use `/content-items` with `kind: "overlay"` for normal text. Retired overlay and generated graphics routes are not part of the public agent-facing API.

## Endpoints [#endpoints]

* `GET /v1/projects/{project_id}/content-items`
* `POST /v1/projects/{project_id}/content-items`
* `PATCH /v1/projects/{project_id}/content-items/{content_item_id}`
* `DELETE /v1/projects/{project_id}/content-items/{content_item_id}`

## Add an Editable Text Overlay [#add-an-editable-text-overlay]

```bash title="Terminal"
curl -X POST https://blitzreels.com/api/v1/projects/{project_id}/content-items \
  -H "Authorization: Bearer $BLITZREELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "overlay",
    "text": "5 Productivity Tips",
    "start_seconds": 0,
    "duration_seconds": 3,
    "layer_index": 1
  }'
```

```json title="Response"
{
  "success": true,
  "timeline_item_id": "timeline-item-uuid",
  "content_item_id": "content-item-uuid",
  "playground_composition_id": "overlay-renderer-uuid",
  "watermark_id": null
}
```

## List and Edit Overlays [#list-and-edit-overlays]

```bash title="Terminal"
curl https://blitzreels.com/api/v1/projects/{project_id}/content-items \
  -H "Authorization: Bearer $BLITZREELS_API_KEY"
```

Use the returned `timeline_item_id` with Timeline API routes for timing and placement:

* `POST /v1/projects/{project_id}/timeline/move`
* `POST /v1/projects/{project_id}/timeline/transform`
* `POST /v1/projects/{project_id}/timeline/batch-transform`

Update metadata or delete the overlay:

```bash title="Terminal"
curl -X PATCH https://blitzreels.com/api/v1/projects/{project_id}/content-items/{content_item_id} \
  -H "Authorization: Bearer $BLITZREELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Opening hook" }'
```

```bash title="Terminal"
curl -X DELETE https://blitzreels.com/api/v1/projects/{project_id}/content-items/{content_item_id} \
  -H "Authorization: Bearer $BLITZREELS_API_KEY"
```

## Placement Tips [#placement-tips]

* Keep overlays on higher layers so they stay visible above B-roll.
* Use Timeline API move/transform routes after creation for exact placement.
* Preview frames before export when overlays sit near captions or platform safe zones.

## Related [#related]

* [Timeline Editing API](/docs/timeline)
* [Captions API](/docs/captions)
* [Backgrounds API](/docs/backgrounds)