Leagues API: Competitive Tiers and Weekly Rankings

Sealearn’s league system divides learners into competitive rooms of up to 30 users. Each Monday a new week begins, XP counters reset, and every user is placed into a room matching their current tier. At the end of the week the top 10 performers in each room are promoted to the next tier, while the bottom 10 are demoted. There are nine tiers in total, ranging from Bronze up to Heroic. The endpoints below let clients display a user’s current standing and — for administrators — trigger the processing cycle on demand.

All routes are mounted under /api/leagues and require a valid JWT. The POST /process route additionally requires the isAdmin middleware; calling it without an admin account returns 403 Forbidden.

The LeagueRoom Model

A LeagueRoom document represents a single competitive room for one week. A new set of rooms is created automatically at the start of each week when users first request their league data.

Field	Type	Description
`_id`	ObjectId	Unique document ID.
`league`	string	Tier key: one of the 9 valid league slugs.
`weekStart`	Date	The Monday 00:00:00 UTC that marks the start of this room’s week.
`roomNumber`	number	Sequential number distinguishing multiple rooms at the same tier in the same week.
`members`	array	Embedded member subdocuments (see below).
`processed`	boolean	`true` after the weekly promotion/demotion cycle has run for this room.
`createdAt`	Date	Auto-managed Mongoose timestamp.

Member subdocument fields:

Field	Type	Description
`user`	ObjectId → User	Reference to the member’s User document.
`xpEarned`	number	XP accumulated by this member during the current week (default `0`).
`promoted`	boolean	Set to `true` when the member is promoted at week’s end.
`demoted`	boolean	Set to `true` when the member is demoted at week’s end.
`joinedAt`	Date	When the member was added to this room.

League Tiers

Sealearn has nine tiers arranged in ascending order of prestige. Moving up requires finishing in the top 10 of your room; finishing in the bottom 10 drops you to the previous tier (Bronze users cannot be demoted further).

Order	Key	Display Name	Icon	Color
0	`bronze`	Bronce	🥉	`#cd7f32`
1	`silver`	Plata	🥈	`#c0c0c0`
2	`gold`	Oro	🥇	`#ffd700`
3	`sapphire`	Zafiro	💙	`#0f52ba`
4	`emerald`	Esmeralda	💚	`#50c878`
5	`diamond`	Diamante	💎	`#b9f2ff`
6	`master`	Maestro	🔮	`#9b59b6`
7	`champion`	Campeón	👑	`#f1c40f`
8	`heroic`	Heroico	⚔️	`#ff4444`

Endpoints

GET /api/leagues/me

Returns the authenticated user’s current league room, including a sorted member list and contextual rank information. If the user has not yet been assigned to a room for the current week, the server creates one automatically before responding. The members array is sorted by xpEarned descending so the client can render the leaderboard directly. The response also includes the promotion and demotion zone boundaries, and the number of days remaining until the next weekly reset.

boolean

required

true on success.

data

object

required

Show Response data fields

league

string

Tier key of the current room (e.g. "gold").

leagueName

string

Localised display name (e.g. "Oro").

leagueIcon

string

Emoji icon for the tier (e.g. "🥇").

leagueColor

string

Hex color for UI theming (e.g. "#ffd700").

roomNumber

number

Sequential room number within this tier and week.

members

array

Sorted member list (highest XP first).

Show Member entry fields

rank

number

1-based position in this room.

user

object

Populated User with username, displayName, avatar, level, xp, and league.

xpEarned

number

XP earned this week.

promoted

boolean

Whether this member was promoted last cycle.

demoted

boolean

Whether this member was demoted last cycle.

isMe

boolean

true for the authenticated user’s own entry.

myRank

number | null

The authenticated user’s current rank, or null if not found.

myXP

number

The authenticated user’s XP earned this week.

total

number

Total number of members in the room.

promoteZone

number

Number of top spots that earn promotion (always 10).

demoteZone

number

total - 10: the rank boundary below which members are demoted.

daysLeft

number

Days remaining until the next Monday reset.

weekStart

string

ISO 8601 date of the Monday that started this week’s rooms.

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

