Course Progress & Enrollment

Endpoints for tracking course progress, lesson completion, and earning gamified rewards.

Enroll in Course

Enrolls the authenticated user into a course, setting up the user’s progress tracking ledger.

Endpoint

POST /api/v2/user-courses/enroll/:courseId

Headers

Authorization: Bearer <jwt_access_token>

Response (201 Created)

{
  "success": true,
  "data": {
    "id": "enrollment-uuid",
    "courseId": "7a3e9c12-3456-4abc-8def-1234567890ab",
    "progressPercentage": 0,
    "enrolledAt": "2026-08-22T02:15:00.000Z"
  },
  "message": "Successfully enrolled in course"
}

Complete Lesson

Submits completion for a specific lesson, awarding XP, gems, updating streaks, and calculating new course completion percentages.

Endpoint

POST /api/v2/user-lessons/:lessonId/complete

Headers

Authorization: Bearer <jwt_access_token>

Request Body

Field	Type	Required	Description
`timeSpentSeconds`	`number`	No	Time user spent studying this lesson
`score`	`number`	No	Quiz score percentage (if lesson ended with a quiz)

{
  "timeSpentSeconds": 240,
  "score": 100
}

Response (200 OK)

{
  "success": true,
  "data": {
    "lessonId": "9f1e8d7c-6b5a-4321-fedc-ba9876543210",
    "courseId": "7a3e9c12-3456-4abc-8def-1234567890ab",
    "xpEarned": 50,
    "gemsEarned": 5,
    "newTotalXP": 500,
    "newTotalGems": 40,
    "courseProgress": 75.0,
    "streakDays": 4,
    "unlockedBadge": null
  },
  "message": "Lesson completed successfully"
}