Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cgwire/zou/llms.txt

Use this file to discover all available pages before exploring further.

​
Working Files

​
File Management

MethodEndpointDescription
GET/api/data/files/{file_id}Get working or output file info
GET/api/data/working-files/{working_file_id}/fileDownload working file
POST/api/data/working-files/{working_file_id}/fileUpload working file content

​
Task Working Files

MethodEndpointDescription
GET/api/data/tasks/{task_id}/working-filesList all working file revisions
POST/api/data/tasks/{task_id}/working-files/newCreate new working file revision
GET/api/data/tasks/{task_id}/working-files/last-revisionsGet latest revision per file name
POST/api/data/tasks/{task_id}/working-file-pathGenerate working file path

​
Entity Working Files

MethodEndpointDescription
GET/api/data/entities/{entity_id}/working-filesGet working files for entity

​
Working File Actions

MethodEndpointDescription
PUT/api/actions/working-files/{working_file_id}/commentUpdate working file comment
PUT/api/actions/working-files/{working_file_id}/modifiedUpdate modification timestamp

​
Output Files

​
Entity Output Files

MethodEndpointDescription
POST/api/data/entities/{entity_id}/output-files/newCreate new entity output file
POST/api/data/entities/{entity_id}/output-files/next-revisionGet next revision number
GET/api/data/entities/{entity_id}/output-files/last-revisionsGet latest output file revisions
GET/api/data/entities/{entity_id}/output-filesGet all output files for entity
POST/api/data/entities/{entity_id}/output-file-pathGenerate output file path

​
Entity Output Types

MethodEndpointDescription
GET/api/data/entities/{entity_id}/output-typesGet output types for entity
GET/api/data/entities/{entity_id}/output-types/{output_type_id}/output-filesGet output files by type

​
Instance Output Files

MethodEndpointDescription
POST/api/data/asset-instances/{asset_instance_id}/entities/{temporal_entity_id}/output-files/newCreate instance output file
POST/api/data/asset-instances/{asset_instance_id}/entities/{temporal_entity_id}/output-files/next-revisionGet next revision
GET/api/data/asset-instances/{asset_instance_id}/entities/{temporal_entity_id}/output-files/last-revisionsGet latest revisions
GET/api/data/asset-instances/{asset_instance_id}/output-filesGet all instance output files
POST/api/data/asset-instances/{asset_instance_id}/entities/{temporal_entity_id}/output-file-pathGenerate output file path

​
Instance Output Types

MethodEndpointDescription
GET/api/data/asset-instances/{asset_instance_id}/entities/{temporal_entity_id}/output-typesGet instance output types
GET/api/data/asset-instances/{asset_instance_id}/entities/{temporal_entity_id}/output-types/{output_type_id}/output-filesGet files by type

​
Project Output Files

MethodEndpointDescription
GET/api/data/projects/{project_id}/output-filesGet all project output files

​
Preview Files

​
Preview Upload

MethodEndpointDescription
POST/pictures/preview-files/{preview_file_id}Upload preview file
POST/api/actions/tasks/{task_id}/batch-commentCreate comments with preview files
POST/api/actions/tasks/batch-commentCreate comments for multiple tasks

​
Preview Download

MethodEndpointDescription
GET/movies/originals/preview-files/{preview_file_id}.mp4Download preview movie
GET/movies/originals/preview-files/{preview_file_id}/downloadDownload movie as attachment
GET/movies/low/preview-files/{preview_file_id}.mp4Download low-def movie
GET/pictures/originals/preview-files/{preview_file_id}.{extension}Download preview file
GET/pictures/originals/preview-files/{preview_file_id}/downloadDownload as attachment

​
Thumbnails

MethodEndpointDescription
GET/pictures/thumbnails/preview-files/{preview_file_id}.pngGet rectangle thumbnail
GET/pictures/thumbnails-square/preview-files/{preview_file_id}.pngGet square thumbnail
GET/pictures/originals/preview-files/{preview_file_id}.pngGet original resolution
GET/pictures/previews/preview-files/{preview_file_id}.pngGet preview size image
GET/movies/tiles/preview-files/{preview_file_id}.pngGet tile sprite for scrubbing

​
Preview Actions

MethodEndpointDescription
PUT/api/actions/preview-files/{preview_file_id}/set-main-previewSet as entity main preview
PUT/api/actions/preview-files/{preview_file_id}/update-positionChange preview order
PUT/api/actions/preview-files/{preview_file_id}/update-annotationsUpdate annotations
GET/api/actions/preview-files/{preview_file_id}/extract-frameExtract frame from movie
GET/api/actions/preview-files/{preview_file_id}/extract-tileExtract tile sprite

