Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Pragyat-Nikunj/VidTube/llms.txt

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

The Playlists API lets you organize videos into named collections. You can create a playlist, add videos to it, remove individual videos, rename it, or delete it entirely. Ownership is enforced — only the playlist creator can modify or delete it.

​
POST /api/v1/playlist/createPlaylist

Protected — requires Authorization: Bearer <accessToken>
Create a new playlist owned by the authenticated user.
​
name
string
required
Playlist name.
​
description
string
required
Playlist description.
curl -X POST https://vidtube-ke5w.onrender.com/api/v1/playlist/createPlaylist \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Favorites","description":"Videos I love"}'
Response (201) 
{
  "statusCode": 201,
  "data": {
    "_id": "664pl001...",
    "name": "My Favorites",
    "description": "Videos I love",
    "videos": [],
    "owner": "664usr789...",
    "createdAt": "2024-05-01T10:00:00.000Z"
  },
  "message": "Playlist created successfully.",
  "success": true
}
Error codes: 400 (missing name or description)

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

List all playlists belonging to a user. Results are paginated and sorted newest first.
​
userId
string
required
MongoDB ObjectId of the user whose playlists to fetch.
​
page
integer
Page number. Defaults to 1.
​
limit
integer
Items per page. Defaults to 10.
curl "https://vidtube-ke5w.onrender.com/api/v1/playlist/user/664usr789...?page=1&limit=10"
Response (200) 
{
  "statusCode": 200,
  "data": {
    "userPlaylists": [
      { "_id": "664pl001...", "name": "My Favorites", "description": "Videos I love" }
    ],
    "page": 1,
    "totalPages": 1,
    "totalCount": 1
  },
  "message": "Playlist fetched successfully.",
  "success": true
}
Error codes: 400 (missing or invalid userId)

​
GET /api/v1/playlist/:playlistId

Fetch a single playlist by ID, including its list of video IDs.
​
playlistId
string
required
MongoDB ObjectId of the playlist.
curl https://vidtube-ke5w.onrender.com/api/v1/playlist/664pl001...
Error codes: 400 (invalid ID format), 404 (playlist not found)

​
PUT /api/v1/playlist/:playlistId/videos/:videoId

Protected — requires Authorization: Bearer <accessToken>
Add a video to a playlist. You must own the playlist and the video must exist. A video cannot be added twice.
​
playlistId
string
required
MongoDB ObjectId of the playlist.
​
videoId
string
required
MongoDB ObjectId of the video to add.
curl -X PUT https://vidtube-ke5w.onrender.com/api/v1/playlist/664pl001.../videos/664vid123... \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response (200) — returns the updated playlist with videos populated (title, thumbnail). Error codes: 400 (invalid IDs, video already in playlist), 403 (not playlist owner), 404 (playlist or video not found)

​
DELETE /api/v1/playlist/:playlistId/videos/:videoId

Protected — requires Authorization: Bearer <accessToken>
Remove a video from a playlist.
​
playlistId
string
required
MongoDB ObjectId of the playlist.
​
videoId
string
required
MongoDB ObjectId of the video to remove.
curl -X DELETE https://vidtube-ke5w.onrender.com/api/v1/playlist/664pl001.../videos/664vid123... \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Error codes: 400 (video not in playlist), 403 (not playlist owner), 404

​
DELETE /api/v1/playlist/:playlistId

Protected — requires Authorization: Bearer <accessToken>
Delete an entire playlist. You must own the playlist.
​
playlistId
string
required
MongoDB ObjectId of the playlist to delete.
curl -X DELETE https://vidtube-ke5w.onrender.com/api/v1/playlist/664pl001... \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Error codes: 403 (not playlist owner), 404 (not found)

​
PATCH /api/v1/playlist/:playlistId

Protected — requires Authorization: Bearer <accessToken>
Rename or update a playlist’s description. At least one field (name or description) is required.
​
playlistId
string
required
MongoDB ObjectId of the playlist.
​
name
string
New playlist name.
​
description
string
New playlist description.
curl -X PATCH https://vidtube-ke5w.onrender.com/api/v1/playlist/664pl001... \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Top Picks"}'
Error codes: 400 (no fields provided, invalid ID), 403 (not playlist owner), 404

Build docs developers (and LLMs) love

Get started for freeTalk to us