Lessons API: Adaptive Sessions, Answers, and Grading

A Lesson is a timed, scored practice session drawn from a pool of typed quiz questions. Sealearn’s adaptive engine analyses each user’s weekly activity, current streak, and recent scores before every session and dynamically chooses the number of questions, the difficulty mix, and the XP multiplier. This means no two sessions feel identical, and the challenge scales automatically with the learner’s performance.

Lesson types

Type	Description
`lesson`	Standard lesson with a hand-curated or AI-supplemented question pool.
`checkpoint`	End-of-unit evaluation with a harder question mix.
`review`	Spaced-repetition replay triggered when a previous completion is due for review.
`ai_generated`	Questions are generated fresh by the AI each time the lesson is started, using the subject and lesson context.

Lesson model fields

unit

ObjectId

required

Reference to the parent Unit document.

name

string

required

Display name of the lesson.

description

string

Optional description. Maximum 500 characters.

order

number

required

Position of the lesson within its unit. Combined with unit, must be unique.

type

string

One of lesson, checkpoint, review, ai_generated. Defaults to lesson.

xpReward

number

Base XP awarded for completing the lesson. Defaults to 10. The adaptive engine multiplies this before crediting the user.

gemsReward

number

Gems awarded on completion. Defaults to 0. Perfect scores (100%) add an extra 5 gems on top.

questionCount

number

Base number of questions per session (3–20). The adaptive engine uses this as a starting point, then scales the actual count between 5 and 18. Defaults to 5.

timeLimit

number | null

Optional session time limit in seconds. null means no limit. Defaults to null.

difficulty

string

Base difficulty: easy, medium, or hard. The adaptive engine may shift this up or down by one level depending on the user’s activity score.

theory

object

Optional mini-reading shown before the exercises.

Show theory fields

title

string

Theory section title.

content

string

Markdown-formatted theory text.

imageUrl

string

Optional image URL.

aiTopicHint

string

Specific topic hint passed to the AI when generating questions. Defaults to the lesson name.

isActive

boolean

Soft-delete flag. Defaults to true.

Adaptive engine

When a user starts a lesson, getAdaptiveConfig computes an activity score (0–100) from three signals:

Signal	Weight	How it is measured
Lessons completed in the last 7 days	40%	Up to 14 lessons/week maps linearly to 100.
Current streak	30%	Up to 30 days maps linearly to 100.
Average score of last 10 completions	30%	Raw percentage (0–100). Defaults to 50 when no history exists.

The resulting activityScore drives three adaptive parameters:

Activity score	`questionCount`	`difficulty`	`easyRatio` / `hardRatio`
0–30 (low activity)	5–8	Escalated one level above base	20% easy / 50% hard
31–60 (moderate)	9–13	Base difficulty unchanged	33% easy / 33% hard
61–100 (high activity)	14–18	Lowered one level below base	50% easy / 20% hard

questionCount is always clamped between 5 and 18.

Endpoints

GET /api/lessons/review

Returns up to 10 completed lessons that are due for spaced-repetition review today (i.e. their spacedRepetition.nextReviewDate is on or before the current date). Authentication: Bearer token required.

curl https://api.sealearn.app/api/lessons/review \
  -H "Authorization: Bearer <token>"

boolean

true on success.

data

object[]

Array of review items.

Show Review item

lesson

object

Lesson document with name, xpReward, and unit fields populated.

nextReviewDate

string

ISO date of the scheduled review.

repetitions

number

Number of times the SM-2 algorithm has processed this lesson for this user.

Example response

{
  "ok": true,
  "data": [
    {
      "lesson": {
        "_id": "665f3c4d5e6f7a8b9c0f1a2b",
        "name": "Adding and Subtracting",
        "xpReward": 10,
        "unit": "665f2b3c4d5e6f7a8b9c0e1f"
      },
      "nextReviewDate": "2025-06-07T00:00:00.000Z",
      "repetitions": 3
    }
  ]
}

