Sessions API: Log and Retrieve Training Sessions

The Sessions API records every completed training session for the authenticated user. Each session captures which routine was performed, the date it occurred, and the exact sets and reps logged for every exercise — down to peso, repeticiones, and completada per set. All write operations use atomic SQL transactions so session data is always consistent.

All endpoints require a valid JWT in the Authorization: Bearer <token> header. The usuario_id is extracted exclusively from the token payload — any usuario_id sent in the request body is overwritten before it reaches the database. This prevents ID spoofing.

GET /api/sesiones

GET /api/sesiones Returns the full training history for the authenticated user, ordered by fecha DESC then id DESC so the most recent session always appears first. Each item includes aggregate stats (volumen_total_kg, total_series) computed directly in SQL. Auth required: Yes — Authorization: Bearer <token>

Responses

200 OK — History retrieved

status

string

"ok"

data

array

Array of session summary objects, ordered newest first.

Show Session summary fields

number

Session primary key.

fecha

string

Training date (YYYY-MM-DD).

notas

string | null

Optional session notes.

duracion_minutos

number | null

Session duration in minutes, if recorded.

created_at

string

ISO 8601 timestamp of when the record was created.

rutina_nombre

string | null

Name of the routine used. null if the routine was subsequently deleted.

volumen_total_kg

number

Sum of peso × repeticiones across all completed sets in this session.

total_series

number

Count of completed sets logged in this session.

401 Unauthorized — Missing or invalid token

{ "status": "error", "message": "Token no proporcionado" }

Example

curl https://your-api.com/api/sesiones \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

POST /api/sesiones

POST /api/sesiones Logs a complete training session. The request must include the routine used, the date, and a nested structure of exercises with their individual sets. All three INSERT statements (into sesiones_entrenamiento, sesion_ejercicios, and sesion_series) execute inside a single SQL transaction — if any step fails, the entire session is rolled back. Auth required: Yes — Authorization: Bearer <token>

The SQL transaction guarantees atomicity: either all three layers of data (session header, exercise entries, and individual series) are committed together, or none of them are. A server crash mid-write will never leave orphaned rows in sesion_ejercicios or sesion_series.

Request body

rutina_id

number

required

ID of the routine performed during this session. Must reference an existing routine.

fecha

string

required

Date of the training session in YYYY-MM-DD format (e.g., "2025-01-15").

notas

string

Optional free-text notes about the session (e.g., "Felt strong today").

duracion_minutos

number

Optional total session duration in minutes.

ejercicios

array

required

Array of exercise entries. Must contain at least one item. Each item must include an ejercicio_id and at least one set in series.

Show Exercise entry fields

ejercicio_id

number

required

ID of the exercise from the global catalog.

notas

string

Optional per-exercise notes (e.g., "Shoulder pain on last set").

series

array

required

Array of set entries. Must contain at least one item.

Show Set (serie) fields

numero_serie

number

required

Set number within this exercise (e.g., 1, 2, 3).

repeticiones

number

required

Number of repetitions performed in this set.

peso

number

Weight in kg for this set. Defaults to 0 if omitted.

completada

boolean

Whether this set was completed. Defaults to false if omitted.

Responses

201 Created — Session logged

status

string

"ok"

message

string

"Sesión guardada exitosamente"

data

object

Show data fields

sesionId

number

Auto-incremented ID of the newly created session.

400 Bad Request — Validation failures

{ "status": "error", "message": "El campo rutina_id es requerido" }
{ "status": "error", "message": "El campo fecha es requerido" }
{ "status": "error", "message": "Debe incluir al menos un ejercicio en el array ejercicios" }
{ "status": "error", "message": "El ejercicio en la posición 0 debe tener un ejercicio_id" }
{ "status": "error", "message": "El ejercicio 4 debe incluir al menos una serie" }

400 Bad Request — Foreign key violation

{ "status": "error", "message": "El usuario o la rutina especificada no existe" }

Example

curl -X POST https://your-api.com/api/sesiones \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "rutina_id": 1,
    "fecha": "2025-01-15",
    "notas": "Buena sesión, PR en press banca",
    "duracion_minutos": 60,
    "ejercicios": [
      {
        "ejercicio_id": 4,
        "series": [
          { "numero_serie": 1, "repeticiones": 10, "peso": 80, "completada": true },
          { "numero_serie": 2, "repeticiones": 8,  "peso": 85, "completada": true },
          { "numero_serie": 3, "repeticiones": 7,  "peso": 85, "completada": true }
        ]
      }
    ]
  }'

