Momentum API Documentation

This document provides comprehensive documentation for the Momentum Learning Management Platform REST API. The API is built using AWS API Gateway with AWS Lambda backend functions.

Table of Contents

• Base Configuration
• Authentication
• Common Response Formats
• Error Handling
• API Endpoints
  • Categories
  • Courses
  • Lessons
  • Enrollments
  • Progress
  • Users
  • Analytics
  • Badges
  • Recommendations
  • AI Generation
• Data Models
• TypeScript Types

Base Configuration

Base URL

All API endpoints are relative to the base URL of the deployed API Gateway stage:

https://<api-gateway-id>.execute-api.us-east-1.amazonaws.com/dev

Current Production URL:

https://iu7ewpcwvc.execute-api.us-east-1.amazonaws.com/dev

Common Headers

Content-Type: application/json
Authorization: Bearer <cognito-jwt-token>
X-Api-Key: <api-key>

Authentication

The API uses AWS Cognito for authentication with JWT tokens.

Authentication Types

1. Public Endpoints - No authentication required
2. Authenticated Endpoints - Require valid JWT token from Cognito
3. Admin-Only Endpoints - Require JWT token + admin role in Cognito groups

Getting a JWT Token

Users authenticate through the frontend application, which uses AWS Cognito. The Cognito JWT ID token must be included in the Authorization header:

Authorization: Bearer eyJraWQiOiJ...

Admin Authorization

Admin endpoints verify that the user belongs to the admin group in Cognito. This is checked via the cognito:groups claim in the JWT token.

Common Response Formats

Success Response

{
  // Direct data return for successful responses
  "id": "uuid",
  "name": "Resource Name",
  // ... other fields
}

List Response

{
  "items": [...],
  "total": 100,
  "limit": 20,
  "offset": 0
}

Simple Confirmation

{
  "message": "Operation completed successfully"
}

Error Handling

Error Response Format

{
  "error": "Error message description",
  "details": "Additional error context" // Optional
}

HTTP Status Codes

Status Code	Description
200	Success (GET, PUT, PATCH)
201	Created (POST)
204	No Content (DELETE)
400	Bad Request - Validation error or missing parameters
401	Unauthorized - Missing or invalid authentication token
403	Forbidden - Insufficient permissions or access denied
404	Not Found - Resource does not exist
405	Method Not Allowed - HTTP method not supported
500	Internal Server Error - Server-side error

---

API Endpoints

Categories

Manage course categories. Categories are used to organize courses by subject area.

GET /categories

List all available categories.

Authentication: None (Public)

Query Parameters: None

Example Request:

curl https://iu7ewpcwvc.execute-api.us-east-1.amazonaws.com/dev/categories

Response: 200 OK

{
  "categories": [
    {
      "id": "uuid",
      "name": "Personal Development",
      "slug": "personal-development",
      "description": "Courses focused on personal growth and development",
      "icon_url": "https://example.com/icons/personal-dev.svg",
      "created_at": "2024-01-01T00:00:00.000Z"
    },
    {
      "id": "uuid",
      "name": "Health & Wellness",
      "slug": "health-wellness",
      "description": "Health, fitness, and wellness courses",
      "icon_url": "https://example.com/icons/health.svg",
      "created_at": "2024-01-01T00:00:00.000Z"
    }
  ]
}

---

Courses

Manage course content and metadata.

GET /courses

List courses with optional filtering, or retrieve a specific course by ID.

Authentication: Optional (admins see draft courses, public users see only published)

Query Parameters:

Parameter	Type	Description
id	string	Get a specific course by ID
category	string	Filter by category ID
search	string	Search term for course titles and descriptions
duration	number	Filter by duration (7, 14, or 21 days)
limit	number	Number of items to return (default: 20, max: 100)
offset	number	Pagination offset (default: 0)

Example Request (List):

curl "https://api.example.com/dev/courses?category=uuid&limit=10&offset=0"

Response (List): 200 OK

{
  "courses": [
    {
      "id": "uuid",
      "title": "7-Day Mindfulness Challenge",
      "description": "Learn mindfulness techniques in just 7 days",
      "category_id": "uuid",
      "duration_days": 7,
      "price": 29.99,
      "thumbnail": "https://example.com/thumbnails/course.jpg",
      "status": "PUBLISHED",
      "metadata": {},
      "ai_generated": false,
      "generation_job_id": null,
      "intro_video_url": "https://example.com/videos/intro.mp4",
      "intro_video_status": "completed",
      "what_you_will_learn": [
        "Daily mindfulness practices",
        "Stress reduction techniques",
        "Improved focus and clarity"
      ],
      "requirements": [
        "Open mind and willingness to practice",
        "10-15 minutes per day"
      ],
      "instructor": {
        "name": "Dr. Jane Smith",
        "title": "Mindfulness Expert",
        "avatar": "https://example.com/avatars/jane.jpg"
      },
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z"
    }
  ],
  "total": 42
}

