Comments & Playlists API Endpoints

Comment Endpoints

Create Task Comment

POST /api/actions/tasks//comment

Create a new comment for a task with status change. Path Parameters:

task_id (string, uuid, required): Task unique identifier

Request Body:

{
  "task_status_id": "status-uuid",  // Required
  "comment": "Comment text with @mentions and #hashtags",
  "person_id": "user-uuid",  // Optional, manager only
  "created_at": "2023-01-01T12:00:00Z",  // Optional, manager only
  "checklist": {"item1": "Check lighting"},
  "links": ["https://example.com/reference"]
}

File Upload: Supports multipart/form-data for attachment uploads. Response: 201 Created

{
  "id": "comment-uuid",
  "task_id": "task-uuid",
  "person_id": "user-uuid",
  "task_status_id": "status-uuid",
  "comment": "Comment text",
  "created_at": "2023-01-01T12:00:00Z"
}

Source: /app/blueprints/comments/resources.py:148

Create Multiple Comments

POST /api/actions/projects//comments

Create several comments at once for a project. Path Parameters:

project_id (string, uuid, required): Project unique identifier

Request Body:

[
  {
    "task_status_id": "status-uuid",
    "object_id": "task-uuid",  // Required
    "comment": "Comment text",
    "person_id": "user-uuid",
    "created_at": "2023-01-01T12:00:00Z",
    "checklist": {},
    "links": []
  }
]

Response: 201 Created Array of created comments. Source: /app/blueprints/comments/resources.py:452

Acknowledge Comment

POST /api/actions/tasks//comments//ack

Acknowledge a comment. If already acknowledged, removes acknowledgement. Path Parameters:

task_id (string, uuid, required): Task unique identifier
comment_id (string, uuid, required): Comment unique identifier

Response: 200 OK

{
  "id": "comment-uuid",
  "acknowledged": true
}

Source: /app/blueprints/comments/resources.py:100

Reply to Comment

POST /api/actions/tasks//comments//reply

Add a reply to a comment. Path Parameters:

task_id (string, uuid, required): Task unique identifier
comment_id (string, uuid, required): Comment unique identifier

Form Data:

text (string): Reply text content
files (file[]): Optional attachment files

Response: 200 OK

{
  "id": "reply-uuid",
  "comment_id": "comment-uuid",
  "text": "Reply text",
  "person_id": "user-uuid",
  "created_at": "2023-01-01T12:00:00Z"
}

Source: /app/blueprints/comments/resources.py:612

Delete Comment Reply

DELETE /api/actions/tasks//comments//replies/

Delete a specific reply from a comment. Path Parameters:

task_id (string, uuid, required): Task unique identifier
comment_id (string, uuid, required): Comment unique identifier
reply_id (string, uuid, required): Reply unique identifier

Response: 200 OK Permissions: Reply author or administrators only. Source: /app/blueprints/comments/resources.py:699

Attachment Endpoints

Add Attachments to Comment

POST /api/actions/tasks//comments//add-attachment

Add one or more files as attachments to a comment. Path Parameters:

task_id (string, uuid, required): Task unique identifier
comment_id (string, uuid, required): Comment unique identifier

Form Data:

files (file[], required): Files to attach
reply_id (string, uuid, optional): Link attachments to specific reply

Content Types:

multipart/form-data
image/png, image/gif, image/jpeg

Response: 201 Created

[
  {
    "id": "attachment-uuid",
    "name": "document.pdf",
    "mimetype": "application/pdf",
    "size": 1024000,
    "extension": "pdf",
    "comment_id": "comment-uuid"
  }
]

Source: /app/blueprints/comments/resources.py:365

Download Attachment

GET /api/data/attachment-files//

Download a specific attachment file. Path Parameters:

attachment_file_id (string, uuid, required): Attachment unique identifier
file_name (string, required): File name to download

Response: 200 OK Binary file content with appropriate MIME type. Source: /app/blueprints/comments/resources.py:22

Delete Attachment

DELETE /api/actions/tasks//comments//attachments/

Delete a specific attachment file. Path Parameters:

task_id (string, uuid, required): Task unique identifier
comment_id (string, uuid, required): Comment unique identifier
attachment_id (string, uuid, required): Attachment unique identifier

Response: 204 No Content Permissions: Comment author or project managers only. Source: /app/blueprints/comments/resources.py:319

Get Project Attachment Files

GET /api/data/projects//attachment-files

Retrieve all attachment files for a project. Path Parameters:

project_id (string, uuid, required): Project unique identifier

Response: 200 OK Array of attachment file objects. Permissions: Administrator only. Source: /app/blueprints/comments/resources.py:743

Get Task Attachment Files

GET /api/data/tasks//attachment-files

