Progress tracking endpoints — lectures and courses

The progress tracking system records which lectures a student has completed within a course and computes an overall completionPercentage automatically. Each CourseProgress document is keyed by both a user and a course ObjectId, so every student has their own independent progress record per course. The completionPercentage and isCompleted fields are recalculated on every save via a pre-save hook — you never need to compute them yourself.

All progress endpoints are prefixed with /api/v1/progress. All four endpoints require authentication via the HTTP-only token cookie.

GET /api/v1/progress/:courseId

Retrieve the authenticated user’s progress record for a specific course. The response includes the populated course metadata and user info, as well as the per-lecture completion breakdown. Auth required: Yes

Path parameters

courseId

string

required

MongoDB ObjectId of the course whose progress you want to retrieve.

Response — 200

status

string

"success"

data

object

Show data properties

courseProgress

object

The full progress document.

Show courseProgress fields

_id

string

MongoDB document ID of the progress record.

user

object

Populated user with _id, name, and email.

course

object

Populated course with _id, title, and description.

isCompleted

boolean

true when completionPercentage reaches 100. Computed automatically.

completionPercentage

number

Percentage of lectures marked as completed. Range: 0 – 100. Computed on every save.

lectureProgress

array

Per-lecture progress entries.

Show lecture progress entry

lecture

string

ObjectId of the lecture.

isCompleted

boolean

Whether this lecture has been marked completed.

watchTime

number

Seconds watched (currently tracked as 0 unless updated by a client).

lastWatched

string

ISO 8601 timestamp of the last watched event.

lastAccessed

string

ISO 8601 timestamp of the most recent access.

createdAt

string

ISO 8601 creation timestamp.

updatedAt

string

ISO 8601 last-update timestamp.

curl --request GET \
  --url http://localhost:4000/api/v1/progress/64f1a2b3c4d5e6f7a8b9c0d1 \
  --cookie cookies.txt

Errors

Status	Condition
`400`	`courseId` is missing
`401`	Missing or invalid auth cookie
`404`	Course not found
`404`	No progress record found for this user and course

PATCH /api/v1/progress/:courseId/lectures/:lectureId

Mark a single lecture as completed or uncompleted. If no progress record exists for the user/course pair yet, the server creates one initialised with all lectures set to isCompleted: false and returns it immediately without applying the isCompleted update from the request body. On subsequent calls the specific lecture’s status is updated and completionPercentage is recalculated. Auth required: Yes

Path parameters

courseId

string

required

MongoDB ObjectId of the parent course.

lectureId

string

required

MongoDB ObjectId of the lecture to update.

Request body

isCompleted

boolean

required

Pass true to mark the lecture completed, false to mark it incomplete.

Response — 200

status

string

"success"

data

object

Show data properties

courseProgress

object

The updated CourseProgress document with recalculated completionPercentage and isCompleted.

curl --request PATCH \
  --url http://localhost:4000/api/v1/progress/64f1a2b3c4d5e6f7a8b9c0d1/lectures/65a1b2c3d4e5f6a7b8c9d0e1 \
  --cookie cookies.txt \
  --header 'Content-Type: application/json' \
  --data '{"isCompleted": true}'

Errors

Status	Condition
`400`	`courseId` or `lectureId` is missing
`400`	The specified lecture does not belong to this course
`401`	Missing or invalid auth cookie

POST /api/v1/progress/:courseId/complete

Mark every lecture in the course as completed in one operation, setting isCompleted: true on all lecture progress entries and the top-level isCompleted flag to true. The completionPercentage is saved as 100 after the pre-save hook runs. Auth required: Yes

Path parameters

courseId

string

required

MongoDB ObjectId of the course to mark as fully completed.

Request body

No request body is required.

Response — 200

status

string

"success"

message

string

"Course marked as completed"

data

object

Show data properties

courseProgress

object

The updated progress document with all lectures and the top-level isCompleted set to true and completionPercentage at 100.

curl --request POST \
  --url http://localhost:4000/api/v1/progress/64f1a2b3c4d5e6f7a8b9c0d1/complete \
  --cookie cookies.txt

Errors

Status	Condition
`400`	`courseId` is missing
`401`	Missing or invalid auth cookie
`404`	No progress record found for this user and course

POST /api/v1/progress/:courseId/reset

Reset all lecture progress for a course to its initial state. Every lecture entry’s isCompleted is set to false, lastWatched is cleared to null, and the top-level isCompleted is set to false. The completionPercentage is recomputed to 0 by the pre-save hook. Auth required: Yes

Path parameters

courseId

string

required

MongoDB ObjectId of the course whose progress should be reset.

Request body

No request body is required.

Response — 200

status

string

"success"

message

string

"Course progress has been reset"

data

object

Show data properties

courseProgress

object

The reset progress document with isCompleted: false, completionPercentage: 0, and all lecture entries set to isCompleted: false.

curl --request POST \
  --url http://localhost:4000/api/v1/progress/64f1a2b3c4d5e6f7a8b9c0d1/reset \
  --cookie cookies.txt

Resetting progress clears all lecture completion data for this course. The action is saved immediately and cannot be undone.

Errors

Status	Condition
`400`	`courseId` is missing
`401`	Missing or invalid auth cookie
`404`	No progress record found for this user and course

Overview

Endpoints

Progress tracking endpoints — lectures and courses

GET /api/v1/progress/:courseId

Path parameters

Response — 200

Errors

PATCH /api/v1/progress/:courseId/lectures/:lectureId

Path parameters

Request body

Response — 200

Errors

POST /api/v1/progress/:courseId/complete

Path parameters

Request body

Response — 200

Errors

POST /api/v1/progress/:courseId/reset

Path parameters

Request body

Response — 200

Errors

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/v1/progress/:courseId

​Path parameters

​Response — 200

​Errors

​PATCH /api/v1/progress/:courseId/lectures/:lectureId

​Path parameters

​Request body

​Response — 200

​Errors

​POST /api/v1/progress/:courseId/complete

​Path parameters

​Request body

​Response — 200

​Errors

​POST /api/v1/progress/:courseId/reset

​Path parameters

​Request body

​Response — 200

​Errors

Build docs developers (and LLMs) love

GET /api/v1/progress/:courseId

Path parameters

Response — 200

Errors

PATCH /api/v1/progress/:courseId/lectures/:lectureId

Path parameters

Request body

Response — 200

Errors

POST /api/v1/progress/:courseId/complete

Path parameters

Request body

Response — 200

Errors

POST /api/v1/progress/:courseId/reset

Path parameters

Request body

Response — 200

Errors