# LMS API Collection Documentation

This document provides detailed information about the Learning Management System (LMS) API endpoints available in the Postman collection.

## Base URL

All API requests use the base URL defined in the Postman environment variable:
```
{{base_url}} - Default: http://localhost:8000
```

## Authentication

Most endpoints require authentication using a Bearer token. After logging in, the token should be stored in the Postman environment variable:
```
{{token}} - Your JWT authentication token
```

## Available Endpoints

### Authentication

#### Register
- **Method**: POST
- **URL**: {{base_url}}/api/register
- **Description**: Register a new user account
- **Headers**:
  - Content-Type: application/json
- **Body**:
```json
{
    "name": "John Doe",
    "email": "john@example.com",
    "password": "password123",
    "role": "student"
}
```

#### Login
- **Method**: POST
- **URL**: {{base_url}}/api/login
- **Description**: Authenticate user and get access token
- **Headers**:
  - Content-Type: application/json
- **Body**:
```json
{
    "email": "user@example.com",
    "password": "password123"
}
```
- **Response**: Contains JWT token to be used for authenticated requests

#### Logout
- **Method**: POST
- **URL**: {{base_url}}/api/logout
- **Description**: Invalidate the current user's token
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get Profile
- **Method**: GET
- **URL**: {{base_url}}/api/profile
- **Description**: Get the current user's profile information
- **Headers**:
  - Authorization: Bearer {{token}}

#### Update Profile
- **Method**: PUT
- **URL**: {{base_url}}/api/profile
- **Description**: Update the current user's profile information
- **Headers**:
  - Authorization: Bearer {{token}}
  - Content-Type: application/json
- **Body**:
```json
{
    "name": "Updated Name",
    "email": "updated@example.com"
}
```

### Quizzes

#### List All Quizzes
- **Method**: GET
- **URL**: {{base_url}}/api/v1/quizzes
- **Description**: Get a list of all available quizzes
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get Quiz Details
- **Method**: GET
- **URL**: {{base_url}}/api/v1/quizzes/{quiz_id}
- **Description**: Get detailed information about a specific quiz
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get Quiz Questions
- **Method**: GET
- **URL**: {{base_url}}/api/v1/quizzes/{quiz_id}/questions
- **Description**: Get all questions for a specific quiz
- **Headers**:
  - Authorization: Bearer {{token}}

#### Start Quiz
- **Method**: POST
- **URL**: {{base_url}}/api/v1/quizzes/{quiz_id}/start
- **Description**: Start a new quiz attempt
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get Specific Question
- **Method**: GET
- **URL**: {{base_url}}/api/v1/quizzes/{quiz_id}/questions/{question_id}
- **Description**: Get details of a specific question in a quiz
- **Headers**:
  - Authorization: Bearer {{token}}

#### Submit Answer
- **Method**: POST
- **URL**: {{base_url}}/api/v1/quizzes/{quiz_id}/questions/{question_id}/answer
- **Description**: Submit an answer for a quiz question
- **Headers**:
  - Authorization: Bearer {{token}}
  - Content-Type: application/json
- **Body**:
```json
{
    "answer_id": 123
}
```

#### Track Question Time
- **Method**: POST
- **URL**: {{base_url}}/api/v1/quizzes/{quiz_id}/questions/{question_id}/track-time
- **Description**: Track time spent on a question
- **Headers**:
  - Authorization: Bearer {{token}}
  - Content-Type: application/json
- **Body**:
```json
{
    "time_spent": 45
}
```

#### Mark Question as Difficult
- **Method**: POST
- **URL**: {{base_url}}/api/v1/quizzes/{quiz_id}/questions/{question_id}/mark-difficult
- **Description**: Mark a question as difficult for later review
- **Headers**:
  - Authorization: Bearer {{token}}

#### Report Question
- **Method**: POST
- **URL**: {{base_url}}/api/v1/quizzes/{quiz_id}/questions/{question_id}/report
- **Description**: Report an issue with a question
- **Headers**:
  - Authorization: Bearer {{token}}
  - Content-Type: application/json
- **Body**:
```json
{
    "reason": "Incorrect information",
    "details": "The question contains factually incorrect information."
}
```

#### Get Quiz Progress
- **Method**: GET
- **URL**: {{base_url}}/api/v1/quizzes/{quiz_id}/progress
- **Description**: Get the current progress of an ongoing quiz
- **Headers**:
  - Authorization: Bearer {{token}}

#### Finish Quiz
- **Method**: POST
- **URL**: {{base_url}}/api/v1/quizzes/{quiz_id}/finish
- **Description**: Complete a quiz attempt
- **Headers**:
  - Authorization: Bearer {{token}}

### Rankings

#### Get Quiz Rankings
- **Method**: GET
- **URL**: {{base_url}}/api/v1/quizzes/{quiz_id}/rankings
- **Description**: Get leaderboard rankings for a specific quiz
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get User Ranking for Quiz
- **Method**: GET
- **URL**: {{base_url}}/api/v1/quizzes/{quiz_id}/my-ranking
- **Description**: Get the current user's ranking for a specific quiz
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get Global Leaderboard
- **Method**: GET
- **URL**: {{base_url}}/api/v1/rankings/global
- **Description**: Get the global leaderboard across all quizzes
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get Subcategory Averages
- **Method**: GET
- **URL**: {{base_url}}/api/v1/rankings/subcategory-averages
- **Description**: Get average scores by subcategory
- **Headers**:
  - Authorization: Bearer {{token}}

### User-Specific

#### Store Acquisition Source
- **Method**: POST
- **URL**: {{base_url}}/api/v1/user/acquisition-source
- **Description**: Store information about how the user found the platform
- **Headers**:
  - Authorization: Bearer {{token}}
  - Content-Type: application/json
