Projects

A project is the top-level container. Episodes, characters, locations, and world rules all belong to a project.

Endpoints overview

Method	Endpoint	Permission	Description
GET	/api/projects	authenticated	List all projects
GET	/api/projects/with-episodes	authenticated	List projects with episodes
GET	/api/projects/:id	authenticated	Get project by ID
POST	/api/projects	project:create	Create a project
PUT / PATCH	/api/projects/:id	project:edit	Update a project
DELETE	/api/projects/:id	project:delete	Delete a project

Endpoints

List projects

GET /api/projects — Auth required

Supports optional filters via query params. When no params are supplied all projects are returned.

Query params (all optional)

Param	Type	Description
search	string	Full-text search on title
status	string	draft | active | completed | paused
categoryId	string	Age-range like 4-6, or all
sortBy	string	title | createdAt | updatedAt
sortOrder	string	asc | desc
limit	number	Page size
offset	number	Page offset

Response — 200

{
  "projects": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "code": "myproject",
      "title": "My Project",
      "description": "A great animated series",
      "titleI18n": { "uk": "Мій проект", "en": "My Project", "es": "Mi proyecto" },
      "descriptionI18n": { "uk": "Великий серіал", "en": "A great animated series", "es": "Una gran serie" },
      "icon": "🎬",
      "targetEpisodeCount": 10,
      "status": "active",
      "categoryId": "4-6",
      "category": { "id": "4-6", "name": "4–6 years", "icon": null },
      "progress": 40,
      "safety": 95,
      "createdAt": "2025-01-10T09:00:00.000Z",
      "updatedAt": "2025-03-15T12:00:00.000Z",
      "episodeCount": 4
    }
  ],
  "total": 1,
  "filtered": 1
}

---

List projects with episodes

GET /api/projects/with-episodes — Auth required

Returns each project with its nested episodes array — useful for the sidebar/dashboard.

Response — 200

{
  "projects": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "code": "myproject",
      "title": "My Project",
      "description": null,
      "titleI18n": { "uk": "Мій проект", "en": "My Project", "es": "Mi proyecto" },
      "descriptionI18n": { "uk": "", "en": "", "es": "" },
      "icon": "🎬",
      "targetEpisodeCount": 10,
      "status": "active",
      "categoryId": "4-6",
      "category": { "id": "4-6", "name": "4–6 years", "icon": null },
      "progress": 20,
      "safety": null,
      "createdAt": "2025-01-10T09:00:00.000Z",
      "updatedAt": "2025-03-15T12:00:00.000Z",
      "episodeCount": 2,
      "episodes": [
        {
          "id": "ep-uuid-001",
          "code": "ep01",
          "projectId": "a1b2c3d4-0000-0000-0000-000000000001",
          "episodeNumber": 1,
          "title": "Episode 1",
          "description": null,
          "titleI18n": { "uk": "Епізод 1", "en": "Episode 1", "es": "Episodio 1" },
          "descriptionI18n": { "uk": "", "en": "", "es": "" },
          "icon": null,
          "previewUrl": null,
          "targetDuration": 300,
          "status": "draft",
          "safety": null,
          "isLocked": false,
          "tasks": [],
          "createdAt": "2025-01-11T09:00:00.000Z",
          "updatedAt": "2025-01-11T09:00:00.000Z",
          "approved": false,
          "templateId": null
        }
      ]
    }
  ],
  "total": 1
}

---

Get project by ID

GET /api/projects/:id — Auth required

Response — 200 — single project object (same shape as a list item, without episodes)

---

Create project

POST /api/projects — Auth required, Permission: project:create

Request body

{
  "title": "My Project",
  "code": "myproject",
  "description": "A great animated series",
  "icon": "🎬",
  "targetEpisodeCount": 10,
  "categoryId": "4-6"
}

Field	Required	Notes
title	yes	Display title; auto-translated to all locales
code	yes	URL-safe slug — only a-z, 0-9, _ allowed
description	no	Auto-translated if provided
icon	no	Emoji or image URL
targetEpisodeCount	no	Defaults to 10
categoryId	no	Age-range string like "4-6". Defaults to "4-6"

Response — 201 — created project object

---

Update project

PUT /api/projects/:id or PATCH /api/projects/:id — Auth required, Permission: project:edit

Request body (all fields optional)

{
  "title": "Updated Title",
  "description": "New description",
  "icon": "🎥",
  "targetEpisodeCount": 12,
  "status": "active",
  "categoryId": "7-9"
}

status values: draft | active | completed | paused

Response — 200 — updated project object

---

Delete project

DELETE /api/projects/:id — Auth required, Permission: project:delete

Response — 204