Episodes

An episode belongs to a project and contains scenes, creator assignments, and a lifecycle status.

Endpoints overview

Method	Endpoint	Permission	Description
GET	/api/episodes	authenticated	List all episodes
GET	/api/episodes/project/:projectId	authenticated	List episodes by project
GET	/api/episodes/:id	authenticated	Get episode by ID
GET	/api/episodes/roles	authenticated	Get workflow roles
GET	/api/episodes/assignment-template	authenticated	Get assignment template
PUT	/api/episodes/assignment-template	template:edit	Save assignment template
POST	/api/episodes	episode:create	Create an episode
PUT / PATCH	/api/episodes/:id	episode:edit	Update an episode
DELETE	/api/episodes/:id	episode:delete	Delete an episode
POST	/api/episodes/preview/upload	episode:preview:upload	Upload episode preview video
GET	/api/episodes/preview/file/:projectId/:episodeId/preview/:filename	authenticated	Get preview video file
DELETE	/api/episodes/preview/:projectId/:episodeId	episode:preview:delete	Delete episode preview
POST	/api/episodes/import/prepare	episode:import	Prepare episode import
POST	/api/episodes/import	episode:import	Import episode from video
GET	/api/episodes/import/:jobId/progress	authenticated	Get import job progress

Endpoints

List all episodes

GET /api/episodes — Auth required

Supports optional filters. When no params are supplied, all episodes are returned.

Query params (all optional)

Param	Type	Description
projectId	string	Filter by project UUID
search	string	Full-text search on title
status	string	draft | active | completed | paused
sortBy	string	episodeNumber | title | createdAt | updatedAt
sortOrder	string	asc | desc
limit	number	Page size
offset	number	Page offset

Response — 200

{
  "episodes": [
    {
      "id": "ep-uuid-001",
      "code": "ep01",
      "projectId": "proj-uuid-001",
      "episodeNumber": 1,
      "title": "Episode 1 — The Beginning",
      "description": "Pilot episode",
      "titleI18n": { "uk": "Епізод 1", "en": "Episode 1 — The Beginning", "es": "Episodio 1" },
      "descriptionI18n": { "uk": "Пілотний епізод", "en": "Pilot episode", "es": "Episodio piloto" },
      "icon": null,
      "previewUrl": null,
      "targetDuration": 300,
      "status": "draft",
      "safety": null,
      "isLocked": false,
      "tasks": [
        {
          "taskId": "task-uuid",
          "status": "to-do",
          "roleId": "role-uuid",
          "roleName": "Script Writer",
          "roleNameI18n": { "uk": "Сценарист", "en": "Script Writer", "es": "Guionista" },
          "userId": "user-uuid",
          "userEmail": "writer@example.com",
          "userEnName": "Alice",
          "userEnSurname": "Brown",
          "userUaName": "Аліса",
          "userUaSurname": "Браун",
          "order": 1
        }
      ],
      "createdAt": "2025-01-11T09:00:00.000Z",
      "updatedAt": "2025-01-11T09:00:00.000Z",
      "approved": false,
      "templateId": null
    }
  ],
  "total": 1,
  "filtered": 1
}

---

List episodes by project

GET /api/episodes/project/:projectId — Auth required

Response — 200

{
  "episodes": [ /* same shape as list above */ ],
  "total": 3,
  "filtered": 3
}

---

Get episode by ID

GET /api/episodes/:id — Auth required

Response — 200 — single episode object (same shape as list item)

---

Get workflow roles

GET /api/episodes/roles — Auth required

Returns the list of roles available for episode workflow assignments.

Response — 200

[
  { "id": "role-uuid-1", "name": "Script Writer", "nameI18n": { "uk": "Сценарист", "en": "Script Writer", "es": "Guionista" } },
  { "id": "role-uuid-2", "name": "Editor", "nameI18n": { "uk": "Редактор", "en": "Editor", "es": "Editor" } }
]

---

Get assignment template

GET /api/episodes/assignment-template — Auth required

Returns the current global assignment template used when creating new episodes.

Response — 200

{
  "stages": [
    { "order": 1, "roleId": "role-uuid-1", "roleName": "Script Writer" },
    { "order": 2, "roleId": "role-uuid-2", "roleName": "Editor" }
  ]
}

---

Save assignment template

PUT /api/episodes/assignment-template — Auth required, Permission: template:edit

Request body

{
  "stages": [
    { "order": 1, "roleId": "role-uuid-1" },
    { "order": 2, "roleId": "role-uuid-2" }
  ]
}

Response — 200 — updated template object

---

Create episode

POST /api/episodes — Auth required, Permission: episode:create

Request body

{
  "projectId": "proj-uuid-001",
  "title": "Episode 1 — The Beginning",
  "description": "Pilot episode",
  "icon": null,
  "targetDuration": 300,
  "templateId": "template-uuid"
}

Field	Required	Notes
projectId	yes	UUID of the parent project
title	yes	Auto-translated to all locales
description	no	Auto-translated if provided
icon	no
targetDuration	no	Duration in seconds; defaults to 300
templateId	no	If provided, template scenes/blocks are applied after creation

Response — 201 — created episode object

---

Update episode

PUT /api/episodes/:id or PATCH /api/episodes/:id — Auth required, Permission: episode:edit

Request body (all fields optional)

{
  "episodeNumber": 2,
  "title": "Episode 2",
  "description": "Second episode",
  "icon": "🎥",
  "targetDuration": 420,
  "status": "active",
  "isLocked": false,
  "changedBy": "editor@example.com"
}

status values: draft | active | completed | paused

Response — 200 — updated episode object

---

Delete episode

DELETE /api/episodes/:id — Auth required, Permission: episode:delete

Response — 204

---

Upload episode preview video

POST /api/episodes/preview/upload — Auth required, multipart/form-data, Permission: episode:preview:upload

Form fields:

Field	Type	Required
file	video file	yes
projectId	string (UUID)	yes
episodeId	string (UUID)	yes

Response — 201

{ "url": "/api/episodes/preview/file/proj-uuid/ep-uuid/preview/preview.mp4", "filename": "preview.mp4" }

---

Get episode preview file

GET /api/episodes/preview/file/:projectId/:episodeId/preview/:filename — Auth required

Returns the preview video binary stream.

---

Delete episode preview

DELETE /api/episodes/preview/:projectId/:episodeId — Auth required, Permission: episode:preview:delete

Response — 204

---

Prepare episode import

POST /api/episodes/import/prepare — Auth required, Permission: episode:import

Reserves a job ID for tracking progress via SSE.

Response — 200

{ "jobId": "job-abc123" }

---

Import episode from video

POST /api/episodes/import — Auth required, multipart/form-data, Permission: episode:import

Transcribes the uploaded video with ElevenLabs, then uses the LLM to generate scenes and blocks. Response is streamed via SSE.

Form fields:

Field	Type	Required
file	video file	yes
projectId	string (UUID)	yes
userPrompt	string	no
jobId	string	no — use one from /import/prepare

Response — SSE stream of progress events

{ "progress": 50, "stage": "transcribing", "jobId": "job-abc123" }
{ "progress": 100, "stage": "finalizing", "done": true, "episodeId": "ep-uuid" }

---

Get import job progress

GET /api/episodes/import/:jobId/progress — Auth required

Reconnects to a running SSE stream for the given job.

Response — SSE stream (same event shape as /import)