Retrieve all attachment files for a task. Path Parameters:

task_id (string, uuid, required): Task unique identifier

Response: 200 OK Array of attachment file objects. Permissions: Administrator only. Source: /app/blueprints/comments/resources.py:806

Playlist Endpoints

Get Project Playlists

GET /api/data/projects//playlists

Retrieve all playlists for a project with pagination. Path Parameters:

project_id (string, uuid, required): Project unique identifier

Query Parameters:

page (integer): Page number (default: 1)
sort_by (string): Field to sort by (default: “updated_at”)
task_type_id (string, uuid): Filter by task type

Response: 200 OK

[
  {
    "id": "playlist-uuid",
    "name": "Review Playlist",
    "project_id": "project-uuid",
    "first_preview_file_id": "preview-uuid",
    "updated_at": "2023-01-01T12:00:00Z"
  }
]

Source: /app/blueprints/playlists/resources.py:25

Get Episode Playlists

GET /api/data/projects//episodes//playlists

Retrieve all playlists for an episode. Path Parameters:

project_id (string, uuid, required): Project unique identifier
episode_id (string, required): Episode UUID, “main”, or “all”

Query Parameters:

page (integer): Page number
sort_by (string): Sort field
task_type_id (string, uuid): Filter by task type

Special Episode Values:

main: Main pack (no episode)
all: All assets pack

Response: 200 OK Array of playlist objects. Source: /app/blueprints/playlists/resources.py:106

Get Playlist

GET /api/data/projects//playlists/

Retrieve a specific playlist with preview file revisions. Path Parameters:

project_id (string, uuid, required): Project unique identifier
playlist_id (string, uuid, required): Playlist unique identifier

Response: 200 OK

{
  "id": "playlist-uuid",
  "name": "Review Playlist",
  "project_id": "project-uuid",
  "shots": [
    {
      "id": "shot-uuid",
      "preview_file_id": "preview-uuid",
      "preview_file_extension": "mp4",
      "preview_file_revision": 3,
      "preview_files": {
        "task-type-uuid": [
          {"id": "preview-uuid", "revision": 3}
        ]
      }
    }
  ],
  "build_jobs": []
}

Source: /app/blueprints/playlists/resources.py:177

Get Entity Previews

GET /api/data/entities//preview-files

Retrieve all preview files for an entity, grouped by task type. Path Parameters:

entity_id (string, uuid, required): Entity unique identifier

Response: 200 OK

{
  "animation-task-type-uuid": [
    {
      "id": "preview-uuid",
      "revision": 3,
      "extension": "mp4",
      "width": 1920,
      "height": 1080,
      "duration": 5.5,
      "previews": []  // Sub-previews with same revision
    }
  ]
}

Source: /app/blueprints/playlists/resources.py:241

Add Entity to Playlist

POST /api/data/playlists//add-entity

Atomically add an entity to a playlist. Path Parameters:

playlist_id (string, uuid, required): Playlist unique identifier

Request Body:

{
  "entity_id": "entity-uuid",  // Required
  "preview_file_id": "preview-uuid"  // Optional
}

Response: 200 OK Updated playlist object. Permissions: Manager project access required. Source: /app/blueprints/playlists/resources.py:289

Build Job Endpoints

Build Playlist Movie

GET /api/data/playlists//build/mp4

Start a build job to compile playlist into MP4 movie. Path Parameters:

playlist_id (string, uuid, required): Playlist unique identifier

Query Parameters:

full (boolean): Build full quality movie (default: false)

Response: 200 OK

{
  "id": "job-uuid",
  "status": "running",
  "created_at": "2023-01-01T12:00:00Z"
}

Permissions: Manager project access required. Source: /app/blueprints/playlists/resources.py:446

Download Playlist Build

GET /api/data/playlists//jobs//build/mp4

Download completed playlist build as MP4. Path Parameters:

playlist_id (string, uuid, required): Playlist unique identifier
build_job_id (string, uuid, required): Build job unique identifier

Response: 200 OK Binary MP4 file. Error Response: 400 Bad Request

{
  "error": true,
  "message": "Build is not finished"
}

Permissions: Supervisor project access required. Source: /app/blueprints/playlists/resources.py:349

Download Playlist ZIP

GET /api/data/playlists//download/zip

Download playlist as ZIP archive containing all preview files. Path Parameters:

playlist_id (string, uuid, required): Playlist unique identifier

Response: 200 OK Binary ZIP file. Permissions: Supervisor project access required. Source: /app/blueprints/playlists/resources.py:540

Get Build Job

GET /api/data/playlists//jobs/

Retrieve build job status and details. Path Parameters:

playlist_id (string, uuid, required): Playlist unique identifier
build_job_id (string, uuid, required): Build job unique identifier