​
Preview Management

MethodEndpointDescription
GET/api/data/playlists/preview-files/runningGet processing/broken previews

​
Preview Background Files

MethodEndpointDescription
POST/pictures/preview-background-files/{preview_background_file_id}Upload HDR background
GET/pictures/preview-background-files/{preview_background_file_id}.{extension}Download background file
GET/pictures/thumbnails/preview-background-files/{preview_background_file_id}.pngGet background thumbnail

​
Attachment Files

MethodEndpointDescription
GET/pictures/thumbnails/attachment-files/{attachment_file_id}.pngGet attachment thumbnail

​
Thumbnails (Other)

​
Organisation Thumbnails

MethodEndpointDescription
POST/pictures/thumbnails/organisations/{organisation_id}Upload organisation thumbnail
GET/pictures/thumbnails/organisations/{organisation_id}.pngGet organisation thumbnail

​
Project Thumbnails

MethodEndpointDescription
POST/pictures/thumbnails/projects/{project_id}Upload project thumbnail
GET/pictures/thumbnails/projects/{project_id}.pngGet project thumbnail

​
Person Thumbnails

MethodEndpointDescription
POST/pictures/thumbnails/persons/{person_id}Upload person avatar
GET/pictures/thumbnails/persons/{person_id}.pngGet person avatar

​
File Tree

MethodEndpointDescription
POST/api/actions/projects/{project_id}/set-file-treeSet file tree template

​
Utility

MethodEndpointDescription
POST/api/data/entities/guess_from_pathGuess entity from file path

​
Query Parameters

​
Working Files

GET /api/data/entities//working-files
  • task_id (optional): Filter by task
  • name (optional): Filter by file name

​
Output Files

GET /api/data/entities//output-files GET /api/data/entities//output-files/last-revisions GET /api/data/projects//output-files
  • output_type_id (optional): Filter by output type
  • task_type_id (optional): Filter by task type
  • representation (optional): Filter by representation
  • file_status_id (optional): Filter by file status
  • name (optional): Filter by file name
GET /api/data/asset-instances//output-files
  • temporal_entity_id (optional): Filter by temporal entity
  • Plus all filters from above
GET /api/data/entities//output-types//output-files
  • representation (optional): Filter by representation

​
Preview Files

POST /pictures/preview-files/
  • normalize (optional): Enable video normalization (default: true)
GET /api/actions/preview-files//extract-frame
  • frame_number (optional): Frame to extract (default: 0)
PUT /api/actions/preview-files//set-main-preview
  • frame_number (optional): Extract specific frame for entity preview
GET /api/data/playlists/preview-files/running
  • cursor_preview_file_id (optional): Pagination cursor
  • limit (optional): Max results

​
Response Codes

​
Success Codes

  • 200 OK: Request successful
  • 201 Created: Resource created successfully

​
Error Codes

  • 400 Bad Request: Invalid parameters or malformed request
  • 404 Not Found: Resource not found
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions

​
Common Filters

Many endpoints support filtering by:
  • output_type_id: Cache, Render, Texture, etc.
  • task_type_id: Modeling, Animation, Lighting, etc.
  • file_status_id: Approved, Pending, Rejected, etc.
  • representation: mp4, abc, fbx, exr, etc.
  • name: File name (main, cache, proxy, etc.)

​
File Storage

File storage is handled through configurable backends:
  • Local: Files stored on server filesystem
  • S3: Amazon S3 or compatible object storage
  • Swift: OpenStack Swift object storage
Configuration: zou/app/config.py - FS_BACKEND setting Source: zou/app/stores/file_store.py

​
Authentication

All endpoints require JWT authentication: 
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://kitsu.example.com/api/data/files/{file_id}
See Authentication for details.

​
Rate Limiting

File upload endpoints may have size and rate limits:
  • Check config.MAX_UPLOAD_SIZE for upload limits
  • Video normalization may timeout based on JOB_QUEUE_TIMEOUT
  • Large file uploads may require chunking

​
Permissions

​
Working Files

  • Create: Requires task access
  • Read: Requires project access
  • Update: Requires task action access

​
Output Files

  • Create: Requires project access
  • Read: Requires project access
  • Update: Requires manager access

​
Preview Files

  • Upload: Requires task action access
  • Download: Requires task access (or entity is shared)
  • Annotate: Requires manager, client, or supervisor access
  • Set Main: Requires project access

Build docs developers (and LLMs) love

Get started for freeTalk to us