GET /api/sesiones/ultima/:rutina_id

GET /api/sesiones/ultima/:rutina_id Retrieves the most recent training session the authenticated user has completed for a specific routine, with series data grouped by exercise. This endpoint powers the progressive overload feature: the frontend reads previous weights and reps and pre-fills the next session’s input fields as a reference target. Auth required: Yes — Authorization: Bearer <token>

This route is declared before GET /:id in the Express router. This ordering is required — if /:id were declared first, Express would interpret the literal string "ultima" as a session ID, routing the request to the wrong handler. The source already has the correct order; do not rearrange these route definitions.

Path parameters

rutina_id

number

required

Numeric ID of the routine to look up the last session for.

Responses

200 OK — Last session found

status

string

"ok"

data

object

Show data fields

sesionId

number

ID of the most recent session for this routine.

ejercicios

object

A keyed object where each key is an ejercicio_id (as a string) and each value is an array of set records from that session.

Show Per-exercise set fields

peso

number

Weight used in this set (kg).

repeticiones

number

Repetitions performed.

200 OK — No previous sessions for this routine

When no sessions exist, the server returns 200 with a null data payload rather than 404, so the frontend can distinguish “never trained” from “session not found”.

{
  "status": "ok",
  "data": null,
  "message": "No hay sesiones anteriores para esta rutina"
}

400 Bad Request — Non-numeric rutina_id

{ "status": "error", "message": "ID de rutina inválido" }

Example

curl https://your-api.com/api/sesiones/ultima/1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

GET /api/sesiones/:id

GET /api/sesiones/:id Returns the complete detail of a single training session, including every exercise and every set logged within it. The query joins sesiones_entrenamiento, sesion_ejercicios, ejercicios, and sesion_series, then restructures the flat tabular result into a nested JSON object. Auth required: Yes — Authorization: Bearer <token>

Path parameters

number

required

Numeric ID of the session to retrieve.

Responses

200 OK — Full session detail

boolean

true

data

object

Show Session detail fields

number

Session ID.

fecha

string

Training date.

notas

string | null

Session-level notes.

duracion_minutos

number | null

Session duration in minutes.

rutina_nombre

string | null

Name of the routine at the time it was performed.

ejercicios

array

Ordered array of exercises performed in this session.

Show Exercise entry fields

ejercicio_id

number

Exercise ID.

nombre

string

Exercise name.

gif_url

string | null

Animated GIF URL for reference.

imagen_url

string | null

Static image URL.

notas

string | null

Per-exercise notes logged during the session.

series

array

Array of sets performed for this exercise.

Show Set fields

numero_serie

number

Set number (1-indexed).

repeticiones

number

Reps performed.

peso

number

Weight used (kg).

completada

boolean

Whether the set was marked as completed.

400 Bad Request — Non-numeric ID

{ "ok": false, "mensaje": "ID de sesión inválido" }

404 Not Found — Session not found or belongs to another user

The server returns 404 in both cases — it does not reveal whether the session exists but belongs to another user.

{ "ok": false, "mensaje": "Sesión no encontrada" }

Example

curl https://your-api.com/api/sesiones/17 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Overview

Endpoints

Sessions API: Log and Retrieve Training Sessions

GET /api/sesiones

Responses

Example

POST /api/sesiones

Request body

Responses

Example

GET /api/sesiones/ultima/:rutina_id

Path parameters

Responses

Example

GET /api/sesiones/:id

Path parameters

Responses

Example

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/sesiones

​Responses

​Example

​POST /api/sesiones

​Request body

​Responses

​Example

​GET /api/sesiones/ultima/:rutina_id

​Path parameters

​Responses

​Example

​GET /api/sesiones/:id

​Path parameters

​Responses

​Example

Build docs developers (and LLMs) love

GET /api/sesiones

Responses

Example

POST /api/sesiones

Request body

Responses

Example

GET /api/sesiones/ultima/:rutina_id

Path parameters

Responses

Example

GET /api/sesiones/:id

Path parameters

Responses

Example