Example Request (Single Course):

curl "https://api.example.com/dev/courses?id=uuid"

Response (Single): 200 OK

{
  "id": "uuid",
  "title": "7-Day Mindfulness Challenge",
  "description": "Learn mindfulness techniques in just 7 days",
  // ... (same fields as in list response)
}

POST /courses

Create a new course.

Authentication: Required (Admin only)

Request Body:

{
  "title": "New Course Title",
  "description": "Detailed course description",
  "category_id": "uuid",
  "duration_days": 14, // Must be 7, 14, or 21
  "price": 49.99,
  "thumbnail": "https://example.com/thumbnails/new-course.jpg", // Optional
  "metadata": { // Optional
    "difficulty": "intermediate",
    "tags": ["productivity", "time-management"]
  }
}

Response: 201 Created

{
  "id": "uuid",
  "title": "New Course Title",
  "description": "Detailed course description",
  "category_id": "uuid",
  "duration_days": 14,
  "price": 49.99,
  "thumbnail": "https://example.com/thumbnails/new-course.jpg",
  "status": "DRAFT",
  "metadata": {
    "difficulty": "intermediate",
    "tags": ["productivity", "time-management"]
  },
  "ai_generated": false,
  "created_at": "2024-01-20T15:45:00.000Z",
  "updated_at": "2024-01-20T15:45:00.000Z"
}

Validation Errors: 400 Bad Request

{
  "error": "Validation failed",
  "details": [
    "title is required",
    "duration_days must be 7, 14, or 21"
  ]
}

PUT /courses

Update an existing course.

Authentication: Required (Admin only)

Query Parameters:

Parameter	Type	Required	Description
id	string	Yes	The ID of the course to update

Request Body:

{
  "title": "Updated Course Title", // Optional
  "description": "Updated description", // Optional
  "status": "PUBLISHED", // Optional: DRAFT, PUBLISHED, ARCHIVED
  "price": 39.99, // Optional
  "thumbnail": "https://example.com/new-thumbnail.jpg" // Optional
}

Response: 200 OK

{
  "id": "uuid",
  "title": "Updated Course Title",
  "description": "Updated description",
  "status": "PUBLISHED",
  "price": 39.99,
  // ... other fields
  "updated_at": "2024-01-20T16:00:00.000Z"
}

DELETE /courses

Delete a course and all associated lessons.

Authentication: Required (Admin only)

Query Parameters:

Parameter	Type	Required	Description
id	string	Yes	The ID of the course to delete

Response: 200 OK

{
  "message": "Course deleted successfully"
}

---

Lessons

Manage individual lessons within courses.

GET /lessons

List lessons or retrieve a specific lesson by ID.

Authentication: Required for individual lessons (checks enrollment and sequential unlocking)

Query Parameters:

Parameter	Type	Description
id	string	Get a specific lesson by ID (requires authentication)
course_id	string	Filter lessons by course ID
limit	number	Number of items to return (default: 100)
offset	number	Pagination offset (default: 0)

Example Request (List by Course):

curl "https://api.example.com/dev/lessons?course_id=uuid"

Response (List): 200 OK

