Video Comments API — List, Post, Edit, and Delete

All comment endpoints require a valid JWT in the Authorization header — unauthenticated requests are rejected. Comments are always scoped to a specific video identified by videoId. The paginated list endpoint joins owner profile data and live like counts into every comment document so that clients need only one request to render a full comment thread.

GET /api/v1/comments/:videoId

Returns a paginated list of comments for a given video, sorted from newest to oldest. Each comment is enriched with the owner’s public profile fields, a total like count, and a per-user isLiked flag.

Path parameters

videoId

string

required

The MongoDB ObjectId of the video whose comments you want to fetch. Returns 400 if the value is missing or not a valid ObjectId.

Query parameters

page

number

default:"1"

The page of results to return. Must be a positive integer.

limit

number

default:"10"

Maximum number of comments to return per page.

Response

Returns a mongoose-aggregate-paginate-v2 result envelope containing a docs array of comment objects.

docs

array

Array of comment objects for the requested page.

Show Comment object

_id

string

Unique identifier of the comment.

content

string

The text body of the comment.

video

string

ObjectId of the video this comment belongs to.

owner

string

ObjectId of the user who authored the comment.

ownerDetails

object

Resolved public profile of the comment author.

Show ownerDetails fields

username

string

Username of the comment author.

fullName

string

Full display name of the comment author.

avatar

string

URL of the author’s avatar image.

likesCount

number

Total number of likes on this comment.

isLiked

boolean

true if the currently authenticated user has liked this comment, otherwise false.

createdAt

string

ISO 8601 timestamp of when the comment was created.

updatedAt

string

ISO 8601 timestamp of when the comment was last updated.

totalDocs

number

Total number of comments for this video.

limit

number

The limit value used for this page.

page

number

The current page number.

totalPages

number

Total number of available pages.

hasNextPage

boolean

Whether a next page exists.

hasPrevPage

boolean

Whether a previous page exists.

Example

curl -X GET "https://api.videohub.com/api/v1/comments/64f1a2b3c4d5e6f7a8b9c0d1?page=1&limit=10" \
  -H "Authorization: Bearer <your_token>"

POST /api/v1/comments/:videoId

Adds a new comment to the specified video. The comment is associated with the authenticated user as owner.

Path parameters

videoId

string

required

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

Body parameters

content

string

required

The text body of the comment. Must be non-empty after trimming whitespace. Returns 400 if absent or blank.

Response

Returns 200 with the newly created comment document.

_id

string

Unique identifier of the created comment.

content

string

The submitted comment text.

video

string

ObjectId of the video the comment was added to.

owner

string

ObjectId of the authenticated user who created the comment.

createdAt

string

ISO 8601 creation timestamp.

updatedAt

string

ISO 8601 last-updated timestamp.

Errors

Status	Message
`400`	`"Comment body is mandatory"` — `content` was empty or whitespace-only.
`400`	`"Invalid Video ID format"` — `videoId` is not a valid MongoDB ObjectId.

Example

curl -X POST "https://api.videohub.com/api/v1/comments/64f1a2b3c4d5e6f7a8b9c0d1" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"content": "Great video, thanks for sharing!"}'

PATCH /api/v1/comments/c/:commentId

Updates the text of an existing comment. Only the user who originally authored the comment may edit it — attempting to edit someone else’s comment returns a 400 error.

Path parameters

commentId

string

required

The MongoDB ObjectId of the comment to update. Returns 400 if missing or invalid.

Body parameters

content

string

required

The new text body to replace the existing comment. Must be non-empty after trimming whitespace.

Response

Returns 200 with the full updated comment document.

_id

string

Unique identifier of the comment.

content

string

The updated comment text.

video

string

ObjectId of the associated video.

owner

string

ObjectId of the comment author.

createdAt

string

ISO 8601 creation timestamp.

updatedAt

string

ISO 8601 timestamp of the most recent edit.

Errors

Status	Message
`400`	`"You do not have permission to edit this comment"` — authenticated user is not the comment owner.
`400`	`"Comment body is mandatory"` — `content` was empty or whitespace-only.
`400`	`"Comment could not be found"` — no comment exists with the given `commentId`.
`400`	`"Invalid Comment ID format"` — `commentId` is not a valid MongoDB ObjectId.

Example

curl -X PATCH "https://api.videohub.com/api/v1/comments/c/64f1a2b3c4d5e6f7a8b9c0d2" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated: this is an even better video!"}'

DELETE /api/v1/comments/c/:commentId

Permanently deletes a comment. Only the comment’s original author may delete it. After deletion the comment is removed from the database and associated likes are no longer referenced.

Path parameters

commentId

string

required

The MongoDB ObjectId of the comment to delete. Returns 400 if missing or invalid.

Response

Returns 200 with an object containing the ID of the deleted comment.

deletedCommentId

string

The MongoDB ObjectId of the comment that was deleted.

Errors

Status	Message
`400`	`"You do not have permission to delete this comment"` — authenticated user is not the comment owner.
`400`	`"Comment could not be found"` — no comment exists with the given `commentId`.
`400`	`"Invalid Comment ID format"` — `commentId` is not a valid MongoDB ObjectId.

Example

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

Comment object schema

The base Comment document stored in MongoDB has the following shape. List responses augment this with the computed fields described above.

_id

ObjectId

MongoDB-generated unique identifier for the comment.

content

string

Text body of the comment. Required and must be non-empty.

video

ObjectId

Reference to the Video document this comment is attached to.

owner

ObjectId

Reference to the User document who authored the comment.

createdAt

Date

Automatically set by Mongoose timestamps on document creation.

updatedAt

Date

Automatically updated by Mongoose timestamps on every save.

List responses (GET /api/v1/comments/:videoId) include three additional computed fields not stored in the database: ownerDetails (username, fullName, avatar), likesCount, and isLiked. These are resolved at query time via MongoDB aggregation using $lookup on the users and likes collections respectively, then paginated with Comment.aggregatePaginate.

Overview

Users

Videos

Social Features

Dashboard

Video Comments API — List, Post, Edit, and Delete

GET /api/v1/comments/:videoId

Path parameters

Query parameters

Response

Example

POST /api/v1/comments/:videoId

Path parameters

Body parameters

Response

Errors

Example

PATCH /api/v1/comments/c/:commentId

Path parameters

Body parameters

Response

Errors

Example

DELETE /api/v1/comments/c/:commentId

Path parameters

Response

Errors

Example

Comment object schema

Build docs developers (and LLMs) love

Overview

Users

Videos

Social Features

Dashboard

Documentation Index

​GET /api/v1/comments/:videoId

​Path parameters

​Query parameters

​Response

​Example

​POST /api/v1/comments/:videoId

​Path parameters

​Body parameters

​Response

​Errors

​Example

​PATCH /api/v1/comments/c/:commentId

​Path parameters

​Body parameters

​Response

​Errors

​Example

​DELETE /api/v1/comments/c/:commentId

​Path parameters

​Response

​Errors

​Example

​Comment object schema

Build docs developers (and LLMs) love

GET /api/v1/comments/:videoId

Path parameters

Query parameters

Response

Example

POST /api/v1/comments/:videoId

Path parameters

Body parameters

Response

Errors

Example

PATCH /api/v1/comments/c/:commentId

Path parameters

Body parameters

Response

Errors

Example

DELETE /api/v1/comments/c/:commentId

Path parameters

Response

Errors

Example

Comment object schema