Routines API: CRUD Endpoints for Workout Routines

The Routines API manages the workout routines that belong to the authenticated user. Each routine holds a list of exercises drawn from the global exercise catalog and can be updated at any time. Deleting a routine is non-destructive — it is soft-deleted by setting activa = FALSE, so training history linked to it is never lost.

Every endpoint in this group requires a valid JWT passed as Authorization: Bearer <token>. The usuario_id is always extracted from the token — any usuario_id value in the request body is silently ignored. This prevents ID spoofing.

GET /api/rutinas

GET /api/rutinas Returns all active routines owned by the authenticated user, ordered by creation date descending. Each entry includes a precomputed total_ejercicios count so the frontend can display a summary card without fetching each routine individually. Auth required: Yes — Authorization: Bearer <token>

Responses

200 OK — Routines retrieved

status

string

"ok"

data

array

Array of routine summary objects.

Show Routine object fields

number

Routine primary key.

nombre

string

Routine name.

descripcion

string | null

Optional description.

created_at

string

ISO 8601 creation timestamp.

es_recomendada

boolean

Whether this is a system-recommended routine rather than user-created.

total_ejercicios

number

Total number of exercises assigned to this routine.

401 Unauthorized — Missing or invalid token

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

Example

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

POST /api/rutinas/crear

POST /api/rutinas/crear Creates a new personalized routine for the authenticated user. An optional array of exercise IDs can be provided to assign exercises at creation time. Auth required: Yes — Authorization: Bearer <token>

Each user is limited to 4 user-created routines. System-recommended routines (where es_recomendada = TRUE, created automatically during onboarding) are excluded from this count. The limit is checked at the moment of each creation request to eliminate race conditions between concurrent tabs or sessions. If the limit is already reached, the server returns 403 Forbidden regardless of how the request was formed.

Request body

nombre

string

required

Name of the new routine (e.g., "Pull Day"). Must be a non-empty string.

descripcion

string

Optional free-text description of the routine’s purpose or structure.

ejercicios_ids

array of numbers

Optional list of exercise IDs (from the global catalog) to assign to the routine at creation. IDs are assigned an orden value starting at 1. Non-numeric values are silently filtered out. If omitted, the routine is created with no exercises.

Responses

201 Created — Routine created

status

string

"ok"

message

string

"Rutina creada exitosamente"

data

object

Show data fields

number

Auto-generated ID of the new routine.

nombre

string

Routine name as stored.

descripcion

string | null

Routine description or null.

usuario_id

number

ID of the owning user (from the JWT).

400 Bad Request — Missing or invalid name

{ "status": "error", "message": "El nombre de la rutina es obligatorio" }

403 Forbidden — Routine limit reached

{ "status": "error", "message": "Has alcanzado el límite de 4 rutinas personalizadas." }

Example

curl -X POST https://your-api.com/api/rutinas/crear \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Pull Day",
    "descripcion": "Espalda y bíceps",
    "ejercicios_ids": [4, 7, 12]
  }'

GET /api/rutinas/:id

GET /api/rutinas/:id Returns a single routine with its complete, ordered exercise list. Uses a single SQL LEFT JOIN across rutinas, ejercicios_rutinas, and ejercicios — one database round-trip regardless of exercise count. Auth required: Yes — Authorization: Bearer <token>

Path parameters

number

required

Numeric ID of the routine to retrieve. Non-numeric values return 400.

Responses

200 OK — Routine with exercises

status

string

"ok"

data

object

Show data fields

number

Routine ID.

nombre

string

Routine name.

descripcion

string | null

Routine description.

ejercicios

array

Ordered array of exercises assigned to this routine.

Show Exercise object fields

number

Exercise ID.

nombre

string

Exercise name.

descripcion

string | null

Exercise description.

categoria

string

Muscle group or category.

imagen_url

string | null

Static image URL.

gif_url

string | null

Animated demonstration GIF URL.

orden

number

Position of this exercise within the routine (1-indexed).

series

number | null

Recommended number of sets.

repeticiones

number | null

Recommended rep count per set.

peso

number | null

Recommended weight in kg.

