Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/J0S3-LEON/pf_pruebasAseguramientoCalid_SDD/llms.txt

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

The Sessions API drives MindFlow’s core adaptive loop. A student starts an EMA (Ecological Momentary Assessment) session, which opens a window for submitting a self-reported fatigue score on the 1–5 scale. If the submitted score is 4 or higher, the backend automatically triggers the AI task decomposer to break the student’s active tasks into bite-sized micro-objectives of no more than 25 minutes each. All three endpoints require JWT authentication, and every response follows the standard { data, error, status } envelope.
Starting a new session with POST /api/v1/sessions automatically closes any previously active session for the same student by setting its is_active = false and recording an endedAt timestamp.

​
POST /api/v1/sessions

Starts a new EMA session for the authenticated student. The response contains the server-assigned sessionId (which is required for the subsequent fatigue submission) and the EMA bot’s opening prompt. Authentication: JWT Bearer Request Body: None

​
Response — 201 Created

​
data.sessionId
string
UUID of the newly created session. Pass this value to POST /api/v1/sessions/:sessionId/fatigue.
​
data.prompt
string
The EMA bot’s opening question presented to the student.
​
error
null
Always null on success.
​
status
integer
201
Example Response
{
  "data": {
    "sessionId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "prompt": "¿Cómo te sientes hoy? (1-5)"
  },
  "error": null,
  "status": 201
}

​
Errors

StatusCondition
401 UnauthorizedJWT is missing or expired.

​
POST /api/v1/sessions/:sessionId/fatigue

Submits the student’s self-reported fatigue score for an active session. The score is validated strictly at the DTO level before any database write is attempted. On a valid submission the server persists a FatigueRecord, closes the session (is_active = false), and — if the score is >= 4 — invokes the AI task decomposer for the student’s active tasks. Authentication: JWT Bearer

​
Path Parameters

​
sessionId
string
required
UUID of the active session returned by POST /api/v1/sessions.

​
Request Body

​
score
integer
required
Self-reported fatigue score. Must be a whole integer in the range [1, 5]. Decimals, strings, booleans, and null are all rejected with 422.
​
taskId
string
Optional UUID of a specific task to decompose when score >= 4. If omitted and the score triggers decomposition, the service selects the task with the earliest deadline.
Example Request
{
  "score": 4
}
Example Request with taskId
{
  "score": 4,
  "taskId": "3f7e1b2c-4a5d-4e8f-9c0b-1a2b3c4d5e6f"
}

​
Response — 201 Created

​
data.fatigueRecordId
string
UUID of the persisted FatigueRecord.
​
data.sessionId
string
UUID of the session this record belongs to.
​
data.score
integer
The fatigue score as stored — always a whole integer in [1, 5].
​
data.recordedAtUtc
string
ISO 8601 UTC timestamp of when the record was persisted.
​
data.message
string
Human-readable status message indicating the next step in the EMA flow.
​
data.microObjectives
array
Array of AI-generated MicroObjective objects. Populated only when score >= 4 and the AI decomposer succeeds; empty array otherwise.
​
data.task
object | null
The original Task object. Returned when no micro-objectives were generated — either because score <= 3 or as a fallback when AI decomposition fails. null when micro-objectives were successfully generated.
​
data.decompositionFailed
boolean
true if decomposition was attempted (score >= 4) but the AI service failed. The original task is surfaced as a fallback in this case.
​
error
null
Always null on success.
​
status
integer
201
Example Response — score 4, AI decomposition successful
{
  "data": {
    "fatigueRecordId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "sessionId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "score": 4,
    "recordedAtUtc": "2025-07-25T10:30:00.000Z",
    "message": "Fatigue score registrado. Se generaron 3 micro-objetivo(s) para tus tareas activas.",
    "microObjectives": [
      {
        "id": "9e8d7c6b-5a4f-3e2d-1c0b-9a8b7c6d5e4f",
        "taskId": "3f7e1b2c-4a5d-4e8f-9c0b-1a2b3c4d5e6f",
        "content": "Draft the motivation section (250 words)",
        "estimatedMinutes": 20,
        "isCompleted": false
      }
    ],
    "task": null,
    "decompositionFailed": false
  },
  "error": null,
  "status": 201
}
Example Response — score 2, no decomposition
{
  "data": {
    "fatigueRecordId": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "sessionId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "score": 2,
    "recordedAtUtc": "2025-07-25T10:30:00.000Z",
    "message": "Fatigue score registrado. Transicionando al flujo de interacción de tareas.",
    "microObjectives": [],
    "task": {
      "id": "3f7e1b2c-4a5d-4e8f-9c0b-1a2b3c4d5e6f",
      "name": "Write thesis introduction",
      "deadline": "2025-08-01T23:59:00.000Z"
    },
    "decompositionFailed": false
  },
  "error": null,
  "status": 201
}

​
Errors

StatusCondition
422 Unprocessable Entityscore is not a whole integer, is out of the [1, 5] range, is a decimal, a string, a boolean, or null.
400 Bad RequestThe session does not exist, belongs to a different student, or has already been completed.
401 UnauthorizedJWT is missing or expired.
Score validation is strict. The DTO uses @IsInt() — only whole integer values pass validation. The @Type(() => Number) transformer coerces incoming values to a number first, so a JSON body value of 5.0 (which coerces to 5) is accepted, but 4.5 (a non-integer), "4" (a string that does not coerce cleanly), or null are all rejected with 422.
Submitting a score to an already-completed session (i.e. a session where is_active = false) returns 400 Bad Request. Always use the sessionId from the most recent POST /api/v1/sessions call.

​
GET /api/v1/sessions

Returns the authenticated student’s session history — up to the last 30 sessions, ordered by startedAt descending (most recent first). Authentication: JWT Bearer Request Body: None

​
Response — 200 OK

​
data
array
Array of up to 30 session objects sorted by startedAt descending.
​
error
null
Always null on success.
​
status
integer
200
Each item in the data array has the following fields:
​
data[].id
string
UUID of the session.
​
data[].studentId
string
UUID of the owning student.
​
data[].startedAt
string
ISO 8601 UTC timestamp when the session was created.
​
data[].endedAt
string | null
ISO 8601 UTC timestamp when the session was closed, or null if the session is still active.
​
data[].isActive
boolean
true if the session has not yet received a fatigue score submission.
Example Response
{
  "data": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "studentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "startedAt": "2025-07-25T10:28:00.000Z",
      "endedAt": "2025-07-25T10:30:00.000Z",
      "isActive": false
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "studentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "startedAt": "2025-07-24T09:00:00.000Z",
      "endedAt": "2025-07-24T09:02:00.000Z",
      "isActive": false
    }
  ],
  "error": null,
  "status": 200
}

​
Errors

StatusCondition
401 UnauthorizedJWT is missing or expired.

Build docs developers (and LLMs) love

Get started for freeTalk to us