{
  "lessons": [
    {
      "id": "uuid",
      "course_id": "uuid",
      "day": 1,
      "title": "Introduction to Mindfulness",
      "content": "<p>Welcome to day 1...</p>",
      "video_url": "https://example.com/videos/lesson-1.mp4",
      "action_items": [
        "Practice 5-minute breathing exercise",
        "Journal about your experience"
      ],
      "resources": {
        "pdf": "https://example.com/resources/day1.pdf",
        "audio": "https://example.com/audio/guided-meditation.mp3"
      },
      "order_index": 1,
      "generation_prompt": null,
      "ai_generated": false,
      "estimated_duration_minutes": 15,
      "locked": false, // Added dynamically based on user progress
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  ],
  "total": 7
}

Example Request (Single Lesson):

curl -H "Authorization: Bearer <token>" \
  "https://api.example.com/dev/lessons?id=uuid"

Response (Single): 200 OK

{
  "id": "uuid",
  "course_id": "uuid",
  "day": 1,
  "title": "Introduction to Mindfulness",
  // ... (same fields as in list)
}

Access Denied: 403 Forbidden

{
  "error": "Enrollment required",
  "details": "You must be enrolled in this course to access this lesson"
}

{
  "error": "Previous lesson incomplete",
  "details": "You must complete the previous lesson to unlock this one"
}

POST /lessons

Create a new lesson.

Authentication: Required (Admin only)

Request Body:

{
  "course_id": "uuid",
  "day": 2,
  "title": "Breathing Techniques",
  "content": "<p>Today we'll explore breathing...</p>",
  "video_url": "https://example.com/videos/lesson-2.mp4", // Optional
  "action_items": [ // Optional
    "Practice technique for 10 minutes",
    "Record your observations"
  ],
  "resources": { // Optional
    "pdf": "https://example.com/resources/day2.pdf"
  },
  "order_index": 2
}

Response: 201 Created

{
  "id": "uuid",
  "course_id": "uuid",
  "day": 2,
  "title": "Breathing Techniques",
  "content": "<p>Today we'll explore breathing...</p>",
  "video_url": "https://example.com/videos/lesson-2.mp4",
  "action_items": [
    "Practice technique for 10 minutes",
    "Record your observations"
  ],
  "resources": {
    "pdf": "https://example.com/resources/day2.pdf"
  },
  "order_index": 2,
  "ai_generated": false,
  "created_at": "2024-01-20T16:15:00.000Z",
  "updated_at": "2024-01-20T16:15:00.000Z"
}

PUT /lessons

Update an existing lesson.

Authentication: Required (Admin only)

Query Parameters:

Parameter	Type	Required	Description
id	string	Yes	The ID of the lesson to update

Request Body:

{
  "title": "Updated Lesson Title", // Optional
  "content": "<p>Updated content...</p>", // Optional
  "video_url": "https://example.com/videos/updated.mp4", // Optional
  "action_items": ["Updated action item"], // Optional
  "estimated_duration_minutes": 20 // Optional
}

Response: 200 OK

{
  "id": "uuid",
  "title": "Updated Lesson Title",
  "content": "<p>Updated content...</p>",
  // ... other fields
  "updated_at": "2024-01-20T16:30:00.000Z"
}

DELETE /lessons

Delete a lesson.

Authentication: Required (Admin only)

Query Parameters:

Parameter	Type	Required	Description
id	string	Yes	The ID of the lesson to delete

Response: 200 OK

{
  "message": "Lesson deleted successfully"
}

---

Enrollments

Manage user enrollments in courses.

GET /enrollments

Retrieve enrollments for the authenticated user or check enrollment status.

Authentication: Required

Query Parameters:

Parameter	Type	Description
id	string	Get a specific enrollment by ID
course_id	string	Filter enrollments by course ID
check	boolean	Set to true with course_id to check if user is enrolled
limit	number	Number of items to return (default: 20)
offset	number	Pagination offset (default: 0)

Example Request (List User’s Enrollments):

curl -H "Authorization: Bearer <token>" \
  "https://api.example.com/dev/enrollments"

Response (List): 200 OK

{
  "enrollments": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "course_id": "uuid",
      "enrolled_at": "2024-01-15T10:00:00.000Z",
      "completed_at": null,
      "payment_id": "pay_123456",
      "stripe_subscription_id": "sub_123456",
      "status": "ACTIVE"
    }
  ],
  "total": 3
}

Example Request (Check Enrollment):

curl -H "Authorization: Bearer <token>" \
  "https://api.example.com/dev/enrollments?course_id=uuid&check=true"

Response (Enrolled): 200 OK

{
  "enrolled": true,
  "enrollment": {
    "id": "uuid",
    "user_id": "uuid",
    "course_id": "uuid",
    "enrolled_at": "2024-01-15T10:00:00.000Z",
    "status": "ACTIVE"
  }
}

Response (Not Enrolled): 200 OK

{
  "enrolled": false,
  "enrollment": null
}

POST /enrollments

Enroll the authenticated user in a course.

Authentication: Required

Request Body:

{
  "course_id": "uuid",
  "payment_id": "pay_123456", // Optional
  "stripe_subscription_id": "sub_123456" // Optional
}

Response: 201 Created

{
  "id": "uuid",
  "user_id": "uuid",
  "course_id": "uuid",
  "enrolled_at": "2024-01-20T17:00:00.000Z",
  "completed_at": null,
  "payment_id": "pay_123456",
  "stripe_subscription_id": "sub_123456",
  "status": "ACTIVE"
}

Already Enrolled: 400 Bad Request

{
  "error": "User is already enrolled in this course"
}

PUT /enrollments

Update enrollment status (complete or cancel).

Authentication: Required

Query Parameters:

