Lessons

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}"

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"
  }'

number

required

Grade level for the lesson (K-12)

string

required

ID of the learner this lesson is for

string

Lesson topic (can be empty for random topic)

string

Subject area (e.g., “Math”, “Science”)

string

Subject category

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

string

Lesson UUID

number

Learner user ID

string

Module identifier

string

Lesson status (ACTIVE, DONE, or QUEUED)

string

Subject area

string

Subject category

string

Difficulty level

object

Show properties

string

Lesson topic

array

Array of learning objectives

array

Array of quiz questions

array

Generated images (populated after background processing)

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}"

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}"

string

required

Learner ID to get lesson history for (required for PARENT/ADMIN, defaults to authenticated user for LEARNER)

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

Authentication

Learners & Lessons

Gamification

Analytics

Get Active Lesson

Response

Error Codes

Create Custom Lesson

Authorization

Response

Error Codes

Get Lesson by ID

Authorization

Response

Error Codes

Get Lesson History

Authorization

Response

Error Codes

​Get Active Lesson

​Response

​Error Codes

​Create Custom Lesson

​Authorization

​Response

​Error Codes

​Get Lesson by ID

​Authorization

​Response

​Error Codes

​Get Lesson History

​Authorization

​Response

​Error Codes

Get Active Lesson

Response

Error Codes

Create Custom Lesson

Authorization

Response

Error Codes

Get Lesson by ID

Authorization

Response

Error Codes

Get Lesson History

Authorization

Response

Error Codes