Skip to main content

​
Get Active Lesson

Authentication Required: Any authenticated user
GET /api/lessons/active
curl -X GET https://api.sunschool.xyz/api/lessons/active \
  -H "Authorization: Bearer {token}"
​
learnerId
string
Learner ID to get active lesson for (defaults to authenticated user)
Returns the currently active lesson for the learner, or null if none exists.

​
Response

Response Example
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "learnerId": 3,
  "moduleId": "custom-1705320600000",
  "status": "ACTIVE",
  "subject": "Math",
  "category": "STEM",
  "difficulty": "beginner",
  "score": null,
  "spec": {
    "topic": "Addition",
    "learningObjectives": ["Understand basic addition"],
    "questions": [...]
  },
  "imagePaths": [],
  "createdAt": "2024-01-15T10:30:00.000Z"
}

​
Error Codes

  • 401 - Unauthorized
  • 500 - Failed to fetch active lesson

​
Create Custom Lesson

Authentication Required: Any authenticated user
POST /api/lessons/create
curl -X POST https://api.sunschool.xyz/api/lessons/create \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Multiplication",
    "gradeLevel": 5,
    "learnerId": "3",
    "subject": "Math",
    "category": "STEM",
    "difficulty": "beginner"
  }'
​
gradeLevel
number
required
Grade level for the lesson (K-12)
​
learnerId
string
required
ID of the learner this lesson is for
​
topic
string
Lesson topic (can be empty for random topic)
​
subject
string
Subject area (e.g., “Math”, “Science”)
​
category
string
Subject category
​
difficulty
string
Difficulty level: beginner, intermediate, or advanced

​
Authorization

  • LEARNER: Can only create lessons for themselves
  • PARENT: Can create lessons for their children
  • ADMIN: Can create lessons for any learner
Creating a new lesson automatically retires any existing ACTIVE lesson for that learner. Lesson images are generated in the background after the lesson is created.

​
Response

​
id
string
Lesson UUID
​
learnerId
number
Learner user ID
​
moduleId
string
Module identifier
​
status
string
Lesson status (ACTIVE, DONE, or QUEUED)
​
subject
string
Subject area
​
category
string
Subject category
​
difficulty
string
Difficulty level
​
spec
object
Response Example
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "learnerId": 3,
  "moduleId": "custom-1705320600000",
  "status": "ACTIVE",
  "subject": "Math",
  "category": "STEM",
  "difficulty": "beginner",
  "spec": {
    "topic": "Multiplication",
    "learningObjectives": [
      "Understand multiplication as repeated addition",
      "Solve basic multiplication problems"
    ],
    "questions": [
      {
        "question": "What is 3 × 4?",
        "choices": ["7", "12", "10", "15"],
        "correctIndex": 1,
        "explanation": "3 × 4 means adding 3 four times: 3+3+3+3 = 12"
      }
    ]
  },
  "imagePaths": [],
  "createdAt": "2024-01-15T10:30:00.000Z"
}

​
Error Codes

  • 400 - Missing required fields: gradeLevel, learnerId
  • 403 - Forbidden (insufficient permissions)
  • 404 - Learner profile not found
  • 503 - Lesson generation failed after multiple attempts
  • 500 - Failed to generate lesson content

​
Get Lesson by ID

Authentication Required: Any authenticated user with access to the lesson
GET /api/lessons/:lessonId
curl -X GET https://api.sunschool.xyz/api/lessons/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer {token}"
​
lessonId
string
required
Lesson UUID

​
Authorization

  • ADMIN: Can access any lesson
  • LEARNER: Can access their own lessons
  • PARENT: Can access their children’s lessons

​
Response

Returns the complete lesson object (same structure as Create Lesson response).

​
Error Codes

  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Lesson not found

​
Get Lesson History

Authentication Required: Any authenticated user
GET /api/lessons
curl -X GET https://api.sunschool.xyz/api/lessons?learnerId=3&limit=20 \
  -H "Authorization: Bearer {token}"
​
learnerId
string
required
Learner ID to get lesson history for (required for PARENT/ADMIN, defaults to authenticated user for LEARNER)
​
limit
number
Maximum number of lessons to return (default: 10)

​
Authorization

  • LEARNER: Can only access their own history
  • PARENT: Can access their children’s history with learnerId query param
  • ADMIN: Can access any learner’s history

​
Response

Response Example
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "learnerId": 3,
    "status": "DONE",
    "subject": "Math",
    "difficulty": "beginner",
    "score": 85,
    "createdAt": "2024-01-15T10:30:00.000Z"
  },
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "learnerId": 3,
    "status": "DONE",
    "subject": "Science",
    "difficulty": "beginner",
    "score": 92,
    "createdAt": "2024-01-14T09:15:00.000Z"
  }
]

​
Error Codes

  • 400 - learnerId is required
  • 401 - Unauthorized
  • 403 - Forbidden