Parameter	Type	Required	Description
id	string	Yes	Enrollment ID
action	string	Yes	Action to perform: complete or cancel

Example Request (Complete):

curl -X PUT \
  -H "Authorization: Bearer <token>" \
  "https://api.example.com/dev/enrollments?id=uuid&action=complete"

Response: 200 OK

{
  "id": "uuid",
  "user_id": "uuid",
  "course_id": "uuid",
  "enrolled_at": "2024-01-15T10:00:00.000Z",
  "completed_at": "2024-01-22T14:30:00.000Z",
  "status": "COMPLETED"
}

---

Progress

Track user progress through course lessons.

GET /progress

Get progress records for the authenticated user.

Authentication: Required

Query Parameters:

Parameter	Type	Description
course_id	string	Filter progress by course ID
lesson_id	string	Filter progress by lesson ID
with_details	boolean	Include lesson details (default: false)

Example Request:

curl -H "Authorization: Bearer <token>" \
  "https://api.example.com/dev/progress?course_id=uuid&with_details=true"

Response: 200 OK

{
  "progress": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "lesson_id": "uuid",
      "completed": true,
      "completed_at": "2024-01-16T15:30:00.000Z",
      "time_spent_seconds": 900,
      "created_at": "2024-01-16T15:15:00.000Z",
      "updated_at": "2024-01-16T15:30:00.000Z",
      "lesson": { // Included when with_details=true
        "id": "uuid",
        "title": "Introduction to Mindfulness",
        "day": 1,
        "course_id": "uuid"
      }
    }
  ]
}

GET /progress/summary

Get a course completion summary for the authenticated user.

Authentication: Required

Query Parameters:

Parameter	Type	Required	Description
course_id	string	Yes	Course ID to get summary for

Example Request:

curl -H "Authorization: Bearer <token>" \
  "https://api.example.com/dev/progress/summary?course_id=uuid"

Response: 200 OK

{
  "summary": {
    "course_id": "uuid",
    "total_lessons": 7,
    "completed_lessons": 3,
    "completion_percentage": 42.86,
    "total_time_spent_seconds": 2700
  }
}

POST /progress

Create or update progress for a lesson.

Authentication: Required

Request Body:

{
  "lesson_id": "uuid",
  "completed": true, // Optional, default: false
  "time_spent_seconds": 450 // Optional
}

Response: 200 OK

{
  "id": "uuid",
  "user_id": "uuid",
  "lesson_id": "uuid",
  "completed": true,
  "completed_at": "2024-01-20T18:00:00.000Z",
  "time_spent_seconds": 450,
  "created_at": "2024-01-20T17:45:00.000Z",
  "updated_at": "2024-01-20T18:00:00.000Z"
}

DELETE /progress

Delete all progress records for a course (reset progress).

Authentication: Required

Query Parameters:

Parameter	Type	Required	Description
course_id	string	Yes	Course ID to delete progress for

Example Request:

curl -X DELETE \
  -H "Authorization: Bearer <token>" \
  "https://api.example.com/dev/progress?course_id=uuid"

Response: 200 OK

{
  "message": "Progress deleted successfully",
  "deleted_count": 3
}

---

Users

Manage users (admin only).

GET /users

List all users with optional filtering.

Authentication: Required (Admin only)

Query Parameters:

Parameter	Type	Description
id	string	Get a specific user by ID
search	string	Search by name or email
role	string	Filter by role: ADMIN, PREMIUM, FREE
profile_completed	boolean	Filter by profile completion status
limit	number	Number of items to return (default: 20, max: 100)
offset	number	Pagination offset (default: 0)

Example Request:

curl -H "Authorization: Bearer <admin-token>" \
  "https://api.example.com/dev/users?role=PREMIUM&limit=10"

Response: 200 OK

{
  "users": [
    {
      "id": "uuid",
      "cognito_sub": "cognito-user-sub",
      "email": "user@example.com",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "role": "PREMIUM",
      "avatar_url": "https://example.com/avatars/user.jpg",
      "gender": "male",
      "age_group": "25-34",
      "location_country": "USA",
      "location_city": "New York",
      "timezone": "America/New_York",
      "interests": ["mindfulness", "productivity"],
      "learning_objectives": ["reduce stress", "improve focus"],
      "preferred_learning_style": "video",
      "weekly_learning_hours": 5,
      "profile_completed": true,
      "onboarding_completed_at": "2024-01-10T12:00:00.000Z",
      "created_at": "2024-01-10T10:00:00.000Z",
      "updated_at": "2024-01-10T14:00:00.000Z"
    }
  ],
  "total": 150
}

PUT /users

Update a user’s profile or role.

