Friends API: Connections, Profiles, and Leaderboards

The Friends API powers Sealearn’s social layer. Users can discover other learners by username, send and manage friend requests, inspect anyone’s public profile, and see how their friends stack up in a weekly XP leaderboard. Every endpoint in this group requires a valid JWT — attach the token as a Bearer value in the Authorization header of every request.

All routes are mounted under /api/friends and protected by the verificarToken middleware. Requests without a valid token receive 401 Unauthorized.

The Friendship Model

A Friendship document is created whenever one user sends a friend request to another. Its status field tracks the lifecycle of the relationship.

Field	Type	Description
`_id`	ObjectId	Unique document ID — used when accepting or rejecting a request.
`requester`	ObjectId → User	The user who sent the request.
`recipient`	ObjectId → User	The user who received the request.
`status`	`"pending"` \| `"accepted"` \| `"rejected"`	Current state of the friendship.
`createdAt`	Date	Timestamp of when the request was first sent (auto-managed by Mongoose `timestamps`).
`updatedAt`	Date	Timestamp of the last status change.

A compound unique index on { requester, recipient } prevents duplicate requests between the same pair. If a previously rejected friendship exists and a new request is sent, the server re-uses the existing document and sets its status back to "pending".

Endpoints

GET /api/friends

Returns the list of accepted friends for the authenticated user. Both sides of each Friendship document are resolved, so it doesn’t matter who originally sent the request. Response fields per friend object:

boolean

required

true on success.

data

array

required

Array of populated User objects.

Show User object fields

_id

string

MongoDB ObjectId of the friend.

username

string

Unique username handle.

displayName

string

Display name shown in the UI.

number

Total XP accumulated.

level

number

Current level derived from XP.

avatar

string

Avatar image URL.

hearts

number

Current heart count (lives).

gems

number

Gem currency balance.

streak

number

Current daily streak in days.

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

{
  "ok": true,
  "data": [
    {
      "_id": "664a1f2e8b3c2a001e4d8e10",
      "username": "marisolita",
      "displayName": "Marisol",
      "xp": 3420,
      "level": 12,
      "avatar": "https://res.cloudinary.com/sealearn/image/upload/avatars/marisolita.webp",
      "hearts": 5,
      "gems": 80,
      "streak": 7
    }
  ]
}

GET /api/friends/requests

Returns all incoming friend requests that are still in "pending" status for the authenticated user. Only requests where the authenticated user is the recipient are returned.

boolean

required

true on success.

data

array

required

Array of Friendship documents with the requester field populated.

Show Friendship object fields

_id

string

Friendship document ID — pass this to the accept/reject endpoints.

status

string

Always "pending" in this response.

requester

object

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

createdAt

string

ISO 8601 timestamp of the request.

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

{
  "ok": true,
  "data": [
    {
      "_id": "664b3e1c9f0e4b002f5a9d33",
      "status": "pending",
      "requester": {
        "_id": "664a0011ab12cd003e7f1122",
        "username": "codigoninja",
        "displayName": "Código Ninja",
        "avatar": "https://res.cloudinary.com/sealearn/image/upload/avatars/codigoninja.webp",
        "level": 8,
        "xp": 1950
      },
      "createdAt": "2024-05-20T14:32:00.000Z"
    }
  ]
}

GET /api/friends/search

Searches active users by username or displayName. Results are case-insensitive and limited to 8 matches. The query string must be at least 2 characters; shorter values return an empty array immediately. Each result includes a friendStatus field so the client can immediately render the correct call-to-action (add, pending, already friends, etc.).

string

required

Search term (minimum 2 characters). Matched against both username and displayName using a case-insensitive regex.

boolean

required

true on success.

data

array

required

Up to 8 matching User objects.

Show User search result fields

_id

string

User’s ObjectId.

username

string

Unique username handle.

displayName

string

Display name.

avatar

string

Avatar URL.

level

number

Current level.

number

Total XP.

friendStatus

string | null

"pending", "accepted", "rejected", or null if no relationship exists.

friendshipId

string | null

ID of the Friendship document if one exists, otherwise null.

isRequester

boolean

Whether the authenticated user sent the existing request.

curl -X GET "https://api.sealearn.app/api/friends/search?q=mari" \
  -H "Authorization: Bearer <token>"

{
  "ok": true,
  "data": [
    {
      "_id": "664a1f2e8b3c2a001e4d8e10",
      "username": "marisolita",
      "displayName": "Marisol",
      "avatar": "https://res.cloudinary.com/sealearn/image/upload/avatars/marisolita.webp",
      "level": 12,
      "xp": 3420,
      "friendStatus": null,
      "friendshipId": null,
      "isRequester": false
    }
  ]
}

GET /api/friends/leaderboard

Returns a weekly XP leaderboard that includes the authenticated user and all of their accepted friends. Ranking is based on xpEarned accumulated in the user’s current league room since the week started (Monday 00:00 UTC). Users not yet assigned to a league room for the current week show 0 XP.

boolean

required

true on success.

data

array

required

Sorted array of leaderboard entries, highest XP first.

Show Leaderboard entry fields

rank

number

1-based position in the leaderboard.

xpEarned

number

XP earned during the current week.

user

object

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

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

{
  "ok": true,
  "data": [
    {
      "rank": 1,
      "xpEarned": 520,
      "user": {
        "_id": "664a1f2e8b3c2a001e4d8e10",
        "username": "marisolita",
        "displayName": "Marisol",
        "avatar": "https://res.cloudinary.com/sealearn/image/upload/avatars/marisolita.webp",
        "level": 12
      }
    },
    {
      "rank": 2,
      "xpEarned": 310,
      "user": {
        "_id": "664a0011ab12cd003e7f1122",
        "username": "codigoninja",
        "displayName": "Código Ninja",
        "avatar": "https://res.cloudinary.com/sealearn/image/upload/avatars/codigoninja.webp",
        "level": 8
      }
    }
  ]
}

