Feat: Watch Party

[arabcoders]

This pull request updates the API documentation (API.md) and some workflow naming in GitHub Actions to reflect recent API changes and improvements, particularly around upload token handling, public ID usage, and the addition of a new Watch Party feature. The changes clarify and expand API endpoint descriptions, update parameter requirements, and document new functionality for collaborative media viewing. Below are the most important changes grouped by theme:

API Documentation Improvements and New Features:

• Added documentation for Watch Party endpoints, including creation (POST /api/tokens/{download_token}/uploads/{upload_id}/watch), deletion (DELETE /api/watch/{room_id}), and WebSocket synchronization (WS /api/watch/{room_id}/ws). These endpoints enable temporary collaborative playback sessions for completed uploads, with detailed authentication, error handling, and protocol descriptions.
• Documented new subtitle endpoints for listing and retrieving external subtitle tracks associated with uploads.

Parameter and Response Changes:

• Changed all references to upload_id from integer to string, clarifying that upload IDs are now public, random 18-character strings, not sequential integers. This applies to all relevant endpoint descriptions and path parameter documentation. [1] [2] [3] [4] [5] [6] [7] [8]
• Updated the response structure for listing upload tokens: now returns an object with a tokens array and a total count, and changed the default limit from 100 to 10. [1] [2]

Authentication and Error Handling:

• Clarified authentication requirements for various endpoints, including making token info endpoints public, and expanded error responses for upload completion and Watch Party endpoints. [1] [2]
• Updated the max_uploads field to be optional (default 1) when creating a new token, and clarified error responses for upload completion. [1] [2]

Workflow and Miscellaneous Documentation Updates:

• Updated workflow job names in .github/workflows/build-pr.yml and .github/workflows/main.yml for clarity. [1] [2]
• Clarified the use of the default field in metadata schemas, TUS protocol features, and upload flow steps, including support for checksum verification and increased post-processing worker default. [1] [2] [3] [4] [5]