Authentication: Required (Admin only for role changes, users can update their own profile)

Query Parameters:

Parameter	Type	Required	Description
id	string	Yes	The ID of the user to update

Request Body:

{
  "role": "PREMIUM", // Optional (admin only)
  "gender": "female", // Optional
  "age_group": "35-44", // Optional
  "location_country": "Canada", // Optional
  "location_city": "Toronto", // Optional
  "timezone": "America/Toronto", // Optional
  "interests": ["health", "wellness"], // Optional
  "learning_objectives": ["better sleep", "stress management"], // Optional
  "preferred_learning_style": "reading", // Optional
  "weekly_learning_hours": 3, // Optional
  "profile_completed": true // Optional
}

Response: 200 OK

{
  "id": "uuid",
  "email": "user@example.com",
  "name": "Jane Smith",
  "role": "PREMIUM",
  "gender": "female",
  "age_group": "35-44",
  // ... other updated fields
  "updated_at": "2024-01-20T18:30:00.000Z"
}

---

Analytics

Access platform and course analytics (admin only).

GET /analytics

Get platform-wide analytics and statistics.

Authentication: Required (Admin only)

Query Parameters:

Parameter	Type	Description
type	string	Analytics type: platform, course, or user-activity
start_date	string	Start date (ISO 8601 format)
end_date	string	End date (ISO 8601 format)
course_id	string	Course ID (required for type=course)
user_id	string	User ID (required for type=user-activity)
days	number	Number of days to look back (default: 30)

Example Request (Platform Stats):

curl -H "Authorization: Bearer <admin-token>" \
  "https://api.example.com/dev/analytics?type=platform&days=7"

Response (Platform): 200 OK

{
  "platform_stats": {
    "total_users": 1250,
    "new_users": 45,
    "active_users": 380,
    "total_logins": 1840,
    "unique_logins": 420,
    "total_enrollments": 3200,
    "total_completions": 780,
    "total_lessons_completed": 15600,
    "total_time_spent_seconds": 4680000,
    "total_revenue_cents": 12450000,
    "date_range": {
      "start": "2024-01-14T00:00:00.000Z",
      "end": "2024-01-20T23:59:59.000Z"
    }
  }
}

Example Request (Course Performance):

curl -H "Authorization: Bearer <admin-token>" \
  "https://api.example.com/dev/analytics?type=course&course_id=uuid&days=30"

Response (Course): 200 OK

{
  "course_stats": {
    "course_id": "uuid",
    "enrollments": 156,
    "completions": 42,
    "active_learners": 89,
    "lessons_completed": 945,
    "avg_completion_rate": 26.92,
    "avg_time_spent_seconds": 1800,
    "revenue_cents": 461244,
    "date_range": {
      "start": "2023-12-21T00:00:00.000Z",
      "end": "2024-01-20T23:59:59.000Z"
    }
  }
}

Example Request (User Activity):

curl -H "Authorization: Bearer <admin-token>" \
  "https://api.example.com/dev/analytics?type=user-activity&user_id=uuid&days=14"

Response (User Activity): 200 OK

{
  "user_activity": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "activity_type": "lesson_completed",
      "metadata": {
        "lesson_id": "uuid",
        "course_id": "uuid",
        "time_spent_seconds": 720
      },
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0...",
      "created_at": "2024-01-20T15:30:00.000Z"
    }
  ],
  "total": 42
}

---

Badges

Manage achievement badges and user badge progress.

GET /badges

List all active badges available in the system.

Authentication: None (Public)

Example Request:

curl "https://api.example.com/dev/badges"

Response: 200 OK

{
  "badges": [
    {
      "id": "uuid",
      "name": "First Course Complete",
      "description": "Complete your first course",
      "badge_type": "COURSE_COMPLETION",
      "tier": "BRONZE",
      "icon_url": "https://example.com/badges/first-course.svg",
      "criteria": {
        "courses_completed": 1
      },
      "points": 100,
      "is_active": true,
      "display_order": 1,
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  ]
}

GET /badges/progress

Get the authenticated user’s badge progress (earned badges and progress towards others).

Authentication: Required

Example Request:

curl -H "Authorization: Bearer <token>" \
  "https://api.example.com/dev/badges/progress"

Response: 200 OK

{
  "user_badges": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "badge_id": "uuid",
      "badge_name": "First Course Complete",
      "badge_description": "Complete your first course",
      "badge_type": "COURSE_COMPLETION",
      "tier": "BRONZE",
      "icon_url": "https://example.com/badges/first-course.svg",
      "points": 100,
      "earned_at": "2024-01-18T14:30:00.000Z",
      "progress_percentage": 100,
      "is_showcased": true,
      "metadata": {}
    }
  ],
  "statistics": {
    "id": "uuid",
    "user_id": "uuid",
    "total_points": 450,
    "total_badges": 3,
    "current_streak": 7,
    "longest_streak": 12,
    "last_activity_date": "2024-01-20T00:00:00.000Z",
    "courses_completed": 2,
    "lessons_completed": 28,
    "total_time_spent_seconds": 25200,
    "created_at": "2024-01-10T10:00:00.000Z",
    "updated_at": "2024-01-20T18:45:00.000Z"
  }
}

