Tasks

User tasks track personal work items, optionally linked to one or more episodes. Tasks can be scoped to a specific user or to a role. Admins can view all tasks; regular users see only their own.

Endpoints overview

Method	Endpoint	Permission	Description
GET	/api/user-tasks	authenticated	Get tasks for a user
GET	/api/user-tasks/all	admin:dashboard	Get all tasks (Admin)
POST	/api/user-tasks	authenticated	Create a task
PATCH	/api/user-tasks/:id	authenticated	Update task (assign user)
PATCH	/api/user-tasks/:id/status	authenticated	Update task status
DELETE	/api/user-tasks/:id	authenticated	Delete a task
POST	/api/user-tasks/:id/episodes	authenticated	Link task to episode
DELETE	/api/user-tasks/:id/episodes/:episodeId	authenticated	Unlink task from episode

Endpoints

Get tasks for a user

GET /api/user-tasks — Auth required

Query params

Param	Type	Required	Description
userId	string (UUID)	yes	Return tasks for this user

Response — 200

[
  {
    "id": "task-uuid-001",
    "userId": "user-uuid-001",
    "roleId": "role-uuid-001",
    "title": "Review episode 3 script",
    "titleI18n": { "uk": "Перевірити сценарій 3 епізоду", "en": "Review episode 3 script", "es": "Revisar el guion del episodio 3" },
    "description": "Check continuity with episode 2",
    "descriptionI18n": { "uk": "Перевірити безперервність з епізодом 2", "en": "Check continuity with episode 2", "es": "Verificar continuidad con el episodio 2" },
    "url": "",
    "status": "to-do",
    "createdAt": "2025-03-01T10:00:00.000Z",
    "updatedAt": "2025-03-01T10:00:00.000Z",
    "userEmail": "writer@example.com",
    "roleName": "Script Writer"
  }
]

---

Get all tasks (Admin)

GET /api/user-tasks/all — Auth required, Permission: admin:dashboard

Returns every task across all users. Supports date filtering.

Query params (all optional)

Param	Type	Description
filter	string	today | monthly | range
month	number	Month index (0-based). Used with filter=monthly
year	number	Full year. Used with filter=monthly
dateFrom	string	ISO date string. Used with filter=range
dateTo	string	ISO date string. Used with filter=range

Response — 200 — array of task objects (same shape as above)

---

Create task

POST /api/user-tasks — Auth required

Request body

{
  "title": "Review episode 3 script",
  "roleId": "role-uuid-001",
  "userId": "user-uuid-001",
  "description": "Check continuity with episode 2",
  "url": "",
  "status": "to-do"
}

Field	Required	Notes
roleId	yes	UUID of the role this task belongs to
title	yes	Auto-translated
userId	no	UUID of the assigned user
description	no	Auto-translated if provided
url	no	External link
status	no	Defaults to "to-do"

Response — 201 — created task object

---

Update task (assign user)

PATCH /api/user-tasks/:id — Auth required

Updates the userId assignment on the task.

Request body

{ "userId": "user-uuid-002" }

Response — 200 — updated task object

---

Update task status

PATCH /api/user-tasks/:id/status — Auth required

Request body

{
  "status": "in-progress",
  "episodeId": "ep-uuid-001"
}

Field	Required	Notes
status	yes	to-do | in-progress | blocked | done
episodeId	no	If provided, the status change is recorded for this specific episode link

Response — 200 — updated task object

---

Delete task

DELETE /api/user-tasks/:id — Auth required

Response — 204

---

Link task to episode

POST /api/user-tasks/:id/episodes — Auth required

Request body

{
  "episodeId": "ep-uuid-001",
  "order": 1
}

Field	Required	Notes
episodeId	yes	UUID of the episode to link
order	no	Display order; defaults to 0

Response — 204

---

Unlink task from episode

DELETE /api/user-tasks/:id/episodes/:episodeId — Auth required

Response — 204