Comments

Comments can be attached to any entity (episode, scene, scene block, character, project) and support a resolved/unresolved workflow for review feedback.

Endpoints overview

Method	Endpoint	Permission	Description
GET	/api/comments/entity/:entityType/:entityId	authenticated	List comments for entity
GET	/api/comments/:id	authenticated	Get comment by ID
POST	/api/comments	comment:create	Create a comment
PUT	/api/comments/:id	authenticated	Update a comment
PATCH	/api/comments/:id/resolve	authenticated	Resolve a comment
PATCH	/api/comments/:id/unresolve	authenticated	Unresolve a comment
DELETE	/api/comments/:id	authenticated	Delete a comment

Endpoints

List comments for entity

GET /api/comments/entity/:entityType/:entityId — Auth required

entityType values: scene_block | scene | character | episode | project

Response — 200

[
  {
    "id": "cmt-uuid-001",
    "parentId": null,
    "entityType": "scene_block",
    "entityId": "block-uuid-001",
    "text": "The pacing here feels rushed — consider adding a pause beat.",
    "createdByEmail": "editor@example.com",
    "assignedToRole": "Script Writer",
    "resolved": false,
    "resolvedByEmail": null,
    "resolvedAt": null,
    "createdAt": "2025-03-10T14:00:00.000Z",
    "updatedAt": "2025-03-10T14:00:00.000Z",
    "replies": [
      {
        "id": "cmt-uuid-002",
        "parentId": "cmt-uuid-001",
        "entityType": "scene_block",
        "entityId": "block-uuid-001",
        "text": "Agreed — I'll add a 1-second pause.",
        "createdByEmail": "writer@example.com",
        "assignedToRole": null,
        "resolved": false,
        "resolvedByEmail": null,
        "resolvedAt": null,
        "createdAt": "2025-03-10T15:00:00.000Z",
        "updatedAt": "2025-03-10T15:00:00.000Z",
        "replies": []
      }
    ]
  }
]

---

Get comment by ID

GET /api/comments/:id — Auth required

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

---

Create comment

POST /api/comments — Auth required, Permission: comment:create

Request body

{
  "entityType": "scene_block",
  "entityId": "block-uuid-001",
  "text": "The pacing here feels rushed — consider adding a pause beat.",
  "createdByEmail": "editor@example.com",
  "parentId": null,
  "assignedToRole": "Script Writer"
}

Field	Required	Notes
entityType	yes	One of: scene_block, scene, character, episode, project
entityId	yes	UUID of the entity
text	yes	Max 1000 characters
createdByEmail	yes	Email of the commenter
parentId	no	UUID of parent comment for replies
assignedToRole	no	Role name to assign the comment to

Response — 201 — created comment object

---

Update comment

PUT /api/comments/:id — Auth required

Request body (all fields optional)

{
  "text": "Updated comment text.",
  "assignedToRole": "Editor",
  "resolved": false,
  "resolvedByEmail": null
}

Response — 200 — updated comment object

---

Resolve comment

PATCH /api/comments/:id/resolve — Auth required

Marks the comment as resolved. The calling user's email is recorded as resolvedByEmail. Users with the comment:resolve permission can resolve any comment; others can only resolve their own.

Response — 200 — updated comment object with resolved: true and resolvedAt set

---

Unresolve comment

PATCH /api/comments/:id/unresolve — Auth required

Marks the comment as unresolved. Same permission rules as resolve.

Response — 200 — updated comment object with resolved: false

---

Delete comment

DELETE /api/comments/:id — Auth required

Users with the comment:delete permission can delete any comment; others can only delete their own.

Response — 204