GET /statistics

Get user statistics (alternative endpoint for user stats).

Authentication: Required

Query Parameters:

Parameter	Type	Description
user_id	string	User ID (optional, defaults to authenticated user)

Example Request:

curl -H "Authorization: Bearer <token>" \
  "https://api.example.com/dev/statistics"

Response: 200 OK

{
  "statistics": {
    "id": "uuid",
    "user_id": "uuid",
    "total_points": 450,
    "total_badges": 3,
    "current_streak": 7,
    "longest_streak": 12,
    "last_activity_date": "2024-01-20T00:00:00.000Z",
    "courses_completed": 2,
    "lessons_completed": 28,
    "total_time_spent_seconds": 25200,
    "created_at": "2024-01-10T10:00:00.000Z",
    "updated_at": "2024-01-20T18:45:00.000Z"
  }
}

---

Recommendations

Get personalized course recommendations.

GET /recommendations

Get course recommendations based on user activity and preferences.

Authentication: Optional (provides better recommendations when authenticated)

Query Parameters:

Parameter	Type	Description
type	string	Recommendation type: personalized, popular, or similar
course_id	string	Source course ID (required for type=similar)
limit	number	Number of recommendations (default: 10, max: 50)

Example Request (Personalized - Requires Auth):

curl -H "Authorization: Bearer <token>" \
  "https://api.example.com/dev/recommendations?type=personalized&limit=5"

Response (Personalized): 200 OK

{
  "recommendations": [
    {
      "id": "uuid",
      "title": "Advanced Mindfulness Techniques",
      "description": "Take your mindfulness practice to the next level",
      "category_id": "uuid",
      "duration_days": 14,
      "price": 49.99,
      "thumbnail": "https://example.com/thumbnails/advanced.jpg",
      "status": "PUBLISHED",
      "reason": "Based on your completed courses"
    }
  ],
  "type": "personalized",
  "userId": "uuid"
}

Example Request (Popular - Public):

curl "https://api.example.com/dev/recommendations?type=popular&limit=5"

Response (Popular): 200 OK

{
  "recommendations": [
    {
      "id": "uuid",
      "title": "7-Day Productivity Bootcamp",
      "description": "Master productivity in one week",
      "category_id": "uuid",
      "duration_days": 7,
      "price": 29.99,
      "thumbnail": "https://example.com/thumbnails/productivity.jpg",
      "status": "PUBLISHED",
      "enrollment_count": 342
    }
  ],
  "type": "popular"
}

Example Request (Similar Courses):

curl "https://api.example.com/dev/recommendations?type=similar&course_id=uuid&limit=5"

Response (Similar): 200 OK

{
  "recommendations": [
    {
      "id": "uuid",
      "title": "Meditation for Beginners",
      "description": "Start your meditation journey",
      "category_id": "uuid",
      "duration_days": 7,
      "price": 19.99,
      "thumbnail": "https://example.com/thumbnails/meditation.jpg",
      "status": "PUBLISHED"
    }
  ],
  "type": "similar",
  "sourceCourseId": "uuid"
}

---

AI Generation

AI-powered course generation (admin only).

POST /admin/generate/course

Generate a complete course using AI (Amazon Bedrock).

Authentication: Required (Admin only)

Request Body:

{
  "title": "AI-Generated Productivity Course",
  "description": "A comprehensive productivity course",
  "category_id": "uuid",
  "duration_days": 14, // Must be 7, 14, or 21
  "difficulty_level": "intermediate", // beginner, intermediate, advanced
  "target_audience": "working professionals"
}

Response: 201 Created

{
  "job_id": "uuid",
  "status": "PENDING",
  "execution_arn": "arn:aws:states:us-east-1:...",
  "message": "Course generation started",
  "estimated_completion_time": "2024-01-20T19:15:00.000Z"
}

GET /admin/generate/status/{jobId}

Check the status of an AI generation job.

Authentication: Required (Admin only)

Path Parameters:

Parameter	Type	Required	Description
jobId	string	Yes	The job ID returned from POST /admin/generate/course

Example Request:

