Templates

Scene templates are pre-built scene and block structures that can be applied to new episodes to speed up episode creation. They are separate from the assignment template (which deals with creator roles and workflow stages).

Endpoints overview

Method	Endpoint	Permission	Description
GET	/api/templates	authenticated	List active templates
GET	/api/templates/all	authenticated	List all templates
GET	/api/templates/:id	authenticated	Get template by ID
POST	/api/templates	template:create	Create a template
PUT	/api/templates/:id	template:edit	Update a template
DELETE	/api/templates/:id	template:delete	Delete a template
POST	/api/templates/:id/scenes	template:edit	Add scene to template
PUT	/api/templates/:id/scenes/:sceneId	template:edit	Update template scene
DELETE	/api/templates/:id/scenes/:sceneId	template:edit	Delete template scene
POST	/api/templates/:id/scenes/:sceneId/blocks	template:edit	Add block to template scene
PUT	/api/templates/:id/scenes/:sceneId/blocks/:blockId	template:edit	Update template block
DELETE	/api/templates/:id/scenes/:sceneId/blocks/:blockId	template:edit	Delete template block

Template Endpoints

List active templates

GET /api/templates — Auth required

Returns only templates with isActive: true — used to populate the episode creation picker.

Response — 200

[
  {
    "id": "tpl-uuid-001",
    "name": "Standard 3-Act Episode",
    "nameI18n": { "uk": "Стандартний 3-актний епізод", "en": "Standard 3-Act Episode", "es": "Episodio estándar de 3 actos" },
    "description": "Setup, confrontation, and resolution scenes.",
    "descriptionI18n": { "uk": "Вступ, конфлікт та розв'язка.", "en": "Setup, confrontation, and resolution scenes.", "es": "Configuración, confrontación y resolución." },
    "category": "Drama",
    "categoryI18n": { "uk": "Драма", "en": "Drama", "es": "Drama" },
    "icon": "🎭",
    "isActive": true,
    "createdAt": "2025-01-05T09:00:00.000Z",
    "scenes": [
      {
        "id": "ts-uuid-001",
        "templateId": "tpl-uuid-001",
        "title": "Setup",
        "titleI18n": { "uk": "Вступ", "en": "Setup", "es": "Configuración" },
        "mood": "neutral",
        "index": 0,
        "blocks": [
          {
            "id": "tb-uuid-001",
            "templateSceneId": "ts-uuid-001",
            "type": "action",
            "placeholderTextI18n": { "uk": "Опишіть вступну дію", "en": "Describe the opening action", "es": "Describe la acción inicial" },
            "hintI18n": { "uk": "Де відбувається дія?", "en": "Where does the action take place?", "es": "¿Dónde ocurre la acción?" },
            "index": 0
          }
        ]
      }
    ]
  }
]

---

List all templates

GET /api/templates/all — Auth required

Returns all templates including archived ones (isActive: false).

Response — 200 — same array shape as active list

---

Get template by ID

GET /api/templates/:id — Auth required

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

Returns 404 if not found.

---

Create template

POST /api/templates — Auth required, Permission: template:create

Request body

{
  "name": "Standard 3-Act Episode",
  "description": "Setup, confrontation, and resolution scenes.",
  "icon": "🎭",
  "category": "Drama",
  "isActive": true
}

Field	Required	Notes
name	yes	Auto-translated
description	no	Auto-translated if provided
icon	no	Defaults to 📄
category	no	Auto-translated if provided
isActive	no	Defaults to true

Response — 201 — created template object

---

Update template

PUT /api/templates/:id — Auth required, Permission: template:edit

Request body (all fields optional)

{
  "name": "Updated Template Name",
  "description": "Updated description.",
  "icon": "🎬",
  "category": "Comedy",
  "isActive": false
}

Response — 200 — updated template object

---

Delete template

DELETE /api/templates/:id — Auth required, Permission: template:delete

Response — 204

---

Template Scene Endpoints

Add scene to template

POST /api/templates/:id/scenes — Auth required, Permission: template:edit

Request body

{
  "title": "Setup",
  "mood": "neutral",
  "index": 0
}

Field	Required	Notes
title	yes	Auto-translated
mood	no	Defaults to ""
index	no	Display order; defaults to 0

Response — 201

{
  "id": "ts-uuid-002",
  "templateId": "tpl-uuid-001",
  "title": "Setup",
  "titleI18n": { "uk": "Вступ", "en": "Setup", "es": "Configuración" },
  "mood": "neutral",
  "index": 0,
  "blocks": []
}

---

Update template scene

PUT /api/templates/:id/scenes/:sceneId — Auth required, Permission: template:edit

Request body (all fields optional)

{
  "title": "Introduction",
  "mood": "cheerful",
  "index": 1
}

Response — 200 — updated template scene object

---

Delete template scene

DELETE /api/templates/:id/scenes/:sceneId — Auth required, Permission: template:edit

Response — 204

---

Template Block Endpoints

Add block to template scene

POST /api/templates/:id/scenes/:sceneId/blocks — Auth required, Permission: template:edit

Request body

{
  "type": "dialog",
  "placeholderText": "Opening line from protagonist",
  "hint": "Keep it short and punchy",
  "index": 0
}

Field	Required	Notes
type	no	dialog | action; defaults to "action"
placeholderText	yes	Auto-translated
hint	no	Auto-translated if provided
index	no	Display order; defaults to 0

Response — 201

{
  "id": "tb-uuid-002",
  "templateSceneId": "ts-uuid-002",
  "type": "dialog",
  "placeholderTextI18n": { "uk": "Перша репліка протагоніста", "en": "Opening line from protagonist", "es": "Línea inicial del protagonista" },
  "hintI18n": { "uk": "Коротко і чітко", "en": "Keep it short and punchy", "es": "Breve y contundente" },
  "index": 0
}

---

Update template block

PUT /api/templates/:id/scenes/:sceneId/blocks/:blockId — Auth required, Permission: template:edit

Request body (all fields optional)

{
  "type": "action",
  "placeholderText": "Describe what happens",
  "hint": null,
  "index": 1
}

Response — 200 — updated template block object

---

Delete template block

DELETE /api/templates/:id/scenes/:sceneId/blocks/:blockId — Auth required, Permission: template:edit

Response — 204