{
  "ok": true,
  "data": {
    "league": "gold",
    "leagueName": "Oro",
    "leagueIcon": "🥇",
    "leagueColor": "#ffd700",
    "roomNumber": 3,
    "members": [
      {
        "rank": 1,
        "user": {
          "_id": "664a1f2e8b3c2a001e4d8e10",
          "username": "marisolita",
          "displayName": "Marisol",
          "avatar": "https://res.cloudinary.com/sealearn/image/upload/avatars/marisolita.webp",
          "level": 12,
          "xp": 3420,
          "league": "gold"
        },
        "xpEarned": 520,
        "promoted": false,
        "demoted": false,
        "isMe": false
      },
      {
        "rank": 2,
        "user": {
          "_id": "664a0011ab12cd003e7f1122",
          "username": "codigoninja",
          "displayName": "Código Ninja",
          "avatar": "https://res.cloudinary.com/sealearn/image/upload/avatars/codigoninja.webp",
          "level": 8,
          "xp": 1950,
          "league": "gold"
        },
        "xpEarned": 310,
        "promoted": false,
        "demoted": false,
        "isMe": true
      }
    ],
    "myRank": 2,
    "myXP": 310,
    "total": 28,
    "promoteZone": 10,
    "demoteZone": 18,
    "daysLeft": 4,
    "weekStart": "2024-05-20T00:00:00.000Z"
  }
}

GET /api/leagues/info

Returns metadata for all nine league tiers, along with the authenticated user’s current tier key. Use this endpoint to render a tier progression screen or highlight the user’s position in the full ladder.

boolean

required

true on success.

data

object

required

Show Response data fields

currentLeague

string

The authenticated user’s current tier key (e.g. "gold"). Defaults to "bronze" if unset.

leagues

array

Array of all 9 tier config objects, in ascending order (Bronze → Heroic).

Show Tier config fields

key

string

Tier slug used throughout the API (e.g. "sapphire").

name

string

Localised display name (e.g. "Zafiro").

icon

string

Emoji icon.

color

string

Hex color string.

order

number

0-based numeric order (0 = Bronze, 8 = Heroic).

curl -X GET https://api.sealearn.app/api/leagues/info \
  -H "Authorization: Bearer <token>"

{
  "ok": true,
  "data": {
    "currentLeague": "gold",
    "leagues": [
      { "key": "bronze",   "name": "Bronce",     "icon": "🥉", "color": "#cd7f32", "order": 0 },
      { "key": "silver",   "name": "Plata",      "icon": "🥈", "color": "#c0c0c0", "order": 1 },
      { "key": "gold",     "name": "Oro",        "icon": "🥇", "color": "#ffd700", "order": 2 },
      { "key": "sapphire", "name": "Zafiro",     "icon": "💙", "color": "#0f52ba", "order": 3 },
      { "key": "emerald",  "name": "Esmeralda",  "icon": "💚", "color": "#50c878", "order": 4 },
      { "key": "diamond",  "name": "Diamante",   "icon": "💎", "color": "#b9f2ff", "order": 5 },
      { "key": "master",   "name": "Maestro",    "icon": "🔮", "color": "#9b59b6", "order": 6 },
      { "key": "champion", "name": "Campeón",    "icon": "👑", "color": "#f1c40f", "order": 7 },
      { "key": "heroic",   "name": "Heroico",    "icon": "⚔️", "color": "#ff4444", "order": 8 }
    ]
  }
}

POST /api/leagues/process

Admin only. Forces an immediate run of the weekly league processing cycle. In normal operation this cycle runs automatically on the server’s scheduled cron job every Monday. This endpoint is intended for testing and manual intervention. The cycle iterates over every unprocessed LeagueRoom for the current week: the top 10 members (by xpEarned) are promoted to the next tier and the bottom 10 are demoted to the previous tier. Bronze members cannot be demoted. Heroic members cannot be promoted further. After processing, the room’s processed flag is set to true so it is not processed again.

Calling this endpoint while the week is still in progress will promote and demote users based on their XP at the time of the call. For production use, this is intended to be called only on Monday when the week has concluded.

boolean

required

true on success.

message

string

required

Summary of how many rooms were processed (e.g. "Procesadas 47 salas").

curl -X POST https://api.sealearn.app/api/leagues/process \
  -H "Authorization: Bearer <token>"

{ "ok": true, "message": "Procesadas 47 salas" }

Authentication

Learning

Social & Competitive

Shop & Admin

Leagues API: Competitive Tiers and Weekly Rankings

The LeagueRoom Model

League Tiers

Endpoints

GET /api/leagues/me

GET /api/leagues/info

POST /api/leagues/process

Build docs developers (and LLMs) love

Authentication

Learning

Social & Competitive

Shop & Admin

Documentation Index

​The LeagueRoom Model

​League Tiers

​Endpoints

​GET /api/leagues/me

​GET /api/leagues/info

​POST /api/leagues/process

Build docs developers (and LLMs) love

The LeagueRoom Model

League Tiers

Endpoints

GET /api/leagues/me

GET /api/leagues/info

POST /api/leagues/process