Playlists API — Create, Manage, and Organize Videos

Playlists belong to a user and hold an ordered list of video references. All endpoints require a valid JWT in the Authorization header. Only the playlist owner can modify, add videos to, remove videos from, or delete a playlist — operations on playlists owned by other users return an error. Duplicate video entries within a single playlist are prevented at the API level.

POST /api/v1/playlist

Creates a new playlist for the authenticated user. Playlist names must be unique per user — you cannot have two playlists with the same name in your account.

Body parameters

name

string

required

The name of the new playlist. Must be non-empty. Returns 400 if missing.

description

string

An optional description for the playlist.

Response

Returns 200 with the newly created playlist document.

_id

string

Unique identifier of the created playlist.

name

string

Name of the playlist.

description

string

Description of the playlist (may be absent if not provided).

videos

array

Empty array on creation — no videos are added at this stage.

owner

string

ObjectId of the authenticated user who owns the playlist.

createdAt

string

ISO 8601 creation timestamp.

updatedAt

string

ISO 8601 last-updated timestamp.

Errors

Status	Message
`409`	`"Playlist with the same name already exists in your account"` — the user already has a playlist with this exact name.
`400`	`"Playlist name is required"` — the `name` field was missing from the request body.

Example

curl -X POST "https://api.videohub.com/api/v1/playlist" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Favourite Tutorials", "description": "All the Node.js and React tutorials I keep coming back to."}'

GET /api/v1/playlist/:playlistId

Fetches the full details of a single playlist including the owner’s public profile, expanded video documents (each with their own owner details), and a computed totalVideos count.

Path parameters

playlistId

string

required

The MongoDB ObjectId of the playlist to retrieve. Returns 400 if missing or invalid; 404 if no playlist exists with that ID.

Response

Returns an array containing a single enriched playlist object (the aggregation pipeline result).

_id

string

Unique identifier of the playlist.

name

string

Name of the playlist.

description

string

Description of the playlist.

owner

string

ObjectId of the playlist owner.

ownerDetails

object

Resolved public profile of the playlist owner.

Show ownerDetails fields

username

string

Username of the playlist owner.

fullName

string

Full display name of the playlist owner.

avatar

string

URL of the playlist owner’s avatar.

videos

array

Array of expanded video documents in the playlist. Each entry includes the video’s own ownerDetails.

Show Video entry fields

_id

string

ObjectId of the video.

title

string

Title of the video.

thumbnail

string

Thumbnail URL.

duration

number

Duration in seconds.

views

number

Total view count.

ownerDetails

object

Public profile of the video’s uploader (username, fullName, avatar).

totalVideos

number

Total number of videos currently in the playlist. Computed dynamically via $size.

createdAt

string

ISO 8601 creation timestamp.

updatedAt

string

ISO 8601 last-updated timestamp.

Example

curl -X GET "https://api.videohub.com/api/v1/playlist/64f1a2b3c4d5e6f7a8b9c0d5" \
  -H "Authorization: Bearer <your_token>"

PATCH /api/v1/playlist/:playlistId

Updates the name and/or description of an existing playlist. At least one of the two fields must be included in the request body. Only the playlist owner can perform this operation. Ownership is enforced inside the findOneAndUpdate query — a non-owner update returns 404. The response contains only the fields that were actually updated, not the full playlist document.

Path parameters

playlistId

string

required

The MongoDB ObjectId of the playlist to update. Returns 400 if missing or invalid; 404 if not found or the authenticated user is not the owner.

Body parameters

name

string

New name for the playlist. Must be non-empty after trimming whitespace if provided.

description

string

New description for the playlist.

Response

Returns 200 with an object containing only the fields that were updated.

name

string

The updated playlist name. Present only if name was included in the request.

description

string

The updated playlist description. Present only if description was included in the request.

Errors

Status	Message
`400`	`"Please provide a name or description to update"` — neither `name` nor `description` was provided.
`400`	`"Playlist name cannot be empty"` — `name` was provided but was blank after trimming.
`404`	`"Playlist not found or you don't have permission to update it"` — playlist doesn’t exist or the requester is not the owner.

