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.

VidTube handles video uploads through a multipart pipeline: files are received by the server, their duration is measured with FFprobe, and then both the video and thumbnail are pushed to Cloudinary. The original local files are deleted from the server once the upload succeeds. All write operations require a valid Authorization: Bearer <token> header; the read-only listing and detail endpoints are public.
Both title and the video file are required when publishing a video. Submitting JSON or application/x-www-form-urlencoded bodies will not work — you must use multipart/form-data.

​
Publishing a video

1

Prepare your files

You need at least a video file and a title. A thumbnail is strongly recommended — if you omit it, the upload will still fail because the server requires a thumbnail URL in the database. Have both files ready on disk.
2

Send the multipart request

Use the -F flag in curl to send fields and files as multipart/form-data.
curl -X POST https://vidtube-ke5w.onrender.com/api/v1/videos/publishVideo \
  -H "Authorization: Bearer <your_access_token>" \
  -F "title=My First Video" \
  -F "description=A short introduction to VidTube" \
  -F "video=@/path/to/video.mp4" \
  -F "thumbnail=@/path/to/thumbnail.jpg"
FieldTypeRequiredDescription
titlestringYesVideo title
descriptionstringNoVideo description (defaults to “No description provided”)
videofileYesThe video file (any format FFprobe can read)
thumbnailfileYesThumbnail image
3

Check the response

A successful upload returns HTTP 200 with the new video document.
{
  "statusCode": 200,
  "data": {
    "_id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "title": "My First Video",
    "description": "A short introduction to VidTube",
    "videoFile": "https://res.cloudinary.com/your_cloud/video/upload/v1234567890/video-1234567890.mp4",
    "thumbnail": "https://res.cloudinary.com/your_cloud/image/upload/v1234567890/thumbnail-1234567890.jpg",
    "duration": "2: 34 seconds",
    "views": 0,
    "isPublished": 1,
    "owner": "64e0a1b2c3d4e5f6a7b8c9d0",
    "createdAt": "2024-09-01T12:00:00.000Z",
    "updatedAt": "2024-09-01T12:00:00.000Z"
  },
  "message": "Video uploaded successfully",
  "success": true
}
The duration field is auto-computed by FFprobe from the uploaded file. The isPublished field defaults to true (the integer 1 is also used — see toggling publish status).
Files are uploaded to Cloudinary with resource_type: "auto", so any video or image format that Cloudinary supports is accepted. If the Cloudinary upload fails after the video has already been uploaded, the server automatically calls deleteFromCloudinary to clean up the partial upload before returning an error.

​
Listing videos

GET /api/v1/videos/getAllVideos is public — no token required. Use query parameters to filter, sort, and paginate. 
curl "https://vidtube-ke5w.onrender.com/api/v1/videos/getAllVideos?query=introduction&sortBy=views&sortType=desc&page=1&limit=10"
ParameterDefaultAllowed valuesDescription
page1Any integer ≥ 1Page number
limit101–100Results per page
query—Any stringCase-insensitive search against title and description
sortBycreatedAtcreatedAt, views, likesField to sort by
sortTypedescasc, descSort direction
userId—A valid user IDFilter to videos owned by a specific user
Response: 
{
  "statusCode": 200,
  "data": {
    "videos": [
      {
        "_id": "64f1a2b3c4d5e6f7a8b9c0d1",
        "title": "My First Video",
        "videoFile": "https://res.cloudinary.com/...",
        "thumbnail": "https://res.cloudinary.com/...",
        "duration": "2: 34 seconds",
        "views": 142,
        "isPublished": 1,
        "owner": "64e0a1b2c3d4e5f6a7b8c9d0"
      }
    ],
    "totalVideos": 58,
    "totalPages": 6
  },
  "message": "Video fetched successfully.",
  "success": true
}

​
Getting a video by ID

curl https://vidtube-ke5w.onrender.com/api/v1/videos/getVideoById/64f1a2b3c4d5e6f7a8b9c0d1
Returns the full video document or 404 if the ID does not exist. This endpoint is public.

​
Updating a video

Send a PATCH request with any combination of fields you want to change. You must provide at least one field — the request is rejected if all four are absent. 
curl -X PATCH https://vidtube-ke5w.onrender.com/api/v1/videos/updateVideo/64f1a2b3c4d5e6f7a8b9c0d1 \
  -H "Authorization: Bearer <your_access_token>" \
  -F "title=Updated Title" \
  -F "thumbnail=@/path/to/new-thumbnail.jpg"
FieldTypeDescription
titlestringNew video title
descriptionstringNew description
videofileReplacement video file (duration is re-computed)
thumbnailfileReplacement thumbnail image

​
Deleting a video

curl -X DELETE https://vidtube-ke5w.onrender.com/api/v1/videos/deleteVideo/64f1a2b3c4d5e6f7a8b9c0d1 \
  -H "Authorization: Bearer <your_access_token>"
Returns the deleted video document on success, or 404 if not found.
Deleting a video through this endpoint removes the database record, but does not automatically purge the Cloudinary assets. You may want to handle Cloudinary cleanup on your own if storage usage is a concern.

​
Toggling publish status

Call this endpoint to flip a video between published and unpublished. The isPublished field is stored as a number: 1 is published, 0 is unpublished. Calling the endpoint again reverses the state. 
curl -X PATCH https://vidtube-ke5w.onrender.com/api/v1/videos/togglePublish/64f1a2b3c4d5e6f7a8b9c0d1 \
  -H "Authorization: Bearer <your_access_token>"

{
  "statusCode": 200,
  "data": {
    "_id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "title": "My First Video",
    "isPublished": 0
  },
  "message": "Video publish status updated successfully.",
  "success": true
}

​
Endpoint summary

MethodPathAuthDescription
GET/api/v1/videos/getAllVideosPublicList and search videos
GET/api/v1/videos/getVideoById/:videoIdPublicFetch a single video
POST/api/v1/videos/publishVideoRequiredUpload a new video
PATCH/api/v1/videos/updateVideo/:videoIdRequiredUpdate video metadata/files
DELETE/api/v1/videos/deleteVideo/:videoIdRequiredDelete a video
PATCH/api/v1/videos/togglePublish/:videoIdRequiredToggle published/unpublished

Build docs developers (and LLMs) love

Get started for freeTalk to us