Exercise Catalog and Muscle Group Assignments in Blackterz

Blackterz ships with a catalog of 64 exercises seeded from strengthlevel.es data. Every exercise has a Spanish name, a description, a category (all seeded entries use fuerza), a color .avif image (~12 KB each), and an optional looping MP4 video sourced via AscendAPI. The catalog is read-only from the API perspective — exercises are managed through database seeds and migrations, not end-user requests.

Listing All Exercises

GET /api/ejercicios returns the full catalog, including each exercise’s associated muscle groups as a comma-separated string. The endpoint requires a valid JWT.

curl http://localhost:3000/api/ejercicios \
  -H "Authorization: Bearer <token>"

The model executes a single GROUP_CONCAT query across the exercises–muscle groups join:

SELECT
  e.id,
  e.nombre,
  e.descripcion,
  e.categoria,
  e.imagen_url,
  e.gif_url,
  GROUP_CONCAT(DISTINCT gm.nombre ORDER BY gm.nombre SEPARATOR ', ') AS musculos
FROM ejercicios e
LEFT JOIN ejercicios_grupos_musculares eg ON e.id = eg.ejercicio_id
LEFT JOIN grupos_musculares gm ON eg.grupo_muscular_id = gm.id
GROUP BY e.id, e.nombre, e.descripcion, e.categoria, e.imagen_url, e.gif_url
ORDER BY e.nombre ASC

Response fields

number

The exercise’s primary key.

nombre

string

Spanish name of the exercise, e.g. "Press de banca".

descripcion

string

Brief description of technique or focus.

categoria

string

Exercise category. All 64 seeded exercises use the value "fuerza". The column supports additional categories for future seed expansions.

imagen_url

string

Filename of the .avif image, e.g. "bench-press.avif". The frontend prepends /images/ at render time to build the full path served by express.static.

gif_url

string | null

Absolute URL to an MP4 video from AscendAPI, or null if the video has not been fetched yet.

musculos

string

Comma-separated list of muscle group names from the grupos_musculares table, e.g. "Hombros, Pecho, Tríceps". Empty string if no assignments exist.

Sample exercise object

{
  "id": 1,
  "nombre": "Press de banca",
  "descripcion": "Ejercicio de barra para Pecho.",
  "categoria": "fuerza",
  "imagen_url": "bench-press.avif",
  "gif_url": "https://cdn.ascendapi.com/exercises/bench-press.mp4",
  "musculos": "Hombros, Pecho, Tríceps"
}

Muscle Groups

The catalog covers 15 muscle groups defined in the grupos_musculares table. Each exercise can have one or more principal or secondary group assignments via the ejercicios_grupos_musculares pivot table.

Upper Body — Push

Hombros, Tríceps, Pecho

Upper Body — Pull

Bíceps, Antebrazos, Espalda Media, Espalda Baja, Trampas

Lower Body

Cuádriceps, Isquiotibiales, Gemelos, Glúteos, Aductores, Flexores Cadera

Core

The musculos field returned by GET /api/ejercicios is a flat comma-separated string combining all muscle group assignments for that exercise. The frontend uses this string to power the real-time search filter — a query for "Hombros" matches every exercise that trains shoulders.

Exercise Videos via AscendAPI

The gif_url field is populated by the AscendAPI (available on RapidAPI). The API returns looping MP4 video URLs for standard exercises by English slug.

Setup instructions

Create a RapidAPI account and subscribe to the AscendAPI.
Copy your API key.
Add it to your .env file:

ASCENDAPI_KEY=your_rapidapi_key_here

The seeder script maps Spanish exercise names to English slugs (e.g. "Press de banca" → "bench-press") and fetches the video URL for each exercise.

The AscendAPI free tier allows 2,000 requests per month. With 64 exercises in the catalog, a full re-seed consumes 64 requests. Do not re-run the seeder unnecessarily in production. If gif_url is null for an exercise, the frontend falls back to showing only the .avif static image.

The frontend renders a full-screen lightbox when a user taps an exercise image during a training session or while browsing the catalog. The modal shows:

The exercise image at full size
Exercise name and description
Muscle group list
Category badge
Looping MP4 video (autoplay, muted) if gif_url is available

The lightbox is dismissed by clicking the ✕ button, clicking the backdrop, or pressing Escape.

Adding Exercises to a Routine

Exercises are linked to routines through the ejercicios_rutinas pivot table. To set the exercise list for a routine, send an ejercicios_ids array in a PUT /api/rutinas/:id request. The array completely replaces the current list — include all exercises you want, in the order you want them.

{
  "nombre": "Push Day",
  "descripcion": "Pecho, hombros y tríceps",
  "ejercicios_ids": [4, 12, 7, 9]
}

Adding Exercises Mid-Session

Users can add exercises from the catalog during an active training session without modifying the base routine. The frontend renders an “Agregar ejercicio extra” search panel below the routine’s exercise cards. Typing in the search box filters the catalog client-side using the musculos string — no additional API calls. Extra exercises added mid-session are:

Included in the POST /api/sesiones payload under ejercicios[]
Persisted to localStorage via guardarEstadoEntrenamiento() so they survive a page refresh
Not written back to the routine definition

The anti-duplicate filter (obtenerIdsEjerciciosActivos()) scans the active DOM cards and hides already-added exercises from the extra panel, preventing the user from accidentally adding the same exercise twice.

Exercise Search

Both the routine editor modal and the mid-session extra panel include a real-time search input. Filtering happens entirely client-side after the catalog is loaded once into memory:

function filtrarCatalogo(termino) {
  return catalogoEjercicios.filter(ej =>
    ej.nombre.toLowerCase().includes(termino.toLowerCase()) ||
    (ej.musculos && ej.musculos.toLowerCase().includes(termino.toLowerCase()))
  );
}

Searches match against both the exercise name and the muscle group list, so "Pecho" returns all chest exercises regardless of their name.

API Reference — Exercises

View full request/response schemas, error codes, and live playground for the /api/ejercicios endpoint.

Get Started

Core Features

Architecture

Exercise Catalog and Muscle Group Assignments in Blackterz

Listing All Exercises

Response fields

Sample exercise object

Muscle Groups

Upper Body — Push

Upper Body — Pull

Lower Body

Core

Exercise Videos via AscendAPI

Adding Exercises to a Routine

Adding Exercises Mid-Session

Exercise Search

API Reference — Exercises

Build docs developers (and LLMs) love

Get Started

Core Features

Architecture

Documentation Index

​Listing All Exercises

​Response fields

​Sample exercise object

​Muscle Groups

Upper Body — Push

Upper Body — Pull

Lower Body

Core

​Exercise Videos via AscendAPI

​Exercise Detail Modal (Lightbox)

​Adding Exercises to a Routine

​Adding Exercises Mid-Session

​Exercise Search

API Reference — Exercises

Build docs developers (and LLMs) love

Listing All Exercises

Response fields

Sample exercise object

Muscle Groups

Exercise Videos via AscendAPI

Exercise Detail Modal (Lightbox)

Adding Exercises to a Routine

Adding Exercises Mid-Session

Exercise Search