GET /api/lessons/:id

Returns a single active lesson populated with its parent unit and the unit’s parent subject (name, color, icon). Also includes the requesting user’s current status, best score, and completion count for that lesson. Authentication: Bearer token required. Path parameters

string

required

MongoDB ObjectId of the lesson.

curl https://api.sealearn.app/api/lessons/665f3c4d5e6f7a8b9c0f1a2b \
  -H "Authorization: Bearer <token>"

boolean

true on success.

data

object

Show Lesson detail

_id

string

Lesson ObjectId.

name

string

Lesson name.

unit

object

Populated unit with nested subject (name, color, icon).

status

string

User’s current status: locked, available, in_progress, or completed.

bestScore

number

Best session score (0–100).

completions

number

Times the user has completed this lesson.

POST /api/lessons/:id/start

Triggers the adaptive engine, selects (or generates) questions, records a new in-progress session, and returns everything the client needs to render the lesson UI: the question list, AI-generated theory slides, and the adaptive configuration used. For lesson type, if the question pool is smaller than the adaptive questionCount, the API automatically calls the AI to generate the missing questions and saves them for future use before proceeding. Authentication: Bearer token required. The user must have at least 1 heart remaining. Path parameters

string

required

MongoDB ObjectId of the lesson to start.

curl -X POST https://api.sealearn.app/api/lessons/665f3c4d5e6f7a8b9c0f1a2b/start \
  -H "Authorization: Bearer <token>"

boolean

true on success.

data

object

Show Session start data

lesson

object

Lean lesson summary: _id, name, xpReward, timeLimit, type.

questions

object[]

Sanitized question array. Correct answers, correctBoolean, and isCorrect fields are stripped. See question type notes below for the exact shape of each type.

theorySlides

object[]

AI-generated theory slides to display before the questions. Empty array if generation fails.

totalQuestions

number

Number of questions in this session.

hearts

number

The user’s remaining hearts at session start.

adaptive

object

The adaptive configuration used for this session.

Show adaptive object

questionCount

number

Number of questions selected for this session (5–18).

difficulty

string

Effective difficulty after adaptive scaling: easy, medium, or hard.

activityScore

number

Composite activity score (0–100) used to compute the configuration.

Example response

{
  "ok": true,
  "data": {
    "lesson": {
      "_id": "665f3c4d5e6f7a8b9c0f1a2b",
      "name": "Adding and Subtracting",
      "xpReward": 10,
      "timeLimit": null,
      "type": "lesson"
    },
    "questions": [ /* ... */ ],
    "theorySlides": [ /* ... */ ],
    "totalQuestions": 9,
    "hearts": 5,
    "adaptive": {
      "questionCount": 9,
      "difficulty": "easy",
      "activityScore": 45
    }
  }
}

For multiple_choice questions the options array is shuffled randomly before being sent. For order_items the array is exposed as shuffledItems (correct order removed). For match_pairs the pairs are split into leftItems and rightItems, each independently shuffled. For sentence_builder the wordBank is shuffled.

If the user’s hearts.current is 0, the endpoint returns 403 Forbidden with the message “No tenés corazones para iniciar una lección”. Hearts refill automatically 30 minutes after reaching zero, or can be refilled immediately with gems via POST /api/progress/refill-hearts.

Question answer formats

Each question object in the questions array has a type field. Use the correct answer shape when calling POST /api/lessons/:id/answer.

multiple_choice — select one option by ID

The options array is delivered as [{ _id, text }, ...] (shuffled). Submit the _id of the option you believe is correct.

{
  "questionId": "665fabc...",
  "answer": "665fopt1..."
}

true_false — submit a boolean

Submit a JavaScript boolean (true or false). String values "true" and "false" are also accepted and coerced automatically.

{
  "questionId": "665fabc...",
  "answer": true
}

fill_blank — submit a string