400 Bad Request — Non-numeric ID

{ "status": "error", "message": "El ID de la rutina debe ser un número válido" }

404 Not Found — Routine does not exist or does not belong to the user

{ "status": "error", "message": "No se encontró la rutina con ID 99" }

Example

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

PUT /api/rutinas/:id

PUT /api/rutinas/:id Updates the name, description, and exercise list of an existing routine. This is a full replacement — the incoming ejercicios_ids array completely replaces every exercise currently in the routine. The replacement is performed atomically inside a SQL transaction (DELETE all current entries, then INSERT the new list), so the routine is never left in a partial state. Auth required: Yes — Authorization: Bearer <token>

ejercicios_ids is not a patch. If you send [1, 5, 3], the routine ends up with exactly those three exercises in that order, regardless of what it contained before. To keep existing exercises, include their IDs in the new array.

Path parameters

number

required

Numeric ID of the routine to update.

Request body

nombre

string

required

Updated routine name. Cannot be empty.

descripcion

string

Updated description. Pass null or omit to clear.

ejercicios_ids

array of numbers

Ordered list of exercise IDs that will replace the routine’s current exercise list entirely. At least one valid numeric ID is required. Invalid (non-numeric) entries are silently skipped.

Responses

200 OK — Routine updated

Returns the full updated routine object, re-read from the database after the update.

status

string

"ok"

message

string

"Rutina actualizada exitosamente"

data

object

Same shape as GET /api/rutinas/:id — the updated routine with its full exercise list.

400 Bad Request — Missing name or invalid ID

{ "status": "error", "message": "El nombre de la rutina es obligatorio" }
{ "status": "error", "message": "El ID de la rutina debe ser un número válido" }

404 Not Found — Routine not found or not owned by the user

{ "status": "error", "message": "Rutina no encontrada o no tienes permiso para editarla" }

Example

curl -X PUT https://your-api.com/api/rutinas/3 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Full Body v2",
    "descripcion": "Actualizado con más volumen",
    "ejercicios_ids": [4, 7, 2, 9]
  }'

DELETE /api/rutinas/:id

DELETE /api/rutinas/:id Soft-deletes a routine by setting its activa column to FALSE. The row is not removed from the database. All training sessions that reference this routine remain intact and fully queryable — only the routine itself disappears from the user’s active list. Auth required: Yes — Authorization: Bearer <token>

Because deletion is non-destructive, a soft-deleted routine frees up one slot toward the 4-routine limit, allowing the user to create a new one.

Path parameters

number

required

Numeric ID of the routine to deactivate.

Responses

200 OK — Routine deactivated

{ "status": "ok", "message": "Rutina desactivada correctamente" }

400 Bad Request — Non-numeric ID

{ "status": "error", "message": "El ID de la rutina debe ser un número válido" }

404 Not Found — Routine not found or already deactivated

{ "status": "error", "message": "Rutina no encontrada" }

Example

curl -X DELETE https://your-api.com/api/rutinas/3 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Overview

Endpoints

Routines API: CRUD Endpoints for Workout Routines

GET /api/rutinas

Responses

Example

POST /api/rutinas/crear

Request body

Responses

Example

GET /api/rutinas/:id

Path parameters

Responses

Example

PUT /api/rutinas/:id

Path parameters

Request body

Responses

Example

DELETE /api/rutinas/:id

Path parameters

Responses

Example

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​GET /api/rutinas

​Responses

​Example

​POST /api/rutinas/crear

​Request body

​Responses

​Example

​GET /api/rutinas/:id

​Path parameters

​Responses

​Example

​PUT /api/rutinas/:id

​Path parameters

​Request body

​Responses

​Example

​DELETE /api/rutinas/:id

​Path parameters

​Responses

​Example

Build docs developers (and LLMs) love

GET /api/rutinas

Responses

Example

POST /api/rutinas/crear

Request body

Responses

Example

GET /api/rutinas/:id

Path parameters

Responses

Example

PUT /api/rutinas/:id

Path parameters

Request body

Responses

Example

DELETE /api/rutinas/:id

Path parameters

Responses

Example