curl -H "Authorization: Bearer <admin-token>" \
  "https://api.example.com/dev/admin/generate/status/uuid"

Response (In Progress): 200 OK

{
  "id": "uuid",
  "admin_user_id": "uuid",
  "course_id": null,
  "status": "IN_PROGRESS",
  "input_params": {
    "title": "AI-Generated Productivity Course",
    "description": "A comprehensive productivity course",
    "category_id": "uuid",
    "duration_days": 14,
    "difficulty_level": "intermediate",
    "target_audience": "working professionals"
  },
  "progress_percentage": 45,
  "current_step": "Generating lesson 7 of 14",
  "result": null,
  "error_message": null,
  "quality_score": null,
  "model_used": "anthropic.claude-v2",
  "tokens_used": 12500,
  "estimated_cost_usd": 0.0625,
  "execution_arn": "arn:aws:states:us-east-1:...",
  "is_async": true,
  "created_at": "2024-01-20T19:00:00.000Z",
  "started_at": "2024-01-20T19:00:15.000Z",
  "completed_at": null,
  "updated_at": "2024-01-20T19:05:00.000Z"
}

Response (Completed): 200 OK

{
  "id": "uuid",
  "admin_user_id": "uuid",
  "course_id": "uuid",
  "status": "COMPLETED",
  "input_params": { /* ... */ },
  "progress_percentage": 100,
  "current_step": "Course generation complete",
  "result": {
    "course_id": "uuid",
    "lessons_created": 14,
    "total_content_length": 45000
  },
  "error_message": null,
  "quality_score": 0.92,
  "model_used": "anthropic.claude-v2",
  "tokens_used": 28750,
  "estimated_cost_usd": 0.1438,
  "execution_arn": "arn:aws:states:us-east-1:...",
  "is_async": true,
  "created_at": "2024-01-20T19:00:00.000Z",
  "started_at": "2024-01-20T19:00:15.000Z",
  "completed_at": "2024-01-20T19:12:30.000Z",
  "updated_at": "2024-01-20T19:12:30.000Z"
}

Response (Failed): 200 OK

{
  "id": "uuid",
  "status": "FAILED",
  "error_message": "AI generation failed: Rate limit exceeded",
  "progress_percentage": 35,
  "current_step": "Generating lesson 5 of 14",
  // ... other fields
}

POST /admin/generate/lesson/{lessonId}/regenerate

Regenerate a specific lesson using AI.

Authentication: Required (Admin only)

Path Parameters:

Parameter	Type	Required	Description
lessonId	string	Yes	The ID of the lesson to regenerate

Request Body:

{
  "prompt": "Make it more engaging and add practical examples", // Optional
  "preserve_structure": true // Optional, default: true
}

Response: 200 OK

{
  "job_id": "uuid",
  "lesson_id": "uuid",
  "status": "PENDING",
  "message": "Lesson regeneration started"
}

---

Data Models

Enums

UserRole

enum UserRole {
  ADMIN = 'ADMIN',
  PREMIUM = 'PREMIUM',
  FREE = 'FREE'
}

CourseStatus

enum CourseStatus {
  DRAFT = 'DRAFT',
  PUBLISHED = 'PUBLISHED',
  ARCHIVED = 'ARCHIVED'
}

EnrollmentStatus

enum EnrollmentStatus {
  ACTIVE = 'ACTIVE',
  COMPLETED = 'COMPLETED',
  CANCELLED = 'CANCELLED'
}

BadgeType

enum BadgeType {
  COURSE_COMPLETION = 'COURSE_COMPLETION',
  STREAK = 'STREAK',
  SPEED = 'SPEED',
  MILESTONE = 'MILESTONE',
  SPECIAL = 'SPECIAL'
}

BadgeTier

enum BadgeTier {
  BRONZE = 'BRONZE',
  SILVER = 'SILVER',
  GOLD = 'GOLD',
  PLATINUM = 'PLATINUM'
}

---

TypeScript Types

Core Entities

Category

interface Category {
  id: string;
  name: string;
  slug: string;
  description?: string;
  icon_url?: string;
  created_at: Date;
}

Course

interface Course {
  id: string;
  title: string;
  description: string;
  category_id: string;
  duration_days: 7 | 14 | 21;
  price: number;
  thumbnail?: string;
  status: CourseStatus;
  metadata: Record<string, any>;
  ai_generated?: boolean;
  generation_job_id?: string;
  intro_video_url?: string;
  intro_video_status?: string;
  what_you_will_learn?: string[];
  requirements?: string[];
  instructor?: {
    name: string;
    title: string;
    avatar: string;
  };
  created_at: Date;
  updated_at: Date;
}