Submit the word or phrase that fills the blank. Matching is case-insensitive and accent-insensitive — “ecuation” and “Ecuación” are treated as equivalent. If the strict comparison fails, the AI is called as a fallback evaluator.

{
  "questionId": "665fabc...",
  "answer": "photosynthesis"
}

order_items — submit items in the correct sequence

The question delivers a shuffledItems array of strings. Submit those same strings in the order you believe is correct.

{
  "questionId": "665fabc...",
  "answer": ["First step", "Second step", "Third step"]
}

match_pairs — submit left-to-right pair mappings

The question delivers leftItems and rightItems, each as [{ _id, text }] arrays (shuffled independently). Both arrays are derived from the same underlying pair documents, so a left item and its matching right item share the same _id. Submit an array of { leftId, rightId } objects where you set leftId to a left item’s _id and rightId to the _id of the right item you believe it matches. A submission is correct when every leftId equals its corresponding rightId (i.e. they originate from the same pair).

{
  "questionId": "665fabc...",
  "answer": [
    { "leftId": "665fpair1", "rightId": "665fpair1" },
    { "leftId": "665fpair2", "rightId": "665fpair2" }
  ]
}

sentence_builder — reconstruct a sentence from a word bank

The question delivers a shuffled wordBank array of strings. Submit the words in the correct order as an array of strings.

{
  "questionId": "665fabc...",
  "answer": ["The", "mitochondria", "is", "the", "powerhouse"]
}

free_text — open-ended answer evaluated by AI

Submit any string. The AI evaluates it against the question’s evaluationCriteria and maxScore. The response shape differs from other types — see the POST /api/lessons/:id/answer response section.

{
  "questionId": "665fabc...",
  "answer": "Photosynthesis converts light energy into chemical energy stored in glucose."
}

typing — exact text reproduction

Submit the string exactly as it must appear. Comparison is strict (case-sensitive, whitespace-sensitive). A wrong answer costs a heart.

{
  "questionId": "665fabc...",
  "answer": "print(\"Hello, world!\")"
}

code_python — Python code evaluated against test cases

Code execution happens on the client (via a Pyodide sandbox or similar). Submit the evaluation result — not the raw code. A wrong answer costs a heart.

{
  "questionId": "665fabc...",
  "answer": {
    "passed": true,
    "passedCount": 3,
    "totalCount": 3,
    "code": "def add(a, b):\n    return a + b"
  }
}

POST /api/lessons/:id/answer

Submits one answer and returns whether it was correct, the explanation, and the XP earned for that question. An incorrect answer deducts one heart for every question type except free_text, which is AI-evaluated and never penalises hearts. typing and code_python handle heart deduction inside their own response branch but follow the same rule. Authentication: Bearer token required. Path parameters

string

required

MongoDB ObjectId of the lesson the session belongs to.

Request body

questionId

string

required

ObjectId of the question being answered.

answer

any

required

The answer value. See the question type accordion above for the correct shape per type.

hintUsed

boolean

If true, XP earned for a correct answer is halved (xpValue * 0.5).

typingStats

object

Optional typing performance metrics (WPM, accuracy, etc.) for typing questions. Stored alongside the attempt record.

curl -X POST https://api.sealearn.app/api/lessons/665f3c4d5e6f7a8b9c0f1a2b/answer \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "questionId": "665fabc123def456",
    "answer": "665fopt1abc",
    "hintUsed": false
  }'

Standard response (all types except free_text)

boolean

true on success.

data

object

Show Answer result

isCorrect

boolean

Whether the submitted answer was correct.

correctAnswer

any

The correct answer value (type-dependent).

explanation

string

Post-answer explanation text from the question.

heartsRemaining

number | null

null if the answer was correct. The user’s updated heart count if the answer was wrong and a heart was deducted.

xpEarned

number

XP credited for this answer. 0 if incorrect. Halved if hintUsed was true.

free_text response

boolean

true on success.

data

object

Show AI evaluation result

isCorrect

boolean

Whether the AI approved the response.

score

number

