Course endpoints — create, search, and manage

Courses are the central resource in the LMS Backend. Each course has a title, optional subtitle and description, a category, a difficulty level, a price, and a Cloudinary-hosted thumbnail. Only the authenticated instructor who created a course can update it. Students browse published courses and enroll via the payments flow.

All endpoints are prefixed with /api/v1/courses. Protected endpoints require the HTTP-only token cookie set during sign-in.

POST /api/v1/courses

Create a new course. The thumbnail image is uploaded to Cloudinary and its secure URL is stored in the document. You must be authenticated — the server reads the instructor ID from the verified JWT cookie. Auth required: Yes
Content-Type: multipart/form-data

Request body

title

string

required

Course title. Maximum 100 characters.

category

string

required

Course category (free text, e.g. "Web Development", "Data Science").

price

number

required

Course price in USD. Must be a non-negative number.

thumbnail

file

required

Thumbnail image file. The field name must be thumbnail. Uploaded to Cloudinary; the returned secure URL is stored on the course document.

subtitle

string

Short one-line subtitle. Maximum 200 characters. Defaults to an empty string if omitted.

description

string

Full course description. No length limit enforced by the model.

level

string

default:"beginner"

Difficulty level. Accepted values: beginner, intermediate, advanced.

Response — 201

success

boolean

true on successful creation.

message

string

"Course created successfully"

course

object

The newly created course document.

Show course fields

_id

string

MongoDB document ID.

title

string

Course title.

subtitle

string

Short subtitle.

description

string

Full description.

category

string

Course category.

level

string

beginner, intermediate, or advanced.

price

number

Price in USD.

thumbnail

string

Cloudinary secure URL for the thumbnail image.

instructor

string

ObjectId of the creating user.

isPublished

boolean

Whether the course is visible in the public catalog. Default: false.

lectures

array

Array of lecture ObjectIds. Empty on creation.

enrolledStudents

array

Array of student ObjectIds. Empty on creation.

totalLectures

number

Computed from lectures.length. Default: 0.

totalDuration

number

Total duration in seconds. Default: 0.

createdAt

string

ISO 8601 creation timestamp.

updatedAt

string

ISO 8601 last-update timestamp.

curl --request POST \
  --url http://localhost:4000/api/v1/courses \
  --cookie cookies.txt \
  --form 'title=Introduction to Node.js' \
  --form 'category=Web Development' \
  --form 'price=49' \
  --form 'level=beginner' \
  --form 'subtitle=Build REST APIs from scratch' \
  --form 'description=A complete beginner course covering Express, MongoDB, and authentication.' \
  --form 'thumbnail=@/path/to/thumbnail.jpg'

Errors

Status	Condition
`400`	Thumbnail file is missing from the request
`401`	Missing or invalid auth cookie

GET /api/v1/courses/search

Search for courses using one or more text filters. At least one query parameter must be provided. Results are sorted by most recently created and paginated. Auth required: No

Query parameters

title

string

Case-insensitive partial match on the course title.

subtitle

string

Case-insensitive partial match on the subtitle.

description

string

Case-insensitive partial match on the description text.

category

string

Case-insensitive partial match on the category.

level

string

Exact match on difficulty level: beginner, intermediate, or advanced.

price

number

Maximum price. Returns courses with price <= this value.

page

number

default:"1"

Page number (1-indexed).

limit

number

default:"10"

Number of results per page.

Response — 200

success

boolean

true on success.

data

object

Show data properties

courses

array

Array of matching course objects. The instructor field is populated with name and email.

totalCourses

number

Total matching documents across all pages.

totalPages

number

Total number of pages at the requested limit.

currentPage

number

The current page number.

curl --request GET \
  --url 'http://localhost:4000/api/v1/courses/search?category=Web+Development&level=beginner&page=1&limit=10'

Errors

Status	Condition
`400`	No search parameters provided

GET /api/v1/courses/published

Retrieve a paginated list of all published courses. The instructor field on each course is populated with name and email. Auth required: No

Query parameters

page

number

default:"1"

Page number (1-indexed).

limit

number

default:"10"

Results per page.

Response — 200

success

boolean

true on success.

data

object

Show data properties

courses

array

Paginated array of published course objects.

totalCourses

number

Total published courses in the database.

totalPages

number

Total pages at the requested limit.

currentPage

number

Current page number.

curl --request GET \
  --url 'http://localhost:4000/api/v1/courses/published?page=1&limit=12'

GET /api/v1/courses/my-courses

Retrieve all courses created by the authenticated user. Results are sorted by most recently created. The instructor field is populated. Auth required: Yes