Example

curl -X PATCH "https://api.videohub.com/api/v1/playlist/64f1a2b3c4d5e6f7a8b9c0d5" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Must-Watch Tutorials", "description": "Curated list of the best programming tutorials."}'

DELETE /api/v1/playlist/:playlistId

Permanently deletes a playlist and its video reference list. The underlying video documents are not affected — only the playlist record is removed. Ownership is enforced atomically via findOneAndDelete({ _id: playlistId, owner: req.user._id }) — only the playlist owner can delete it.

Path parameters

playlistId

string

required

The MongoDB ObjectId of the playlist to delete. Returns 400 if missing or invalid; 404 if not found or the requester is not the owner.

Response

Returns 200 with the full deleted playlist document as it existed before deletion.

_id

string

ObjectId of the deleted playlist.

name

string

Name of the deleted playlist.

description

string

Description of the deleted playlist.

videos

array

Array of video ObjectIds that were in the playlist.

owner

string

ObjectId of the playlist owner.

createdAt

string

ISO 8601 creation timestamp.

updatedAt

string

ISO 8601 last-updated timestamp.

Errors

Status	Message
`404`	`"Playlist not found or you don't have permission to delete it"` — playlist doesn’t exist or the requester is not the owner.

Example

curl -X DELETE "https://api.videohub.com/api/v1/playlist/64f1a2b3c4d5e6f7a8b9c0d5" \
  -H "Authorization: Bearer <your_token>"

PATCH /api/v1/playlist/add/:videoId/:playlistId

Adds a video to a playlist. The endpoint first verifies ownership of the playlist, then checks whether the video is already present in the videos array. If the video is a duplicate a 400 error is returned immediately and no database write occurs. Otherwise the video ObjectId is appended using $push.

Path parameters

videoId

string

required

The MongoDB ObjectId of the video to add. Returns 400 if missing or invalid.

playlistId

string

required

The MongoDB ObjectId of the target playlist. Returns 400 if missing or invalid.

Response

Returns 200 with the updated playlist document after the video has been added.

_id

string

ObjectId of the playlist.

name

string

Name of the playlist.

description

string

Description of the playlist.

videos

array

Updated array of video ObjectIds now including the newly added video.

owner

string

ObjectId of the playlist owner.

createdAt

string

ISO 8601 creation timestamp.

updatedAt

string

ISO 8601 last-updated timestamp.

Errors

Status	Message
`400`	`"This video is already in the playlist"` — the video ObjectId already exists in the `videos` array.
`403`	`"You do not have permission to modify this playlist"` — authenticated user is not the playlist owner.
`400`	`"Playlist not found"` — no playlist exists with the given `playlistId`.

Example

curl -X PATCH "https://api.videohub.com/api/v1/playlist/add/64f1a2b3c4d5e6f7a8b9c0d1/64f1a2b3c4d5e6f7a8b9c0d5" \
  -H "Authorization: Bearer <your_token>"

Attempting to add the same video twice returns a 400 error. Check GET /api/v1/playlist/:playlistId to inspect the current videos array before adding if you are unsure whether the video is already present.

PATCH /api/v1/playlist/remove/:videoId/:playlistId

Removes a video from a playlist using MongoDB’s $pull operator. The endpoint first verifies ownership, then performs the update. If the video is not in the playlist the $pull is a no-op and the updated playlist is still returned successfully.

Path parameters

videoId

string

required

The MongoDB ObjectId of the video to remove. Returns 400 if missing or invalid.

playlistId

string

required

The MongoDB ObjectId of the playlist to remove the video from. Returns 400 if missing or invalid.

Response

Returns 200 with the updated playlist document after the video has been removed.

_id

string

ObjectId of the playlist.

name

string

Name of the playlist.

description

string

Description of the playlist.

videos

array

Updated array of video ObjectIds with the specified video removed.

owner

string

ObjectId of the playlist owner.

createdAt

string

ISO 8601 creation timestamp.

updatedAt

