Progress API: Track XP, Achievements, and Daily Goals

The Progress API gives learners and front-end clients a full picture of where a user stands in their Sealearn journey: accumulated XP, current level, active streak, hearts, gem balance, daily goal targets, completed lessons, and unlocked achievements. It also exposes the weekly league leaderboard — a gamified ranking that resets every Monday and groups users by their league tier.

UserProgress model

A UserProgress document is created automatically the first time a user interacts with a lesson. One document exists per user-lesson pair.

user

ObjectId

required

Reference to the User document.

lesson

ObjectId

required

Reference to the Lesson document.

status

string

Current state of the lesson for this user: locked, available, in_progress, or completed. Defaults to locked.

completions

number

How many times the user has successfully completed this lesson. Used to determine when the next lesson in the unit unlocks (threshold: 4 completions).

bestScore

number

Highest session score achieved (0–100, percentage of correct answers). Defaults to 0.

lastScore

number

Score of the most recent completed session.

totalXPEarned

number

Cumulative XP earned across all sessions on this lesson.

lastCompletedAt

date | null

Timestamp of the most recent successful completion.

currentSession

object

Tracks the in-progress session. Cleared when the session completes or is abandoned.

Show currentSession fields

startedAt

date | null

When the session was started.

heartsAtStart

number

Heart count when the session began. Defaults to 5.

attempts

object[]

Array of individual answer attempts recorded during the session.

Show Attempt object

question

ObjectId

The question that was answered.

isCorrect

boolean

Whether the answer was correct.

timeSpent

number

Seconds spent on this question.

hintsUsed

number

Number of hints used for this question.

spacedRepetition

object

SM-2 spaced-repetition state for this lesson.

Show spacedRepetition fields

nextReviewDate

date | null

The computed date when this lesson should next be reviewed.

interval

number

Current interval in days until the next review. Starts at 1.

easeFactor

number

SM-2 ease factor (minimum 1.3). Starts at 2.5.

repetitions

number

Number of times the SM-2 algorithm has been applied successfully.

seenQuestions

object[]

Record of which questions from this lesson the user has been shown, and how many times. Used by the question-refresh service to vary the question pool.

Show seenQuestion entry

question

ObjectId

Reference to the Question document.

timesShown

number

How many sessions this question has appeared in.

Endpoints

GET /api/progress/me

Returns a comprehensive progress dashboard for the authenticated user, including XP and level metrics, streak details, weekly statistics, and the count of achievements unlocked. Authentication: Bearer token required.

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

boolean

true on success.

data

object

Show Progress dashboard

user

object

Core user stats.

Show user object

username

string

The user’s login handle.

avatar

string

Avatar URL or identifier.

number

Total XP accumulated across all lessons.

level

number

Current level derived from total XP.

xpForNextLevel

number

XP required to reach the next level.

xpProgress

number

XP earned within the current level (i.e. progress toward the next level threshold).

gems

number

Current gem balance. Gems are spent to refill hearts (50 gems per refill).

hearts

object

Heart state object with current (0–5) and lastRefill timestamp fields.

dailyGoal

number

User’s chosen daily XP target: one of 10, 20, 30, or 50.

streak

object

Streak data from the dedicated Streak document.

Show streak object

current

number

Current consecutive-day streak.

longest

number

All-time longest streak.

isAtRisk

boolean

true if the user has not yet completed a lesson today and risks losing their streak.

freezesAvailable

number

Number of streak-freeze tokens the user holds.

history

object[]

Activity records for the last 7 days.

stats

object

Aggregated learning statistics.

Show stats object

completedLessons

number

Total lessons the user has ever completed.

reviewsDue

number

Number of completed lessons whose spaced-repetition review date is today or earlier.

weeklyXP

number

XP earned from lessons completed since the start of the current week (Sunday midnight).

achievementsCount

number

Total number of achievements unlocked.

Example response

{
  "ok": true,
  "data": {
    "user": {
      "username": "ocean_learner",
      "avatar": "🐠",
      "xp": 840,
      "level": 5,
      "xpForNextLevel": 1000,
      "xpProgress": 340,
      "gems": 120,
      "hearts": { "current": 4, "lastRefill": "2025-06-07T10:00:00.000Z" },
      "dailyGoal": 20
    },
    "streak": {
      "current": 7,
      "longest": 14,
      "isAtRisk": false,
      "freezesAvailable": 1,
      "history": [ /* last 7 days */ ]
    },
    "stats": {
      "completedLessons": 32,
      "reviewsDue": 3,
      "weeklyXP": 180,
      "achievementsCount": 8
    }
  }
}

GET /api/progress/leaderboard

Returns the weekly XP ranking for the authenticated user’s league room. League rooms are scoped to a single calendar week (Monday to Sunday) and a league tier (e.g. bronze, silver, gold). If the user has no room for the current week, one is assigned automatically before returning the results. Authentication: Bearer token required.

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

boolean

true on success.

data

object[]

