Skip to main content

​
Submit Quiz Answers

Authentication Required: Any authenticated user with access to the lesson
POST /api/lessons/:lessonId/answer
curl -X POST https://api.sunschool.xyz/api/lessons/550e8400-e29b-41d4-a716-446655440000/answer \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "answers": [1, 0, 2, 1],
    "doubleOrLoss": false,
    "doubleQuestionIndices": [0, 2]
  }'
​
lessonId
string
required
Lesson UUID
​
answers
array
required
Array of selected answer indices (0-based) for each question
​
doubleOrLoss
boolean
Legacy flag: apply double-or-loss to all questions (default: false)
​
doubleQuestionIndices
array
Array of question indices (0-based) where double-or-loss is enabled

​
Authorization

  • LEARNER: Can submit for their own lessons
  • PARENT: Can submit for their children’s lessons
  • ADMIN: Can submit for any lesson
When a parent submits answers, points and achievements are attributed to the child learner, not the parent.

​
Double-or-Loss Mode

When double-or-loss is enabled for a question:
  • Correct answer: Award 2 points instead of 1
  • Wrong answer: Deduct 1 point from balance

​
Response

​
lesson
object
Updated lesson object with status “DONE” and final score
​
score
number
Percentage score (0-100)
​
correctCount
number
Number of correct answers
​
totalQuestions
number
Total number of questions in the quiz
​
wrongCount
number
Number of incorrect answers
​
pointsAwarded
number
Total points earned from correct answers
​
pointsDeducted
number
Total points deducted from double-or-loss wrong answers
​
doubleOrLoss
boolean
Whether any double-or-loss was used
​
doubleQuestionIndices
array
Array of question indices where double-or-loss was applied
​
newBalance
number
Updated points balance after this quiz
​
newAchievements
array
Array of newly earned achievements
Response Example
{
  "lesson": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "learnerId": 3,
    "status": "DONE",
    "score": 75,
    "subject": "Math"
  },
  "score": 75,
  "correctCount": 3,
  "totalQuestions": 4,
  "wrongCount": 1,
  "pointsAwarded": 5,
  "pointsDeducted": 1,
  "doubleOrLoss": true,
  "doubleQuestionIndices": [0, 2],
  "newBalance": 24,
  "newAchievements": [
    {
      "type": "FIRST_PERFECT",
      "title": "Perfect Score!",
      "description": "You got 100% on your first quiz!"
    }
  ]
}
Submitting answers automatically:
  • Updates the lesson status to “DONE”
  • Awards/deducts points based on performance
  • Updates concept mastery tracking
  • Stores question hashes for deduplication
  • Checks for and awards new achievements
  • Pre-generates the next lesson in the background

​
Error Codes

  • 400 - Answers must be an array
  • 400 - Lesson is not active
  • 400 - Invalid lesson specification
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Lesson not found

​
Understanding Quiz Scoring

​
Base Points

  • Each correct answer: 1 point
  • Each wrong answer: 0 points

​
Double-or-Loss Multiplier

When enabled for specific questions: 
{
  "basePoints": 1,
  "doubleOrLossMultiplier": 2,
  "pointsAwarded": 2
}

​
Percentage Score Calculation

const score = Math.round((correctCount / totalQuestions) * 100);
The percentage score is independent of the double-or-loss points system.