Numeric score assigned by the AI (0 to maxScore).

feedback

string

AI-generated overall feedback.

strengths

string[]

Aspects of the answer the AI praised.

improvements

string[]

Suggested improvements from the AI.

fullEvaluation

object

Complete AI evaluation object.

code_python response

boolean

true on success.

data

object

Show Code evaluation result

isCorrect

boolean

Whether all test cases passed.

passedCount

number

Number of test cases that passed.

totalCount

number

Total number of test cases.

explanation

string

Question explanation text.

heartsRemaining

number | null

Updated heart count if a heart was lost.

xpEarned

number

XP credited for a fully passing submission.

POST /api/lessons/:id/complete

Marks the current in-progress session as completed, calculates the final score, awards adaptive XP and gems, updates the user’s streak, adds XP to the weekly league, unlocks the next lesson if eligibility criteria are met, and checks for new achievement unlocks. Authentication: Bearer token required. An active in-progress session must exist for this lesson. Path parameters

string

required

MongoDB ObjectId of the lesson to complete.

curl -X POST https://api.sealearn.app/api/lessons/665f3c4d5e6f7a8b9c0f1a2b/complete \
  -H "Authorization: Bearer <token>"

boolean

true on success.

data

object

Show Completion result

score

number

Session score as a percentage (0–100), calculated as correct / total * 100.

isPerfect

boolean

true if score === 100. Perfect sessions earn 1.5× the base XP plus an extra 5 gems.

xpEarned

number

Total XP credited to the user, after adaptive difficulty and quantity multipliers.

leveledUp

boolean

true if the user crossed a level threshold after earning this XP.

newLevel

number | null

The new level number if leveledUp is true; otherwise null.

newStreak

number

The user’s current streak in days after this activity.

newAchievements

object[]

Array of Achievement documents unlocked by this completion (may be empty).

hearts

number

User’s remaining heart count.

totalXP

number

User’s cumulative XP total across all lessons.

gems

number

User’s current gem count after rewards.

adaptive

object

Echo of the session’s adaptive config: questionsAnswered, difficulty, activityScore.

The next lesson in the unit unlocks when the user has completed the current lesson at least 4 times. Completion is counted per unique successful call to this endpoint.

POST /api/lessons/:id/abandon

Abandons an in-progress session. The lesson’s status is reset to available and the current session attempts are cleared. No XP is awarded and no hearts are penalised. Authentication: Bearer token required. Path parameters

string

required

MongoDB ObjectId of the lesson to abandon.

curl -X POST https://api.sealearn.app/api/lessons/665f3c4d5e6f7a8b9c0f1a2b/abandon \
  -H "Authorization: Bearer <token>"

Example response

{ "ok": true, "message": "Lección abandonada" }

Authentication

Learning

Social & Competitive

Shop & Admin

Lessons API: Adaptive Sessions, Answers, and Grading

Lesson types

Lesson model fields

Adaptive engine

Endpoints

GET /api/lessons/review

GET /api/lessons/:id

POST /api/lessons/:id/start

Question answer formats

POST /api/lessons/:id/answer

POST /api/lessons/:id/complete

POST /api/lessons/:id/abandon

Build docs developers (and LLMs) love

Authentication

Learning

Social & Competitive

Shop & Admin

Documentation Index

​Lesson types

​Lesson model fields

​Adaptive engine

​Endpoints

​GET /api/lessons/review

​GET /api/lessons/:id

​POST /api/lessons/:id/start

​Question answer formats

​POST /api/lessons/:id/answer

​POST /api/lessons/:id/complete

​POST /api/lessons/:id/abandon

Build docs developers (and LLMs) love

Lesson types

Lesson model fields

Adaptive engine

Endpoints

GET /api/lessons/review

GET /api/lessons/:id

POST /api/lessons/:id/start

Question answer formats

POST /api/lessons/:id/answer

POST /api/lessons/:id/complete

POST /api/lessons/:id/abandon