Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DerBasilisk/SEA-ServicioEvaluaconAsistida/llms.txt

Use this file to discover all available pages before exploring further.

Subjects are the top-level learning categories in Sealearn — think “Mathematics”, “History”, or “Python Programming”. Each subject owns an ordered collection of Units, and each unit contains the individual Lessons a learner progresses through. Every authenticated user can browse and read subjects; write operations (create, update, delete) are restricted to administrators.

​
Data models

​
Subject

​
name
string
required
Display name of the subject. Must be unique across the platform. No enforced character limit in the schema.
​
slug
string
URL-safe identifier auto-generated from name on save (lowercase, diacritics stripped, spaces replaced with hyphens). Used as the lookup key in GET /api/subjects/:slug.
​
description
string
required
Short description of what the subject covers. Maximum 300 characters.
​
icon
string
Emoji or icon string displayed in the UI alongside the subject name. Defaults to 📚.
​
color
string
Hex color string used for the subject’s theme card. Defaults to #4F46E5.
​
order
number
Integer sort position used when listing subjects. Lower values appear first. Defaults to 0.
​
isActive
boolean
Soft-delete flag. Only subjects with isActive: true are returned to learners. Defaults to true. Setting this to false via DELETE /api/subjects/:id hides the subject without destroying its data.
​
aiPromptContext
string
Optional free-text prompt context injected into AI question generation calls for this subject. Helps the model stay on topic. Defaults to an empty string.
​
units
Unit[]
Virtual array of Unit documents that reference this subject. Populated on demand — not stored directly on the subject document.

​
Unit

​
name
string
required
Display name of the unit (e.g. “Linear Equations”, “World War II”).
​
description
string
Brief description of the unit’s content. Maximum 500 characters.
​
icon
string
Emoji or icon string. Defaults to 📖.
​
order
number
required
Position of the unit within its parent subject’s map. Combined with subject, this value must be unique — no two units in the same subject can share an order number.
​
requiredXP
number
Minimum XP the user must have earned in this subject before the unit unlocks. Defaults to 0.
​
subject
ObjectId
Reference to the parent Subject document.
​
isActive
boolean
Soft-delete flag. Defaults to true.
​
lessons
Lesson[]
Virtual array of Lesson documents that belong to this unit. Populated when fetching a subject by slug.

​
Endpoints

​
GET /api/subjects

Returns all active subjects, each enriched with the authenticated user’s progress data: total lessons, how many they have completed, and an overall completion percentage. Authentication: Bearer token required. 
curl https://api.sealearn.app/api/subjects \
  -H "Authorization: Bearer <token>"
​
ok
boolean
true on success.
​
data
object[]
Array of subject objects.
Example response 
{
  "ok": true,
  "data": [
    {
      "_id": "665f1a2b3c4d5e6f7a8b9c0d",
      "name": "Mathematics",
      "slug": "mathematics",
      "description": "From arithmetic to calculus, explore the language of the universe.",
      "icon": "➗",
      "color": "#10B981",
      "order": 1,
      "isActive": true,
      "totalLessons": 24,
      "completedLessons": 6,
      "progressPercent": 25
    }
  ]
}

​
GET /api/subjects/:slug

Returns a single active subject identified by its slug, with all of its units and their lessons fully populated. Each lesson carries the requesting user’s personal status (locked, available, in_progress, or completed), best score, completion count, and the next spaced-repetition review date when applicable. Authentication: Bearer token required. Path parameters
​
slug
string
required
URL slug of the subject (e.g. mathematics).
curl https://api.sealearn.app/api/subjects/mathematics \
  -H "Authorization: Bearer <token>"
​
ok
boolean
true on success.
​
data
object
Subject object with units and progress summary.
The first lesson in each unit always has a default status of available when no progress record exists. All subsequent lessons start as locked and are unlocked after the preceding lesson is completed at least 4 times.
Example response 
{
  "ok": true,
  "data": {
    "_id": "665f1a2b3c4d5e6f7a8b9c0d",
    "name": "Mathematics",
    "slug": "mathematics",
    "totalLessons": 24,
    "completedLessons": 6,
    "progressPercent": 25,
    "units": [
      {
        "_id": "665f2b3c4d5e6f7a8b9c0e1f",
        "name": "Arithmetic",
        "order": 1,
        "totalLessons": 8,
        "completedLessons": 3,
        "progressPercent": 38,
        "lessons": [
          {
            "_id": "665f3c4d5e6f7a8b9c0f1a2b",
            "name": "Adding and Subtracting",
            "order": 1,
            "xpReward": 10,
            "difficulty": "easy",
            "status": "completed",
            "bestScore": 100,
            "completions": 2,
            "nextReviewDate": "2025-06-14T00:00:00.000Z"
          }
        ]
      }
    ]
  }
}

​
POST /api/subjects

Creates a new subject. The slug is auto-generated from name if not provided. Authentication: Bearer token + admin role required. Request body
​
name
string
required
Unique display name for the subject.
​
description
string
required
Short description. Maximum 300 characters.
​
icon
string
Emoji or icon string. Defaults to 📚.
​
color
string
Hex color string (e.g. #10B981). Defaults to #4F46E5.
​
order
number
Sort position in the subject list. Defaults to 0.
​
isActive
boolean
Whether the subject is immediately visible to learners. Defaults to true.
​
aiPromptContext
string
Optional context string passed to the AI when generating questions for any lesson within this subject.
curl -X POST https://api.sealearn.app/api/subjects \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Python Programming",
    "description": "Learn Python from variables and loops to object-oriented design.",
    "icon": "🐍",
    "color": "#3B82F6",
    "order": 3,
    "aiPromptContext": "Focus on beginner-friendly Python syntax and real-world coding examples."
  }'
Returns 201 Created with the new subject document under data.

​
PUT /api/subjects/:id

Updates an existing subject. Only the fields included in the request body are modified. Runs schema validators on the provided values. Authentication: Bearer token + admin role required. Path parameters
​
id
string
required
MongoDB ObjectId of the subject to update.
Request body — Any subset of Subject fields (see POST /api/subjects above). 
curl -X PUT https://api.sealearn.app/api/subjects/665f1a2b3c4d5e6f7a8b9c0d \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{ "color": "#F59E0B", "order": 2 }'
Returns 200 OK with the updated subject document under data. Returns 404 if the subject does not exist.

​
DELETE /api/subjects/:id

Performs a soft delete: sets isActive to false so the subject no longer appears in learner-facing responses. No data is permanently removed. Authentication: Bearer token + admin role required. Path parameters
​
id
string
required
MongoDB ObjectId of the subject to deactivate.
curl -X DELETE https://api.sealearn.app/api/subjects/665f1a2b3c4d5e6f7a8b9c0d \
  -H "Authorization: Bearer <admin-token>"
Example response 
{ "ok": true, "message": "Materia desactivada" }
Deleting a subject via findOneAndDelete (used in the cascade middleware) permanently removes all child units, lessons, and questions. The DELETE /api/subjects/:id endpoint performs only a soft delete via findByIdAndUpdate. To hard-delete, use the admin database tooling directly — not this endpoint.

Build docs developers (and LLMs) love

Get started for freeTalk to us