GET /api/friends/profile/:username

Returns the public profile of any user, identified by their username. The response also includes the friendship status between the viewer and the profile owner, enabling the client to show the correct social action button. Achievements, active cosmetic frame, and active background are fully populated.

username

string

required

The target user’s username (case-sensitive, exact match).

boolean

required

true on success.

data

object

required

Public profile object.

Show Profile fields

username

string

Unique username handle.

displayName

string

Displayed name.

avatar

string

Avatar image URL.

banner

string

Profile banner image URL.

level

number

Current level.

number

Total XP accumulated.

league

string

Current league tier key (e.g. "gold").

streak

number

Current daily learning streak in days.

gems

number

Gem currency balance.

achievements

array

Array of populated Achievement documents.

activeFrame

object | null

Populated cosmetic frame item, or null if none equipped.

activeBackground

object | null

Populated cosmetic background item, or null if none equipped.

friendStatus

string | null

"pending", "accepted", "rejected", or null.

friendshipId

string | null

Friendship document ID if a relationship exists.

isRequester

boolean

Whether the authenticated user is the one who sent the request.

curl -X GET https://api.sealearn.app/api/friends/profile/marisolita \
  -H "Authorization: Bearer <token>"

{
  "ok": true,
  "data": {
    "username": "marisolita",
    "displayName": "Marisol",
    "avatar": "https://res.cloudinary.com/sealearn/image/upload/avatars/marisolita.webp",
    "banner": "https://res.cloudinary.com/sealearn/image/upload/banners/ocean.webp",
    "level": 12,
    "xp": 3420,
    "league": "gold",
    "streak": 7,
    "gems": 80,
    "achievements": [],
    "activeFrame": null,
    "activeBackground": null,
    "friendStatus": null,
    "friendshipId": null,
    "isRequester": false
  }
}

POST /api/friends/request

Sends a friend request to another user identified by their username. If the target previously rejected a request from the authenticated user, the existing document is reused and its status is reset to "pending".

username

string

required

The username of the user to befriend. The lookup is case-insensitive.

boolean

required

true on success.

message

string

required

Human-readable confirmation or error detail.

data

object

The newly created (or reactivated) Friendship document.

Error cases:

400 — username not provided, attempting to add yourself, already friends, or request already pending.
404 — Username not found.

curl -X POST https://api.sealearn.app/api/friends/request \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "username": "marisolita" }'

{
  "ok": true,
  "message": "Solicitud enviada a @marisolita",
  "data": {
    "_id": "664b3e1c9f0e4b002f5a9d33",
    "requester": "664a0011ab12cd003e7f1122",
    "recipient": "664a1f2e8b3c2a001e4d8e10",
    "status": "pending",
    "createdAt": "2024-05-20T14:32:00.000Z"
  }
}

PUT /api/friends/request/:id/accept

Accepts a pending incoming friend request. The :id parameter is the _id of the Friendship document, which can be found in the response from GET /api/friends/requests. Only the recipient of the request can call this endpoint.

string

required

The _id of the Friendship document to accept.

boolean

required

true on success.

message

string

required

"Solicitud aceptada".

curl -X PUT https://api.sealearn.app/api/friends/request/664b3e1c9f0e4b002f5a9d33/accept \
  -H "Authorization: Bearer <token>"

{ "ok": true, "message": "Solicitud aceptada" }

PUT /api/friends/request/:id/reject

Rejects a pending incoming friend request. Sets the friendship status to "rejected". Only the recipient can call this endpoint.

string

required

The _id of the Friendship document to reject.

boolean

required

true on success.

message

string

required

"Solicitud rechazada".

curl -X PUT https://api.sealearn.app/api/friends/request/664b3e1c9f0e4b002f5a9d33/reject \
  -H "Authorization: Bearer <token>"

{ "ok": true, "message": "Solicitud rechazada" }

DELETE /api/friends/:userId

Removes an accepted friendship between the authenticated user and the target. Both directions of the Friendship document are checked, so either party can remove the other.

userId

string

required

The MongoDB _id of the friend to remove.

boolean

required

true on success.

message

string

required

"Amigo eliminado".

curl -X DELETE https://api.sealearn.app/api/friends/664a1f2e8b3c2a001e4d8e10 \
  -H "Authorization: Bearer <token>"

{ "ok": true, "message": "Amigo eliminado" }

Authentication

Learning

Social & Competitive

Shop & Admin

Friends API: Connections, Profiles, and Leaderboards

The Friendship Model

Endpoints

GET /api/friends

GET /api/friends/requests

GET /api/friends/search

GET /api/friends/leaderboard

GET /api/friends/profile/:username

POST /api/friends/request

PUT /api/friends/request/:id/accept

PUT /api/friends/request/:id/reject

DELETE /api/friends/:userId

Build docs developers (and LLMs) love

Authentication

Learning

Social & Competitive

Shop & Admin

Documentation Index

​The Friendship Model

​Endpoints

​GET /api/friends

​GET /api/friends/requests

​GET /api/friends/search

​GET /api/friends/leaderboard

​GET /api/friends/profile/:username

​POST /api/friends/request

​PUT /api/friends/request/:id/accept

​PUT /api/friends/request/:id/reject

​DELETE /api/friends/:userId

Build docs developers (and LLMs) love

The Friendship Model

Endpoints

GET /api/friends

GET /api/friends/requests

GET /api/friends/search

GET /api/friends/leaderboard

GET /api/friends/profile/:username

POST /api/friends/request

PUT /api/friends/request/:id/accept

PUT /api/friends/request/:id/reject

DELETE /api/friends/:userId