Ranked array of member entries for the user’s current league room, sorted by xpEarned descending.

Show Leaderboard entry

rank

number

1-based position in the leaderboard.

xpEarned

number

XP earned by this member during the current week.

isMe

boolean

true for the entry that belongs to the requesting user.

user

object

Populated user snapshot.

Show user snapshot

username

string

displayName

string

Display name.

avatar

string

Avatar URL or identifier.

number

All-time total XP.

level

number

Current level.

league

string

League tier of the user (e.g. bronze, silver, gold).

Example response

{
  "ok": true,
  "data": [
    {
      "rank": 1,
      "xpEarned": 340,
      "isMe": false,
      "user": {
        "username": "reef_runner",
        "displayName": "Reef Runner",
        "avatar": "🐡",
        "xp": 3200,
        "level": 12,
        "league": "silver"
      }
    },
    {
      "rank": 2,
      "xpEarned": 180,
      "isMe": true,
      "user": {
        "username": "ocean_learner",
        "displayName": "Ocean Learner",
        "avatar": "🐠",
        "xp": 840,
        "level": 5,
        "league": "bronze"
      }
    }
  ]
}

League rooms reset every Monday. XP earned in a previous week does not carry over to the next room’s ranking, though it still counts toward the user’s all-time total XP.

GET /api/progress/achievements

Returns every active achievement in the system, each annotated with whether the authenticated user has unlocked it. Unlocked achievements are identified by comparing the user’s achievements array against the full catalogue. Authentication: Bearer token required.

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

boolean

true on success.

data

object[]

Array of all active achievement documents.

Show Achievement object

_id

string

Achievement ObjectId.

name

string

Achievement display name (e.g. “First Steps”).

description

string

Description of how to earn this achievement.

icon

string

Emoji or icon string.

unlocked

boolean

true if the requesting user has earned this achievement.

Example response

{
  "ok": true,
  "data": [
    {
      "_id": "665fab1234567890",
      "name": "First Steps",
      "description": "Complete your first lesson.",
      "icon": "👣",
      "unlocked": true
    },
    {
      "_id": "665fab1234567891",
      "name": "On Fire",
      "description": "Maintain a 7-day streak.",
      "icon": "🔥",
      "unlocked": false
    }
  ]
}

PUT /api/progress/daily-goal

Sets the user’s daily XP target. The goal is displayed in the app as a progress bar the user aims to fill each day. The value must be one of the four predefined tiers. Authentication: Bearer token required. Request body

dailyGoal

number

required

Target XP per day. Must be exactly one of: 10, 20, 30, 50.

curl -X PUT https://api.sealearn.app/api/progress/daily-goal \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "dailyGoal": 30 }'

boolean

true on success.

data

object

Show Updated goal

dailyGoal

number

The newly saved daily goal value.

Example response

{ "ok": true, "data": { "dailyGoal": 30 } }

Passing any value other than 10, 20, 30, or 50 returns 400 Bad Request with the message "dailyGoal debe ser uno de: 10, 20, 30, 50".

POST /api/progress/refill-hearts

Spends 50 gems to instantly restore the user’s hearts to the maximum of 5. This is only permitted when the user’s current heart count is below 5 and they have sufficient gems. Authentication: Bearer token required.

curl -X POST https://api.sealearn.app/api/progress/refill-hearts \
  -H "Authorization: Bearer <token>"

boolean

true on success.

data

object

Show Refill result

hearts

number

Updated heart count (will be 5 on success).

gems

number

Updated gem balance after the 50-gem cost is deducted.

Example response

{ "ok": true, "data": { "hearts": 5, "gems": 70 } }

Error cases

Condition	HTTP status	Message
Hearts are already at 5	`400`	`"Ya tenés 5 vidas"`
Fewer than 50 gems available	`400`	`"Necesitás 50 gemas. Tenés {n}"`

Hearts also refill automatically. If the user’s hearts hit zero, the server checks on the next lesson completion whether 30 minutes have elapsed since hearts.lastRefill; if so, hearts are restored for free. The manual refill via this endpoint bypasses the timer entirely.

Authentication

Learning

Social & Competitive

Shop & Admin

Progress API: Track XP, Achievements, and Daily Goals

UserProgress model

Endpoints

GET /api/progress/me

GET /api/progress/leaderboard

GET /api/progress/achievements

PUT /api/progress/daily-goal

POST /api/progress/refill-hearts

Build docs developers (and LLMs) love

Authentication

Learning

Social & Competitive

Shop & Admin

Documentation Index

​UserProgress model

​Endpoints

​GET /api/progress/me

​GET /api/progress/leaderboard

​GET /api/progress/achievements

​PUT /api/progress/daily-goal

​POST /api/progress/refill-hearts

Build docs developers (and LLMs) love

UserProgress model

Endpoints

GET /api/progress/me

GET /api/progress/leaderboard

GET /api/progress/achievements

PUT /api/progress/daily-goal

POST /api/progress/refill-hearts