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 Users API covers the full user lifecycle — from creating an account and authenticating, to updating your profile details and retrieving your personal watch history. Most endpoints require a valid JWT access token passed as a Bearer header.

​
POST /api/v1/users/register

Register a new user account. Send as multipart/form-data because avatar upload is required.
​
username
string
required
Unique username (stored lowercase).
​
email
string
required
Unique email address.
​
password
string
required
Account password (hashed with bcrypt before storage).
​
fullname
string
required
Display name for the user.
​
avatar
file
required
Profile picture. Uploaded to Cloudinary.
​
coverImage
file
Optional channel cover image. Uploaded to Cloudinary.
curl -X POST https://vidtube-ke5w.onrender.com/api/v1/users/register \
  -F "username=johndoe" \
  -F "email=john@example.com" \
  -F "password=secret123" \
  -F "fullname=John Doe" \
  -F "avatar=@/path/to/avatar.jpg"
Response (201) 
{
  "statusCode": 201,
  "data": {
    "_id": "664abc123...",
    "username": "johndoe",
    "email": "john@example.com",
    "fullname": "john doe",
    "avatar": "https://res.cloudinary.com/...",
    "coverImage": "",
    "watchHistory": [],
    "createdAt": "2024-05-01T10:00:00.000Z"
  },
  "message": "User registered Successfully",
  "success": true
}
Error codes: 400 (missing required fields, user already exists, missing avatar), 500 (Cloudinary upload failed)

​
POST /api/v1/users/login

Log in with email and username. Returns access and refresh tokens, and sets httpOnly cookies.
​
email
string
required
Registered email address.
​
username
string
required
Registered username.
​
password
string
required
Account password.
curl -X POST https://vidtube-ke5w.onrender.com/api/v1/users/login \
  -H "Content-Type: application/json" \
  -d '{"email":"john@example.com","username":"johndoe","password":"secret123"}'
Response (200) 
{
  "statusCode": 200,
  "data": {
    "user": { "_id": "664abc123...", "username": "johndoe", "email": "john@example.com" },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "message": "User logged In successfully",
  "success": true
}
The response also sets accessToken and refreshToken as httpOnly cookies, so browser clients authenticate automatically on subsequent requests.
Error codes: 400 (missing fields), 401 (invalid credentials), 404 (user not found)

​
POST /api/v1/users/logout

Protected — requires Authorization: Bearer <accessToken>
Log out the current user. Clears the accessToken and refreshToken cookies and invalidates the refresh token in the database. 
curl -X POST https://vidtube-ke5w.onrender.com/api/v1/users/logout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response (200) 
{ "statusCode": 200, "data": {}, "message": "User logged out successfully", "success": true }

​
POST /api/v1/users/refresh-Token

Exchange a refresh token for a new access/refresh token pair. The refresh token can be sent in the cookie (browser clients) or in the request body.
​
refreshToken
string
Refresh token. Optional if the refreshToken cookie is set.
curl -X POST https://vidtube-ke5w.onrender.com/api/v1/users/refresh-Token \
  -H "Content-Type: application/json" \
  -d '{"refreshToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}'
Response (200) — returns new accessToken and refreshToken, and sets new cookies. Error codes: 401 (missing, invalid, or mismatched refresh token), 500

​
GET /api/v1/users/current-user

Protected — requires Authorization: Bearer <accessToken>
Return the authenticated user’s full profile. 
curl https://vidtube-ke5w.onrender.com/api/v1/users/current-user \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response (200) — returns the user document (excluding password and refreshToken).

​
PATCH /api/v1/users/update-account

Protected — requires Authorization: Bearer <accessToken>
Update the authenticated user’s fullname and email.
​
fullname
string
required
New display name.
​
email
string
required
New email address.
curl -X PATCH https://vidtube-ke5w.onrender.com/api/v1/users/update-account \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fullname":"Jane Doe","email":"jane@example.com"}'
Error codes: 400 (missing fullname or email), 401

​
PATCH /api/v1/users/update-avatar

Protected — requires Authorization: Bearer <accessToken>
Upload a new profile avatar. Send as multipart/form-data.
​
avatar
file
required
New avatar image file. Uploaded to Cloudinary.
curl -X PATCH https://vidtube-ke5w.onrender.com/api/v1/users/update-avatar \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "avatar=@/path/to/new-avatar.jpg"
Error codes: 400 (missing file), 500 (upload failed)

​
GET /api/v1/users/history

Protected — requires Authorization: Bearer <accessToken>
Retrieve the authenticated user’s video watch history. Each video entry includes the owner’s fullname, username, and avatar. 
curl https://vidtube-ke5w.onrender.com/api/v1/users/history \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response (200) 
{
  "statusCode": 200,
  "data": [
    {
      "_id": "664vid123...",
      "title": "My First Video",
      "videoFile": "https://res.cloudinary.com/...",
      "thumbnail": "https://res.cloudinary.com/...",
      "duration": "3: 42 seconds",
      "owner": { "fullname": "jane doe", "username": "janedoe", "avatar": "https://..." }
    }
  ],
  "message": "Watch History fetched successfully",
  "success": true
}

​
POST /api/v1/users/change-password

Protected — requires Authorization: Bearer <accessToken>
Change the authenticated user’s password by providing the current password alongside the new one.
​
oldPassword
string
required
The user’s current password.
​
newPassword
string
required
The new password to set.
curl -X POST https://vidtube-ke5w.onrender.com/api/v1/users/change-password \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"oldPassword":"current123","newPassword":"newSecret456"}'
Response (200) 
{ "statusCode": 200, "data": {}, "message": "Password changed successfully", "success": true }
Error codes: 401 (incorrect old password), 401 (not authenticated)

​
PATCH /api/v1/users/update-cover

Protected — requires Authorization: Bearer <accessToken>
Upload a new channel cover image. Send as multipart/form-data.
​
coverImage
file
required
New cover image file. Uploaded to Cloudinary.
curl -X PATCH https://vidtube-ke5w.onrender.com/api/v1/users/update-cover \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "coverImage=@/path/to/cover.jpg"
Error codes: 400 (missing file), 500 (upload failed)

​
GET /api/v1/users/c/:username

Protected — requires Authorization: Bearer <accessToken>
Retrieve a channel profile by username. Returns the channel’s subscriber count, channels-subscribed-to count, and whether the currently authenticated user is subscribed to this channel.
​
username
string
required
The channel’s username (case-insensitive).
curl https://vidtube-ke5w.onrender.com/api/v1/users/c/johndoe \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response (200) 
{
  "statusCode": 200,
  "data": {
    "fullname": "john doe",
    "username": "johndoe",
    "email": "john@example.com",
    "avatar": "https://res.cloudinary.com/...",
    "coverImage": "https://res.cloudinary.com/...",
    "subscriberCount": 342,
    "channelsSubscribedToCount": 17,
    "isSubscribed": false
  },
  "message": "Channel profile fetched successfully",
  "success": true
}
Error codes: 401 (username missing or not authenticated), 404 (channel not found)

Build docs developers (and LLMs) love

Get started for freeTalk to us