Query parameters

page

number

default:"1"

Page number.

limit

number

default:"10"

Results per page.

Response — 200

success

boolean

true on success.

data

object

Show data properties

courses

array

The instructor’s courses, sorted newest first.

totalCourses

number

Total courses belonging to this instructor.

totalPages

number

Total pages.

currentPage

number

Current page.

curl --request GET \
  --url 'http://localhost:4000/api/v1/courses/my-courses' \
  --cookie cookies.txt

Errors

Status	Condition
`401`	Missing or invalid auth cookie

GET /api/v1/courses/:courseId

Retrieve full details for a single course. The instructor field is populated with name and email. The lectures array is populated with each lecture’s title, description, and videoUrl. Auth required: No

Path parameters

courseId

string

required

The MongoDB ObjectId of the course to retrieve.

Response — 200

success

boolean

true on success.

course

object

Full course document with instructor and lectures populated.

Show course fields

_id

string

MongoDB document ID.

title

string

Course title.

subtitle

string

Short subtitle.

description

string

Full description.

category

string

Course category.

level

string

Difficulty level.

price

number

Price in USD.

thumbnail

string

Cloudinary secure URL.

isPublished

boolean

Publication status.

instructor

object

Populated instructor with _id, name, and email.

lectures

array

Populated lecture objects, each with _id, title, description, and videoUrl.

totalLectures

number

Count of lectures.

totalDuration

number

Total duration in seconds.

enrolledStudents

array

Array of enrolled student ObjectIds.

curl --request GET \
  --url http://localhost:4000/api/v1/courses/64f1a2b3c4d5e6f7a8b9c0d1

Errors

Status	Condition
`400`	`courseId` is missing

PATCH /api/v1/courses/:courseId

Update an existing course. Only the instructor who created the course can perform updates. If a new thumbnail is uploaded, the old Cloudinary asset is deleted before the new one is stored. All body fields are optional — send only the fields you want to change. Auth required: Yes — must be the course instructor
Content-Type: multipart/form-data (when uploading a new thumbnail), or application/json (text-only updates)

Path parameters

courseId

string

required

The MongoDB ObjectId of the course to update.

Request body

title

string

Updated course title.

subtitle

string

Updated subtitle.

description

string

Updated full description.

category

string

Updated category.

level

string

Updated difficulty level: beginner, intermediate, or advanced.

price

number

Updated price in USD.

thumbnail

file

Replacement thumbnail image. The field name must be thumbnail. The old Cloudinary asset is deleted automatically.

Response — 200

success

boolean

true on success.

message

string

"Course updated successfully"

course

object

The updated course document.

curl --request PATCH \
  --url http://localhost:4000/api/v1/courses/64f1a2b3c4d5e6f7a8b9c0d1 \
  --cookie cookies.txt \
  --header 'Content-Type: application/json' \
  --data '{"price": 39, "level": "intermediate"}'

Errors

Status	Condition
`400`	`courseId` is missing
`401`	Missing or invalid auth cookie
`403`	Authenticated user is not the course instructor
`404`	Course not found
`500`	Database update failed

Overview

Endpoints

Course endpoints — create, search, and manage

POST /api/v1/courses

Request body

Response — 201

Errors

GET /api/v1/courses/search

Query parameters

Response — 200

Errors

GET /api/v1/courses/published

Query parameters

Response — 200

GET /api/v1/courses/my-courses

Query parameters

Response — 200

Errors

GET /api/v1/courses/:courseId

Path parameters

Response — 200

Errors

PATCH /api/v1/courses/:courseId

Path parameters

Request body

Response — 200

Errors

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​POST /api/v1/courses

​Request body

​Response — 201

​Errors

​GET /api/v1/courses/search

​Query parameters

​Response — 200

​Errors

​GET /api/v1/courses/published

​Query parameters

​Response — 200

​GET /api/v1/courses/my-courses

​Query parameters

​Response — 200

​Errors

​GET /api/v1/courses/:courseId

​Path parameters

​Response — 200

​Errors

​PATCH /api/v1/courses/:courseId

​Path parameters

​Request body

​Response — 200

​Errors

Build docs developers (and LLMs) love

POST /api/v1/courses

Request body

Response — 201

Errors

GET /api/v1/courses/search

Query parameters

Response — 200

Errors

GET /api/v1/courses/published

Query parameters

Response — 200

GET /api/v1/courses/my-courses

Query parameters

Response — 200

Errors

GET /api/v1/courses/:courseId

Path parameters

Response — 200

Errors

PATCH /api/v1/courses/:courseId

Path parameters

Request body

Response — 200

Errors