DOCS · API v1 · DATASET v1.1.0

API reference

Everything is a GET over JSON — keyless to try, CORS-enabled, CDN-cached. Prefer machine contracts? Use /openapi.json (rendered at /docs/api) or /llms.txt for agents.

Endpoints

Endpoint	Purpose
GET /v1/exercises	List & filter the catalog. All filters below; sort + pagination.
GET /v1/exercises/{id}	One exercise by stable slug.
GET /v1/meta	Vocabularies with counts, dataset_version, license + attribution.
GET /health	Liveness + dataset size.
GET /openapi.json	OpenAPI 3.1 spec — the canonical machine contract.
GET /llms.txt	Concise API map for doc-reading agents (llms-full.txt = everything).
POST /v1/suggestions	Suggest a missing exercise / correction — filed to the public issue tracker for review. 5/day per IP.

First request — your first 100 calls each day are free, no key needed:

curl "https://exercise-api.com/v1/exercises?muscle=chest&sfr_class=high"

Parameters — GET /v1/exercises

Distinct filters AND together; comma-separated values within one filter OR together. Invalid values return a 400 that lists the valid ones.

Param	Values	Meaning
muscle	enum (16 muscles)	Primary muscle. Comma-separated = any-of.
secondary_muscle	same vocabulary	Meaningful secondary involvement.
pattern	enum (20 patterns)	Movement pattern.
sfr_class	high · moderate · low	Stimulus-to-fatigue class.
tier	core · extended	Catalog tier.
modality	hypertrophy · conditioning · calisthenics · mobility	Training purpose.
substitution_group	see /v1/meta	e1RM substitution group.
progression_group	see /v1/meta	Calisthenics progression chain.
equipment	equipment tokens	Exercises that require this token.
available_equipment	equipment tokens	Subset match: only exercises whose entire equipment list is covered by your tokens. none_bodyweight (your body) is always implied.
gold_standard · loadable · unilateral · home_hotel_friendly	true · false	Boolean filters.
q	free text	Case-insensitive substring search over name and id.
sort	name · -name · preferred_rank · -preferred_rank · id · -id	Stable sort with id tiebreak — pagination-safe.
limit	1–200 (default 20)	Page size. limit=200 fits the whole catalog in one page.
offset	≥ 0	Zero-based offset into the filtered set.

Field dictionary

20 fields, all always present — nullable fields use null, never omission. This table is generated from the same schema module the API runs on.

Field	Type	Meaning
id	string	Stable, URL-safe snake_case slug, unique across the catalog (e.g. `barbell_bench_press`). Never reused or renamed — safe to store as a foreign reference.
name	string	Human-readable display name.
primary_muscle	enum	The muscle the exercise primarily targets.
secondary_muscles	enum[]	Muscles meaningfully worked besides the primary. Same vocabulary as `primary_muscle`. May be empty.
pattern	enum	Movement pattern classification.
equipment	enum[]	Every equipment token required to perform the exercise. `none_bodyweight` means no equipment is needed.
sfr_class	enum \| null	Stimulus-to-fatigue ratio class: how much hypertrophy stimulus the exercise delivers per unit of fatigue. `high` is best. Null for non-hypertrophy modalities.
is_gold_standard	boolean	True when the exercise is a research/EMG-backed top pick for its primary muscle (see data/SOURCE.md for citations).
preferred_rank	integer \| null	1-based preference order among exercises sharing a primary muscle — lower is more preferred by the curators. Null for non-hypertrophy modalities.
e1rm_substitution_group	string \| null	Named group of interchangeable exercises for estimated-1RM tracking: swapping within a group preserves comparable strength-progression data. Null when e1RM tracking doesn't apply.
default_rep_low	integer \| null	Lower bound of the curated default hypertrophy rep range. Null for time- or hold-based work.
default_rep_high	integer \| null	Upper bound of the curated default hypertrophy rep range. Null for time- or hold-based work.
loadable	boolean	True when the exercise can be progressively loaded with external weight.
unilateral	boolean	True when the exercise trains one side at a time.
home_hotel_friendly	boolean	True when the exercise is practical with minimal/portable equipment (hotel room, home setup).
tier	enum	`core` = the curated default library; `extended` = additive variations and calisthenics progression rungs.
modality	enum	Primary training purpose. Current catalog: `hypertrophy` and `calisthenics` (skill-progression work); `conditioning` and `mobility` are reserved for upcoming dataset releases. Overlaps (e.g. weighted dips) are classified by primary purpose — use pattern/equipment/progression fields for finer slicing.
progression_group	string \| null	Named calisthenics progression chain this exercise belongs to (e.g. `planche_push_line`), or null for non-progression exercises.
progression_level	integer \| null	1-based difficulty rung within `progression_group` (higher = harder), or null.
cues	string	Short coaching cues for correct execution.