Lesson

interface Lesson {
  id: string;
  course_id: string;
  day: number;
  title: string;
  content: string;
  video_url?: string;
  action_items: string[];
  resources: Record<string, any>;
  order_index: number;
  generation_prompt?: string;
  ai_generated?: boolean;
  estimated_duration_minutes?: number;
  created_at: Date;
  updated_at: Date;
}

Enrollment

interface Enrollment {
  id: string;
  user_id: string;
  course_id: string;
  enrolled_at: Date;
  completed_at?: Date;
  payment_id?: string;
  stripe_subscription_id?: string;
  status: EnrollmentStatus;
}

Progress

interface Progress {
  id: string;
  user_id: string;
  lesson_id: string;
  completed: boolean;
  completed_at?: Date;
  time_spent_seconds: number;
  created_at: Date;
  updated_at: Date;
}

User

interface User {
  id: string;
  cognito_sub: string;
  email: string;
  name: string;
  first_name?: string;
  last_name?: string;
  role: UserRole;
  avatar_url?: string;
  gender?: 'male' | 'female' | 'non-binary' | 'prefer-not-to-say' | 'other';
  age_group?: '18-24' | '25-34' | '35-44' | '45-54' | '55-64' | '65+';
  location_country?: string;
  location_city?: string;
  timezone?: string;
  interests?: string[];
  learning_objectives?: string[];
  preferred_learning_style?: 'visual' | 'reading' | 'interactive' | 'video';
  weekly_learning_hours?: number;
  profile_completed: boolean;
  onboarding_completed_at?: Date;
  created_at: Date;
  updated_at: Date;
}

Badge

interface Badge {
  id: string;
  name: string;
  description: string;
  badge_type: BadgeType;
  tier: BadgeTier;
  icon_url?: string;
  criteria: Record<string, any>;
  points: number;
  is_active: boolean;
  display_order: number;
  created_at: Date;
  updated_at: Date;
}

UserBadge

interface UserBadge {
  id: string;
  user_id: string;
  badge_id: string;
  earned_at: Date;
  progress_percentage: number;
  is_showcased: boolean;
  metadata: Record<string, any>;
}

UserStatistics

interface UserStatistics {
  id: string;
  user_id: string;
  total_points: number;
  total_badges: number;
  current_streak: number;
  longest_streak: number;
  last_activity_date?: Date;
  courses_completed: number;
  lessons_completed: number;
  total_time_spent_seconds: number;
  created_at: Date;
  updated_at: Date;
}

DTOs (Data Transfer Objects)

CreateCourseDTO

interface CreateCourseDTO {
  title: string;
  description: string;
  category_id: string;
  duration_days: 7 | 14 | 21;
  price: number;
  thumbnail?: string;
  metadata?: Record<string, any>;
}

UpdateCourseDTO

interface UpdateCourseDTO {
  title?: string;
  description?: string;
  category_id?: string;
  duration_days?: 7 | 14 | 21;
  price?: number;
  thumbnail?: string;
  status?: CourseStatus;
  metadata?: Record<string, any>;
}

CreateLessonDTO

interface CreateLessonDTO {
  course_id: string;
  day: number;
  title: string;
  content: string;
  video_url?: string;
  action_items?: string[];
  resources?: Record<string, any>;
  order_index: number;
}

CreateEnrollmentDTO

interface CreateEnrollmentDTO {
  course_id: string;
  payment_id?: string;
  stripe_subscription_id?: string;
}

CreateProgressDTO

interface CreateProgressDTO {
  lesson_id: string;
  completed?: boolean;
  time_spent_seconds?: number;
}

CourseProgressSummary

interface CourseProgressSummary {
  course_id: string;
  total_lessons: number;
  completed_lessons: number;
  completion_percentage: number;
  total_time_spent_seconds: number;
}

---

Rate Limiting

API Gateway enforces the following rate limits:

• Burst Limit: 5,000 requests
• Rate Limit: 10,000 requests per second

When rate limits are exceeded, the API returns:

Response: 429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "details": "Too many requests. Please try again later."
}

---

Versioning

The current API version is v1 (implicit in the /dev stage).

Future versions will be introduced as new stages (e.g., /v2) to maintain backward compatibility.

---

Support

For API support and questions:

• Documentation: https://github.com/cloudnnj/momentum/tree/main/docs
• Issues: https://github.com/cloudnnj/momentum/issues
• Email: support@momentum.cloudnnj.com

---

Last Updated: 2024-12-07 API Version: 1.0 Platform: AWS API Gateway + Lambda (Node.js 20.x, TypeScript)