string

ISO 8601 last-updated timestamp.

Errors

Status	Message
`403`	`"You do not have permission to modify this playlist"` — authenticated user is not the playlist owner.
`400`	`"Playlist not found"` — no playlist exists with the given `playlistId`.

Example

curl -X PATCH "https://api.videohub.com/api/v1/playlist/remove/64f1a2b3c4d5e6f7a8b9c0d1/64f1a2b3c4d5e6f7a8b9c0d5" \
  -H "Authorization: Bearer <your_token>"

GET /api/v1/playlist/user/:userId

Returns all playlists owned by the specified user via a simple Playlist.find({ owner: userId }) — no aggregation is performed. This is useful for rendering a user’s playlist library on their profile page. Use GET /api/v1/playlist/:playlistId to fetch a specific playlist with full expanded video data.

Path parameters

userId

string

required

The MongoDB ObjectId of the user whose playlists you want to list. Returns 400 if missing or not a valid ObjectId.

Response

Returns an array of playlist documents. An empty array is returned if the user has no playlists.

[]._id

string

ObjectId of the playlist.

[].name

string

Name of the playlist.

[].description

string

Description of the playlist.

[].videos

array

Array of video ObjectIds in the playlist (not expanded).

[].owner

string

ObjectId of the playlist owner.

[].createdAt

string

ISO 8601 creation timestamp.

[].updatedAt

string

ISO 8601 last-updated timestamp.

Example

curl -X GET "https://api.videohub.com/api/v1/playlist/user/64f1a2b3c4d5e6f7a8b9c0e2" \
  -H "Authorization: Bearer <your_token>"

Playlist object schema

_id

ObjectId

MongoDB-generated unique identifier for the playlist.

name

string

Required. The display name of the playlist. Must be unique per owner. This is the only field with a required constraint in the schema.

description

string

Optional free-text description of the playlist.

videos

ObjectId[]

Ordered array of references to Video documents. Entries are appended with $push (add) and removed with $pull (remove). Duplicates are rejected at the application layer before any database write.

owner

ObjectId

Reference to the User document who owns this playlist. Always set by application logic when a playlist is created.

createdAt

Date

Automatically set by Mongoose timestamps on document creation.

updatedAt

Date

Automatically updated by Mongoose timestamps on every save.

When calling GET /api/v1/playlist/:playlistId, the response also includes the computed ownerDetails object, a totalVideos count, and fully expanded video objects each with their own ownerDetails. These fields are not stored in the database — they are resolved at query time via MongoDB aggregation.

Overview

Users

Videos

Social Features

Dashboard

Documentation Index

​POST /api/v1/playlist

​Body parameters

​Response

​Errors

​Example

​GET /api/v1/playlist/:playlistId

​Path parameters

​Response

​Example

​PATCH /api/v1/playlist/:playlistId

​Path parameters

​Body parameters

​Response

​Errors

​Example

​DELETE /api/v1/playlist/:playlistId

​Path parameters

​Response

​Errors

​Example

​PATCH /api/v1/playlist/add/:videoId/:playlistId

​Path parameters

​Response

​Errors

​Example

​PATCH /api/v1/playlist/remove/:videoId/:playlistId

​Path parameters

​Response

​Errors

​Example

​GET /api/v1/playlist/user/:userId

​Path parameters

​Response

​Example

​Playlist object schema

Build docs developers (and LLMs) love

POST /api/v1/playlist

Body parameters

Response

Errors

Example

GET /api/v1/playlist/:playlistId

Path parameters

Response

Example

PATCH /api/v1/playlist/:playlistId

Path parameters

Body parameters

Response

Errors

Example

DELETE /api/v1/playlist/:playlistId

Path parameters

Response

Errors

Example

PATCH /api/v1/playlist/add/:videoId/:playlistId

Path parameters

Response

Errors

Example

PATCH /api/v1/playlist/remove/:videoId/:playlistId

Path parameters

Response

Errors

Example

GET /api/v1/playlist/user/:userId

Path parameters

Response

Example

Playlist object schema