Vocabularies

Live from the dataset (counts = records using each value). Also served as JSON at /v1/meta. New values may be added within /v1; values are never removed or renamed.

PRIMARY MUSCLES

abs 16biceps 9calves 7chest 17forearms 6front_delts 17glutes 9hamstrings 11lats 21lower_back 5quads 21rear_delts 6side_delts 6traps 5triceps 16upper_back 11

MOVEMENT PATTERNS

anti_extension 8calf_raise 7curl 15fly 5hip_hinge 11hip_thrust 8horizontal_press 13horizontal_pull 18incline_press 4lateral_raise 6leg_curl 6leg_extension 2lunge 7rear_delt 6shrug 4squat 12triceps_extension 16trunk_flexion 9vertical_press 12vertical_pull 14

EQUIPMENT

ab_wheel 3adjustable_bench 12assisted_pullup_machine 1barbell 25bench_or_box 15cable_stack 20chest_press_machine 1dip_belt 2dip_station 3dumbbells 32ez_curl_bar 4flat_bench 12gymnastic_rings 6hack_squat_machine 3hip_thrust_machine 1landmine 3lat_pulldown 2leg_curl_machine 2leg_extension_machine 1leg_press 2none_bodyweight 21parallettes 9pec_deck 2power_rack 13preacher_bench 2pullup_bar 13resistance_bands 16seated_calf_machine 1seated_row_machine 1shoulder_press_machine 1smith_machine 3standing_calf_machine 1suspension_trainer 1t_bar_row 1

SFR CLASSES

high 79low 12moderate 92

MODALITIES

calisthenics 47hypertrophy 136

SUBSTITUTION GROUPS

abs_anti_extension 3abs_flexion 6back_horizontal_row 10biceps_curl 9calf_seated 2calf_standing 5chest_fly 5chest_horizontal_press 5chest_incline_press 4core_anti_extension_progression 4dip_vertical_push 6forearm_flexion 6front_lever_horizontal_pull 6glute_abduction 2glute_hip_thrust 7hamstring_curl 3hamstring_hinge 5handstand_vertical_push 5lats_vertical_pull 9lower_back_extension 5lsit_flexion_progression 3nordic_curl_progression 3planche_horizontal_push 7quad_extension 2quad_lunge 5quad_squat 8rear_delt_fly 6shoulder_vertical_press 7side_delt_raise 6single_leg_squat_progression 6traps_shrug 5triceps_extension 11vertical_pull_progression 7

PROGRESSION GROUPS

core_anti_extension_line 4dip_line 6front_lever_pull_line 6handstand_push_line 5lsit_line 3nordic_curl_line 3pistol_squat_line 6planche_push_line 7vertical_pull_line 7

Conventions

Lists use a Stripe-style envelope; errors carry a stable machine-readable code: invalid_parameter (400), not_found (404), rate_limited (429), internal_error (500).

{
  "object": "list",
  "data": [
    "…exercise records…"
  ],
  "count": 20,
  "total": 47,
  "limit": 20,
  "offset": 0
}

{
  "error": {
    "code": "not_found",
    "message": "No exercise with id …"
  }
}

Rate limits

Anonymous use is free: 100 requests per day per IP, plus a per-minute burst limit. /v1 responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; exceeding a limit returns 429 with the error envelope and Retry-After. Since catalog responses are CDN-cached, cache hits are cheap — but still budget your calls: fetch limit=200 once and work locally, or pin a snapshot release for bulk use. A free API key tier with higher limits is planned.

Versioning

Two independent axes. API contract: versioned in the path (/v1), additive-only — fields and enum values are added, never removed, renamed, or retyped; breaking changes would ship as /v2 with a 12-month /v1 sunset window. Dataset content: semver (currently v1.1.0), exposed in /v1/meta and the X-Dataset-Version header on every response. MINOR = exercises/fields added, PATCH = corrections. Immutable snapshots of each dataset release are published on GitHub for consumers who need reproducible builds.

License & attribution

The data is CC BY 4.0 — free to use, including commercially, but products using it must credit ExerciseAPI. A ready-to-use credit line is served in /v1/meta (license.attribution):

Exercise data by ExerciseAPI (https://exercise-api.com), licensed under CC BY 4.0.