- **Body**:
```json
{
    "source": "social_media",
    "details": "Facebook ad"
}
```

#### Get Acquisition Sources
- **Method**: GET
- **URL**: {{base_url}}/api/v1/user/acquisition-sources
- **Description**: Get list of acquisition sources
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get Difficult Questions
- **Method**: GET
- **URL**: {{base_url}}/api/v1/user/difficult-questions
- **Description**: Get questions marked as difficult by the user
- **Headers**:
  - Authorization: Bearer {{token}}

### Performance Analytics

#### Get Performance Stats
- **Method**: GET
- **URL**: {{base_url}}/api/v1/user/performance
- **Description**: Get overall performance statistics for the user
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get Category Performance
- **Method**: GET
- **URL**: {{base_url}}/api/v1/user/performance/{category_id}
- **Description**: Get performance statistics for a specific category
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get Weak Areas
- **Method**: GET
- **URL**: {{base_url}}/api/v1/user/weak-areas
- **Description**: Get analysis of user's weak areas
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get Improvement Stats
- **Method**: GET
- **URL**: {{base_url}}/api/v1/user/improvement
- **Description**: Get statistics showing user's improvement over time
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get Time Analytics
- **Method**: GET
- **URL**: {{base_url}}/api/v1/user/time-analytics
- **Description**: Get analytics about time spent on quizzes and questions
- **Headers**:
  - Authorization: Bearer {{token}}

### Practice Mode

#### Get Main Categories
- **Method**: GET
- **URL**: {{base_url}}/api/v1/user/practice/main-categories
- **Description**: Get list of main practice categories
- **Headers**:
  - Authorization: Bearer {{token}}

#### Start Main Category Practice
- **Method**: POST
- **URL**: {{base_url}}/api/v1/user/practice/main-category/{main_category_id}
- **Description**: Start a practice session for a main category
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get Subcategories
- **Method**: GET
- **URL**: {{base_url}}/api/v1/user/practice/main-category/{main_category_id}/subcategories
- **Description**: Get subcategories for a main category
- **Headers**:
  - Authorization: Bearer {{token}}

#### Start Subcategory Practice
- **Method**: POST
- **URL**: {{base_url}}/api/v1/user/practice/subcategory/{subcategory_id}
- **Description**: Start a practice session for a subcategory
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get Practice History
- **Method**: GET
- **URL**: {{base_url}}/api/v1/user/practice/history
- **Description**: Get history of practice sessions
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get Practice Questions
- **Method**: GET
- **URL**: {{base_url}}/api/v1/user/practice/{practice_id}/questions
- **Description**: Get questions for a practice session
- **Headers**:
  - Authorization: Bearer {{token}}

#### Submit Practice Answer
- **Method**: POST
- **URL**: {{base_url}}/api/v1/user/practice/{practice_id}/questions/{question_id}/answer
- **Description**: Submit an answer for a practice question
- **Headers**:
  - Authorization: Bearer {{token}}
  - Content-Type: application/json
- **Body**:
```json
{
    "answer_id": 123
}
```

#### Finish Practice
- **Method**: POST
- **URL**: {{base_url}}/api/v1/user/practice/{practice_id}/finish
- **Description**: Complete a practice session
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get Practice Results
- **Method**: GET
- **URL**: {{base_url}}/api/v1/user/practice/{practice_id}/results
- **Description**: Get results of a completed practice session
- **Headers**:
  - Authorization: Bearer {{token}}

### Gamification

#### Get User Persona
- **Method**: GET
- **URL**: {{base_url}}/api/v1/user/gamification/persona
- **Description**: Get the user's gamification persona
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get Recent Activities
- **Method**: GET
- **URL**: {{base_url}}/api/v1/user/gamification/activities
- **Description**: Get recent gamification activities
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get Avatar Classes
- **Method**: GET
- **URL**: {{base_url}}/api/v1/user/gamification/avatar-classes
- **Description**: Get available avatar classes
- **Headers**:
  - Authorization: Bearer {{token}}

#### Select Avatar Class
- **Method**: POST
- **URL**: {{base_url}}/api/v1/user/gamification/select-avatar-class
- **Description**: Select an avatar class for the user
- **Headers**:
  - Authorization: Bearer {{token}}
  - Content-Type: application/json
- **Body**:
```json
{
    "avatar_class_id": 3
}
```

### Learning Resources

#### List Live Classes
- **Method**: GET
- **URL**: {{base_url}}/api/v1/live-class
- **Description**: Get a list of available live classes
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get Live Class Details
- **Method**: GET
- **URL**: {{base_url}}/api/v1/live-class/{live_class_id}
- **Description**: Get detailed information about a specific live class
- **Headers**:
  - Authorization: Bearer {{token}}

#### List Videos
- **Method**: GET
- **URL**: {{base_url}}/api/v1/video
- **Description**: Get a list of available videos
- **Headers**:
  - Authorization: Bearer {{token}}

#### Get Video Details
- **Method**: GET
- **URL**: {{base_url}}/api/v1/video/{video_id}
- **Description**: Get detailed information about a specific video
- **Headers**:
  - Authorization: Bearer {{token}}

## Environment Variables

The Postman collection uses the following environment variables:

1. `base_url` - The base URL for the API (default: http://localhost:8000)
2. `token` - The JWT authentication token received after login

## Importing the Collection

1. Open Postman
2. Click on "Import" in the top left
3. Select the LMS.postman_collection.json file
4. Create a new environment and set the `base_url` variable
5. After logging in, update the `token` variable with the received JWT token