Response: 200 OK

{
  "id": "job-uuid",
  "status": "succeeded",  // "running", "succeeded", "failed"
  "created_at": "2023-01-01T12:00:00Z"
}

Source: /app/blueprints/playlists/resources.py:602

Delete Build Job

DELETE /api/data/playlists//jobs/

Remove a build job and its associated files. Path Parameters:

playlist_id (string, uuid, required): Playlist unique identifier
build_job_id (string, uuid, required): Build job unique identifier

Response: 204 No Content Source: /app/blueprints/playlists/resources.py:657

Get Project Build Jobs

GET /api/data/projects//build-jobs

Retrieve all build jobs for a project. Path Parameters:

project_id (string, uuid, required): Project unique identifier

Response: 200 OK Array of build job objects. Permissions: Administrator only. Source: /app/blueprints/playlists/resources.py:693

Get All Project Playlists (Admin)

GET /api/data/projects//all-playlists

Retrieve all playlists for a project (for synchronization). Path Parameters:

project_id (string, uuid, required): Project unique identifier

Query Parameters:

page (integer): Page number

Response: 200 OK Array of all playlist objects. Permissions: Administrator only. Source: /app/blueprints/playlists/resources.py:743

Temporary Playlist Endpoints

Generate Temp Playlist

POST /api/data/projects//temp-playlists

Generate a temporary playlist from task IDs without persisting. Path Parameters:

project_id (string, uuid, required): Project unique identifier

Query Parameters:

sort (boolean): Whether to sort playlist (default: false)

Request Body:

{
  "task_ids": [
    "task-uuid-1",
    "task-uuid-2"
  ]
}

Response: 200 OK Array of playlisted entities with preview files. Source: /app/blueprints/playlists/resources.py:794

Notification Endpoints

Notify Clients

POST /api/data/playlists//notify-clients

Notify clients that a playlist is ready for review. Path Parameters:

playlist_id (string, uuid, required): Playlist unique identifier

Request Body:

{
  "studio_id": "studio-uuid",  // Optional
  "department_id": "dept-uuid"  // Optional
}

Response: 200 OK

{
  "status": "success"
}

Permissions: Manager project access required. Source: /app/blueprints/playlists/resources.py:867

Error Responses

All endpoints may return standard error responses: 401 Unauthorized:

{
  "message": "JWT token required"
}

403 Forbidden:

{
  "message": "Permission denied"
}

404 Not Found:

{
  "message": "Resource not found"
}

400 Bad Request:

{
  "message": "Validation error message"
}

Rate Limiting

API rate limiting applies to all endpoints. Check response headers:

X-RateLimit-Limit: Requests per window
X-RateLimit-Remaining: Remaining requests
X-RateLimit-Reset: Reset timestamp

Authentication

All endpoints require JWT authentication via the Authorization header:

Authorization: Bearer <jwt_token>

Obtain tokens via the authentication endpoints.

Authentication

Projects

Assets

Shots & Sequences

Tasks

Files & Previews

People & Teams

Comments & Playlists

Events & Notifications

Documentation Index

​Comment Endpoints

​Create Task Comment

​Create Multiple Comments

​Acknowledge Comment

​Reply to Comment

​Delete Comment Reply

​Attachment Endpoints

​Add Attachments to Comment

​Download Attachment

​Delete Attachment

​Get Project Attachment Files

​Get Task Attachment Files

​Playlist Endpoints

​Get Project Playlists

​Get Episode Playlists

​Get Playlist

​Get Entity Previews

​Add Entity to Playlist

​Build Job Endpoints

​Build Playlist Movie

​Download Playlist Build

​Download Playlist ZIP

​Get Build Job

​Delete Build Job

​Get Project Build Jobs

​Get All Project Playlists (Admin)

​Temporary Playlist Endpoints

​Generate Temp Playlist

​Notification Endpoints

​Notify Clients

​Error Responses

​Rate Limiting

​Authentication

Build docs developers (and LLMs) love

Comment Endpoints

Create Task Comment

Create Multiple Comments

Acknowledge Comment

Reply to Comment

Delete Comment Reply

Attachment Endpoints

Add Attachments to Comment

Download Attachment

Delete Attachment

Get Project Attachment Files

Get Task Attachment Files

Playlist Endpoints

Get Project Playlists

Get Episode Playlists

Get Playlist

Get Entity Previews

Add Entity to Playlist

Build Job Endpoints

Build Playlist Movie

Download Playlist Build

Download Playlist ZIP

Get Build Job

Delete Build Job

Get Project Build Jobs

Get All Project Playlists (Admin)

Temporary Playlist Endpoints

Generate Temp Playlist

Notification Endpoints

Notify Clients

Error Responses

Rate Limiting

Authentication