{"openapi":"3.0.0","paths":{"/v2/usage":{"get":{"operationId":"getReport","summary":"Get your usage","description":"Requests and errors per day, month or endpoint (updated every 5 minutes). Defaults to the current month.","parameters":[{"name":"from","required":false,"in":"query","description":"First day (UTC), defaults to the start of the current month","schema":{"example":"2026-09-01","type":"string"}},{"name":"to","required":false,"in":"query","description":"Last day (UTC, included), defaults to today","schema":{"example":"2026-09-30","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageReportDto"}}}},"403":{"description":"Only available with a key created in the dashboard"}},"tags":["Usage"]}},"/v2/usage/current":{"get":{"operationId":"getCurrentPeriod","summary":"Get your quota","description":"Plan and quota of the current billing period, in real time.","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurrentUsageDto"}}}},"403":{"description":"Only available with a key created in the dashboard"}},"tags":["Usage"]}},"/v2/calculator/bmr":{"get":{"operationId":"getBmr","summary":"Basal metabolic rate (BMR)","description":"Calories burned at rest in a day, with the Mifflin-St Jeor equation. Rounded to the unit.","parameters":[{"name":"height","required":true,"in":"query","description":"Height in centimeters","schema":{"minimum":1,"example":180,"type":"number"}},{"name":"age","required":true,"in":"query","description":"Age","schema":{"minimum":1,"example":25,"type":"number"}},{"name":"weight","required":true,"in":"query","description":"Body weight in kilograms","schema":{"minimum":1,"example":78,"type":"number"}},{"name":"gender","required":true,"in":"query","description":"Gender, which changes the constant of the equation","schema":{"example":"male","enum":["male","female"],"type":"string"}}],"responses":{"200":{"description":"Successful BMR calculation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculresultResDTO"},"example":{"result":1785}}}}},"tags":["Calculator"]}},"/v2/calculator/tdee":{"get":{"operationId":"getTdee","summary":"Total daily energy expenditure (TDEE)","description":"Calories burned in a day: the BMR times the factor of the activity level (`sedentary` 1.375, `lightlyActive` 1.56, `active` 1.64, `veryActive` 1.82). Rounded to the unit.","parameters":[{"name":"height","required":true,"in":"query","description":"Height in centimeters","schema":{"minimum":1,"example":180,"type":"number"}},{"name":"age","required":true,"in":"query","description":"Age","schema":{"minimum":1,"example":25,"type":"number"}},{"name":"weight","required":true,"in":"query","description":"Body weight in kilograms","schema":{"minimum":1,"example":78,"type":"number"}},{"name":"gender","required":true,"in":"query","description":"Gender, which changes the constant of the equation","schema":{"example":"male","enum":["male","female"],"type":"string"}},{"name":"activityLevel","required":true,"in":"query","description":"Level of physical activity","schema":{"example":"active","enum":["sedentary","lightlyActive","active","veryActive"],"type":"string"}}],"responses":{"200":{"description":"Successful TDEE calculation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculresultResDTO"},"example":{"result":2927}}}}},"tags":["Calculator"]}},"/v2/calculator/bmi":{"get":{"operationId":"getBmi","summary":"Body mass index (BMI)","description":"Weight in kilograms divided by the square of the height in meters. Rounded to one decimal.","parameters":[{"name":"height","required":true,"in":"query","description":"Height in centimeters","schema":{"minimum":1,"example":180,"type":"number"}},{"name":"weight","required":true,"in":"query","description":"Body weight in kilograms","schema":{"minimum":1,"example":78,"type":"number"}}],"responses":{"200":{"description":"Successful BMI calculation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculresultResDTO"},"example":{"result":24.1}}}}},"tags":["Calculator"]}},"/v2/calculator/ibw":{"get":{"operationId":"getIbw","summary":"Ideal body weight (IBW)","description":"Ideal weight in kilograms for a height, with the Devine formula. Rounded to one decimal.","parameters":[{"name":"height","required":true,"in":"query","description":"Height in centimeters","schema":{"minimum":1,"example":180,"type":"number"}}],"responses":{"200":{"description":"Successful IBW calculation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculresultResDTO"},"example":{"result":75.1}}}}},"tags":["Calculator"]}},"/v2/muscles/search":{"get":{"operationId":"searchMuscles","summary":"Search muscles","description":"Search the muscles of the catalog.\n\n**Features:**\n- Text search on the anatomical name, the common name (`Pecs`, `Quads`) and the aliases (`six pack`, `lower back`)\n- Filter by body part and by group (`GET /v2/muscle-groups`)\n- Paginated results, ordered by name\n\n**Use cases:**\n- Find a muscle by what people call it\n- List the muscles of a group\n- Fill a muscle picker","parameters":[{"name":"query","required":false,"in":"query","description":"Search query to filter muscles by name (case-insensitive)","schema":{"maxLength":100,"example":"pectoralis","type":"string"}},{"name":"bodyPart","required":false,"in":"query","description":"Filter by body part","schema":{"enum":["Legs","Back","Chest","Shoulders","Arms","Core","Neck"],"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Number of results to return","schema":{"minimum":1,"maximum":100,"default":50,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Number of results to skip","schema":{"minimum":0,"maximum":100,"default":0,"type":"number"}},{"name":"group","required":false,"in":"query","description":"Group of muscles (`GET /v2/muscle-groups`), e.g. `Hamstrings`","schema":{"maxLength":100,"type":"string"}}],"responses":{"200":{"description":"Muscles matching criteria","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchMusclesResponseDto"},"example":{"results":[{"id":"ffd76ee8-7633-4062-9c91-9092d637567a","name":"Pectoralis major","commonName":"Pecs","bodyPart":"Chest","group":"Chest"},{"id":"6be0d058-5813-49b8-aa58-634171adbee0","name":"Pectoralis minor","commonName":"Pectoralis minor","bodyPart":"Chest","group":"Chest"}],"total":2,"count":2}}}}},"tags":["Muscles"]}},"/v2/muscles/{id}":{"get":{"operationId":"getMuscleById","summary":"Get muscle details","description":"Retrieve a muscle with everything the catalog knows of it.\n\n**Includes:**\n- Anatomical name, common name and aliases\n- Body part and group\n- Heads of the muscle\n\nThe exercises that work it are listed by `GET /v2/muscles/{id}/exercises`.","parameters":[{"name":"id","required":true,"in":"path","description":"Muscle UUID","schema":{"format":"uuid","type":"string"},"example":"ffd76ee8-7633-4062-9c91-9092d637567a"}],"responses":{"200":{"description":"Detailed muscle information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MuscleDetailDto"},"example":{"id":"ffd76ee8-7633-4062-9c91-9092d637567a","name":"Pectoralis major","commonName":"Pecs","bodyPart":"Chest","group":"Chest","aliases":["chest","pectorals"],"heads":["Clavicular (Upper)","Sternal (Lower)"]}}}},"404":{"description":"Muscle not found"}},"tags":["Muscles"]}},"/v2/muscle-groups":{"get":{"operationId":"listGroups","summary":"List the muscle groups","description":"The muscle groups (`Chest`, `Lats`, `Hamstrings`...), each with its muscles and their heads, in one call.\n\nA group name is what `muscleGroup` takes on `GET /v2/exercises/search`. The result is the same for every request: keep it.","parameters":[],"responses":{"200":{"description":"The groups with their muscles","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MuscleGroupDto"}},"example":[{"id":"56cd4301-0124-4c75-bbe9-6a04ccd338e3","name":"Abs","aliases":["abdominals","six pack","core"],"muscles":[{"id":"7d561eae-b72d-48e8-9e5d-a8c82c1fc753","name":"Diaphragm","commonName":"Diaphragm","heads":[]},{"id":"b11a737a-d371-4f43-97b3-c3c4bd47cd09","name":"Rectus abdominis","commonName":"Abs","heads":["Lower","Middle","Superior"]},{"id":"45b8f8b5-cff3-4cec-8d1f-52f19ff9af14","name":"Transverse abdominis","commonName":"Deep abs","heads":[]}]},{"id":"b4798677-fd22-48d4-9662-94daf36cd7f3","name":"Adductors","aliases":["inner thigh","groin"],"muscles":[{"id":"22456832-adb8-4eef-bdf6-03c03ede89fa","name":"Adductor brevis","commonName":"Adductor brevis","heads":[]},{"id":"df03e634-d5d7-4d61-bc23-15b5e2f708bb","name":"Adductor longus","commonName":"Adductor longus","heads":[]},{"id":"af4088f9-a989-4f23-9cd9-49558602c761","name":"Adductor magnus","commonName":"Adductor magnus","heads":["Adductor (Anterior)","Hamstring (Posterior)"]},{"id":"771f5070-1d6a-435d-8cff-e8bb562d4441","name":"Gracilis","commonName":"Gracilis","heads":[]},{"id":"7d2cf221-96bb-4c38-9471-71f6401df991","name":"Pectineus","commonName":"Pectineus","heads":[]}]},{"id":"fe03d381-5c6a-4229-8faa-f79bb3e0e1b7","name":"Biceps","aliases":["bis","guns"],"muscles":[{"id":"6ad37840-db50-431c-80df-171a031fbdec","name":"Biceps brachii","commonName":"Biceps","heads":["Long","Short"]},{"id":"98b3cd59-8b5c-4fcf-9724-b9874e4b93c1","name":"Brachialis","commonName":"Brachialis","heads":[]}]},{"id":"62ccea28-6d01-42ea-a66f-04fa153119ef","name":"Calves","aliases":["calf"],"muscles":[{"id":"ac2bb610-6d0e-47eb-bb46-0f767196de7e","name":"Fibularis","commonName":"Peroneals","heads":[]},{"id":"5c8b7816-388c-4ccf-8251-b283fa7dbe77","name":"Gastrocnemius","commonName":"Calf","heads":["Lateral (Outer)","Medial (Inner)"]},{"id":"98180f1c-d623-4982-8955-8c93cff2c7f1","name":"Soleus","commonName":"Soleus","heads":[]}]},{"id":"7a45a47c-f008-42e3-977b-9529dcdcf6b9","name":"Chest","aliases":["pecs","pectorals"],"muscles":[{"id":"ffd76ee8-7633-4062-9c91-9092d637567a","name":"Pectoralis major","commonName":"Pecs","heads":["Clavicular (Upper)","Sternal (Lower)"]},{"id":"6be0d058-5813-49b8-aa58-634171adbee0","name":"Pectoralis minor","commonName":"Pectoralis minor","heads":[]}]},{"id":"a511ad30-3e1e-45cf-af7a-320442237f77","name":"Forearms","aliases":["grip"],"muscles":[{"id":"a68e0b8c-ff6f-4c21-8451-c9c0e9d46f3a","name":"Brachioradialis","commonName":"Brachioradialis","heads":[]},{"id":"94c6ab8c-0240-4d0f-9122-37433f504d1a","name":"Wrist extensors","commonName":"Wrist extensors","heads":[]},{"id":"96f81fc5-ad42-4a77-a8e9-52306524ca83","name":"Wrist flexors","commonName":"Wrist flexors","heads":[]}]},{"id":"cb8739ab-8985-4c16-9075-8eb05516e0f2","name":"Glutes","aliases":["butt","buttocks"],"muscles":[{"id":"a66ad74a-12ee-47ed-8b3a-0a1f5e0f00ee","name":"Deep hip external rotators","commonName":"Deep hip external rotators","heads":[]},{"id":"2961d054-2624-4a43-af1f-91d2ba18f0a2","name":"Gluteus maximus","commonName":"Glutes","heads":[]},{"id":"4badc855-240c-432e-ad04-57ff8ee03031","name":"Gluteus medius","commonName":"Side glutes","heads":[]},{"id":"34ac5a32-9f01-4663-8e6d-6bf7c0b78226","name":"Gluteus minimus","commonName":"Gluteus minimus","heads":[]}]},{"id":"47aa85fd-a051-46a8-9176-5c29d48d9701","name":"Hamstrings","aliases":["hams","back of thigh"],"muscles":[{"id":"1800ee40-9e19-44ed-9a0f-f067bbcb4179","name":"Biceps femoris","commonName":"Outer hamstring","heads":["Long","Short"]},{"id":"715268ae-27fa-4f70-8827-3f3e50ac5584","name":"Semimembranosus","commonName":"Inner hamstring","heads":[]},{"id":"35dc6992-fd35-4d69-988b-9bb27811b514","name":"Semitendinosus","commonName":"Inner hamstring","heads":[]}]},{"id":"76dbb7a1-51f0-44d2-a422-7c5ede672314","name":"Hip flexors","aliases":["hip flexor"],"muscles":[{"id":"a9f8901d-72f6-4832-82a1-619abcf2b5a4","name":"Iliopsoas","commonName":"Psoas","heads":[]},{"id":"6f0a53be-775f-4223-81ca-c7fbfe81402e","name":"Sartorius","commonName":"Sartorius","heads":[]},{"id":"8e3d2904-aea5-4066-8412-93c11213376e","name":"Tensor fasciae latae","commonName":"TFL","heads":[]}]},{"id":"59888fcc-10ff-4a23-bbd3-79419d25b0d6","name":"Lats","aliases":["latissimus","wings"],"muscles":[{"id":"b9df3ef0-8908-40c2-9b35-47643f775289","name":"Latissimus dorsi","commonName":"Lats","heads":[]},{"id":"1bf9b145-3a48-4455-8c31-fc734cab921b","name":"Teres major","commonName":"Teres major","heads":[]}]},{"id":"9e460c4b-ffcc-43b2-86a9-d424d0faf1f3","name":"Lower back","aliases":["lumbar","spinal erectors"],"muscles":[{"id":"d834254a-010e-4443-ba19-8287fa1219ee","name":"Erector spinae","commonName":"Spinal erectors","heads":[]}]},{"id":"6af817af-3514-4489-9c3c-240bf413ac9d","name":"Neck","aliases":[],"muscles":[{"id":"4834315f-22d9-4c09-957a-fa3c53d98b0a","name":"Splenius","commonName":"Back of the neck","heads":[]},{"id":"9f1cb5ed-1389-40ff-8dd4-6008a0ce9f5d","name":"Sternocleidomastoid","commonName":"Front neck","heads":[]}]},{"id":"622d924b-b277-4733-bd99-2033f4699c30","name":"Obliques","aliases":["side abs","love handles"],"muscles":[{"id":"62b37456-9249-4001-8057-5a9fa19fa053","name":"Obliques","commonName":"Obliques","heads":[]}]},{"id":"5dc033ad-f601-48c6-b007-6d7f623b8a12","name":"Quadriceps","aliases":["quads","thighs"],"muscles":[{"id":"7f7d0edb-abe7-4e1f-85ca-2808db5142ed","name":"Quadriceps femoris","commonName":"Quads","heads":["Rectus femoris","Vastus intermedius","Vastus lateralis","Vastus medialis"]}]},{"id":"17aede9b-5da0-4af3-82a2-50cedbd20451","name":"Rotator cuff","aliases":["cuff"],"muscles":[{"id":"28124bee-c7c8-4c85-8ef1-3ddb98335565","name":"Infraspinatus","commonName":"Infraspinatus","heads":[]},{"id":"336dca8b-588e-4700-9f34-205a344313c7","name":"Subscapularis","commonName":"Subscapularis","heads":[]},{"id":"65db3079-20d9-4972-b59e-d0cb72f85f14","name":"Supraspinatus","commonName":"Supraspinatus","heads":[]},{"id":"ec7cf25e-b28e-45cd-be08-3aff2145204d","name":"Teres minor","commonName":"Teres minor","heads":[]}]},{"id":"b82b9910-22d9-4827-ab95-40204015075a","name":"Serratus","aliases":["serratus anterior","boxer muscle"],"muscles":[{"id":"2b0d8403-caa8-4a7d-9390-b0d6b7fff096","name":"Serratus anterior","commonName":"Serratus","heads":["Inferior","Intermediate","Superior"]}]},{"id":"19d1fcbf-982c-4337-890d-9ef966bd94f2","name":"Shoulders","aliases":["delts","deltoids"],"muscles":[{"id":"d0f075f6-831c-43b9-9749-15e1b74987be","name":"Deltoid","commonName":"Delts","heads":["Acromial (Lateral)","Clavicular (Anterior)","Scapular (Posterior)"]}]},{"id":"1c7bc935-15ed-4f62-971f-8dd1f51a2211","name":"Tibialis","aliases":["shins","tibs"],"muscles":[{"id":"125be4fd-035b-4bb6-85f4-99214cbf5d73","name":"Tibialis anterior","commonName":"Shin","heads":[]}]},{"id":"a9424fb2-1a96-40e8-a2b1-10bfc46140b2","name":"Trapezius","aliases":["traps"],"muscles":[{"id":"a8234b58-2ba6-4c7e-a6b4-1c8d06d9f461","name":"Levator scapulae","commonName":"Levator scapulae","heads":[]},{"id":"d1cba331-eab1-4e46-8315-ac5c0dfffe54","name":"Trapezius","commonName":"Traps","heads":["Inferior","Middle","Superior"]}]},{"id":"48f48c28-833f-430d-a128-933f1076cad4","name":"Triceps","aliases":["tris"],"muscles":[{"id":"28c8765b-55b5-4953-9c14-37a30c8dc0ba","name":"Anconeus","commonName":"Anconeus","heads":[]},{"id":"dec5954e-80b5-493b-8911-a73ef54d96ee","name":"Triceps brachii","commonName":"Triceps","heads":["Lateral","Long","Medial"]}]},{"id":"8de57eb8-2533-4644-b616-f7a5f2eb2c1d","name":"Upper back","aliases":["mid back","rhomboids"],"muscles":[{"id":"32182570-50f7-4001-81f6-31319beda8e8","name":"Rhomboid major","commonName":"Rhomboids","heads":[]},{"id":"780ef79e-6eda-4a8a-8123-ecbf2b346205","name":"Rhomboid minor","commonName":"Rhomboids","heads":[]}]}]}}}},"tags":["Muscles"]}},"/v2/exercises/search":{"get":{"operationId":"searchExercises","summary":"Search exercises","description":"Search the exercise catalog by what the user types, with filters and pagination.\n\n**What it understands:**\n- Words in any order, plural forms and spellings (`pushup`, `push-ups`, `curl biceps`)\n- Typos (`bech press`)\n- Abbreviations (`rdl`, `db curl`, `ohp`)\n- Muscles (`quads`, `lower back`, `abs no equipment`)\n\n**Ranking:** exact name first, then the words in the name, then in the rest of the exercise, weighed by how often the exercise is done and its level.\n\n**Default results:** the exercises people do. `include=all` adds the rare ones and the exercises of rehab, plyometrics, aerobics and warm-up; typing the name of a rare exercise finds it anyway.\n\n**Filters:** body part, equipment (several values, comma separated), muscle (by id, name or common name, with `muscleRole`), muscle group, family, tier, type, category, difficulty, purpose, force, tracking type, laterality. `ids` fetches up to 50 exercises by id or slug. `group=true` shows each movement once, with its variants counted under it.\n\n**Sort:** by relevance (default), `popularity`, `name` or `difficulty`.\n\n**Options:** `suggest=true` adds `suggestion`, the query put right when a word looks misspelled. `facets=true` adds `facets`, the count of the matches per category, difficulty, tier, equipment and muscle group. Both are off by default.\n\nWithout a query, the most popular exercises come first.","parameters":[{"name":"query","required":false,"in":"query","description":"Search query to filter exercises by name (case-insensitive)","schema":{"maxLength":100,"example":"bench press","type":"string"}},{"name":"bodyPart","required":false,"in":"query","description":"Filter by target body part","schema":{"$ref":"#/components/schemas/BodyPart"}},{"name":"type","required":false,"in":"query","description":"Filter by exercise type (compound or isolation)","schema":{"$ref":"#/components/schemas/Type"}},{"name":"limit","required":false,"in":"query","description":"Number of results to return","schema":{"minimum":1,"maximum":100,"default":20,"example":20,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Number of results to skip for pagination","schema":{"minimum":0,"maximum":1000,"default":0,"example":0,"type":"number"}},{"name":"equipment","required":false,"in":"query","description":"Equipment the exercise uses. Several values, separated by commas, give the exercises that use any of them.","schema":{"type":"array","items":{"$ref":"#/components/schemas/Equipment"}}},{"name":"muscle","required":false,"in":"query","description":"A muscle: its id, its name (`Pectoralis major`) or its common name (`Pecs`)","schema":{"maxLength":100,"type":"string"}},{"name":"muscleRole","required":false,"in":"query","description":"With `muscle`: `target` for the exercises it is the main mover of (default), `synergist` for those it helps, `any` for both","schema":{"default":"target","enum":["target","synergist","any"],"type":"string"}},{"name":"family","required":false,"in":"query","description":"Family of movements (`GET /v2/families`): `squat`, `bench-press`...","schema":{"maxLength":100,"type":"string"}},{"name":"tier","required":false,"in":"query","description":"How common the exercise is","schema":{"$ref":"#/components/schemas/ExerciseTier"}},{"name":"trackingType","required":false,"in":"query","description":"How a set is logged: weight and reps, time, distance...","schema":{"$ref":"#/components/schemas/TrackingType"}},{"name":"laterality","required":false,"in":"query","description":"How the sides work: both, one at a time, or taking turns","schema":{"$ref":"#/components/schemas/Laterality"}},{"name":"ids","required":false,"in":"query","description":"Exercises to fetch at once: up to 50 ids or slugs, separated by commas (`bench-press-barbell,squat-barbell`). The rare exercises are included.","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","description":"Order of the results. `relevance` is for a text search, the others sort the matches.","schema":{"default":"relevance","enum":["relevance","popularity","name","difficulty"],"type":"string"}},{"name":"category","required":false,"in":"query","description":"Kind of exercise","schema":{"$ref":"#/components/schemas/ExerciseCategory"}},{"name":"difficulty","required":false,"in":"query","description":"How hard the exercise is","schema":{"$ref":"#/components/schemas/Difficulty"}},{"name":"muscleGroup","required":false,"in":"query","description":"Muscle group the exercise works the most (`GET /v2/muscle-groups`), e.g. `Quadriceps`","schema":{"type":"string"}},{"name":"purpose","required":false,"in":"query","description":"Purpose of the exercise: rehab, yoga, plyometrics...","schema":{"$ref":"#/components/schemas/Purpose"}},{"name":"force","required":false,"in":"query","description":"Push, pull or static","schema":{"$ref":"#/components/schemas/MovementForce"}},{"name":"include","required":false,"in":"query","description":"`default` shows the exercises people do; `all` adds the rare ones and the exercises of rehab, plyometrics, aerobics and warm-up","schema":{"default":"default","enum":["default","all"],"type":"string"}},{"name":"group","required":false,"in":"query","description":"Shows each movement once, with its variants counted under it","schema":{"default":false,"type":"boolean"}},{"name":"suggest","required":false,"in":"query","description":"Adds `suggestion` to the answer when a word of the query looks misspelled: the query put right, for a \"Did you mean\" line","schema":{"default":false,"type":"boolean"}},{"name":"facets","required":false,"in":"query","description":"Adds `facets` to the answer: how many of the matches fall under each category, difficulty, tier, equipment and muscle group, to build filters","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"Exercises matching the search criteria","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchExercisesResponseDto"},"example":{"results":[{"id":"c2b6fccf-2c2c-43e1-aca3-a3cb73caa78b","name":"Bench Press (Barbell)","bodyPart":"Chest","slug":"bench-press-barbell","equipment":"Barbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest"],"tier":"Standard","popularity":100,"variantCount":26},{"id":"3f05cb6b-dfe4-4aaa-9e45-2cbb79ffbf20","name":"Bench Press (Dumbbell)","bodyPart":"Chest","slug":"bench-press-dumbbell","equipment":"Dumbbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest"],"tier":"Standard","popularity":90,"variantCount":22},{"id":"9f14802d-441a-42b4-bd23-79b1e2c89d0e","name":"Bench Press (Smith Machine)","bodyPart":"Chest","slug":"bench-press-smith-machine","equipment":"SmithMachine","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest"],"tier":"Standard","popularity":62,"variantCount":7},{"id":"d2204c30-e837-4fe8-88ed-843d424fb036","name":"Bench Press (Band)","bodyPart":"Chest","slug":"bench-press-band","equipment":"ResistanceBand","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest"],"tier":"Variant","popularity":30,"variantCount":2},{"id":"b0884130-ccad-466f-b591-8ab041e07098","name":"Seated Shoulder Press (Dumbbell)","bodyPart":"Shoulders","slug":"seated-shoulder-press-dumbbell","equipment":"Dumbbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Shoulders"],"tier":"Standard","popularity":88,"variantCount":7},{"id":"af3d6a16-23a2-42be-a486-fc2c00e66098","name":"Chest Press (Machine)","bodyPart":"Chest","slug":"chest-press-machine","equipment":"Machine","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest"],"tier":"Standard","popularity":85,"variantCount":5},{"id":"fa1aeaf9-98db-40e6-bb25-53fc0baecda6","name":"JM Bench Press (Barbell)","bodyPart":"Arms","slug":"jm-bench-press-barbell","equipment":"Barbell","category":"Strength","difficulty":"Advanced","primaryGroups":["Triceps"],"tier":"Variant","popularity":40,"variantCount":0},{"id":"862ee14b-25ef-451e-9eb8-9fac289e573d","name":"Seated Overhead Press (Barbell)","bodyPart":"Shoulders","slug":"seated-overhead-press-barbell","equipment":"Barbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Shoulders"],"tier":"Standard","popularity":60,"variantCount":2},{"id":"665bf233-5cad-4796-a2b9-51475e1d252c","name":"Seated Shoulder Press (Smith Machine)","bodyPart":"Shoulders","slug":"seated-shoulder-press-smith-machine","equipment":"SmithMachine","category":"Strength","difficulty":"Beginner","primaryGroups":["Shoulders"],"tier":"Standard","popularity":60,"variantCount":0},{"id":"5f233adc-25a2-4397-8a33-cbc016bbf40e","name":"Tate Press (Dumbbell)","bodyPart":"Arms","slug":"tate-press-dumbbell","equipment":"Dumbbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Triceps"],"tier":"Variant","popularity":35,"variantCount":0},{"id":"17dbbc4c-3e06-4d83-a849-d35be99ea75b","name":"Seated Shoulder Press (Band)","bodyPart":"Shoulders","slug":"seated-shoulder-press-band","equipment":"ResistanceBand","category":"Strength","difficulty":"Beginner","primaryGroups":["Shoulders"],"tier":"Variant","popularity":20,"variantCount":0},{"id":"17723cc2-9b9a-42c9-96c8-c585b50608fc","name":"Seated Shoulder Press (Kettlebell)","bodyPart":"Shoulders","slug":"seated-shoulder-press-kettlebell","equipment":"Kettlebell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Shoulders"],"tier":"Variant","popularity":20,"variantCount":0},{"id":"822d491e-3549-4773-ab4c-be8a01815ecf","name":"Bench Press (Cable)","bodyPart":"Chest","slug":"bench-press-cable","equipment":"Cable","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest"],"tier":"Niche","popularity":15,"variantCount":4},{"id":"6479d3fc-d3f9-45b4-85cc-7e5c2bbe3df8","name":"Bench Press (Kettlebell)","bodyPart":"Chest","slug":"bench-press-kettlebell","equipment":"Kettlebell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest"],"tier":"Niche","popularity":12,"variantCount":6},{"id":"128ec6b0-7fdf-40f9-83d4-6ea3f0b7f2fd","name":"Close-Grip Bench Press (EZ Bar)","bodyPart":"Arms","slug":"close-grip-bench-press-ez-bar","equipment":"EzBar","category":"Strength","difficulty":"Intermediate","primaryGroups":["Triceps","Chest"],"tier":"Niche","popularity":15,"variantCount":1},{"id":"b027405c-045f-420d-b81f-311e0207b4d7","name":"Pullover with Bench Press (Barbell)","bodyPart":"Chest","slug":"pullover-with-bench-press-barbell","equipment":"Barbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest"],"tier":"Niche","popularity":15,"variantCount":0},{"id":"03d9948e-76ad-488d-b2d2-eae6a3a268ea","name":"Triceps Press - Head Below Bench","bodyPart":"Arms","slug":"triceps-press-head-below-bench","equipment":"Bodyweight","category":"Strength","difficulty":"Intermediate","primaryGroups":["Triceps"],"tier":"Niche","popularity":12,"variantCount":0},{"id":"cc96ff52-f930-48ac-9443-e8081685a4d6","name":"Shrug - Bench Press Machine (Machine)","bodyPart":"Back","slug":"shrug-bench-press-machine-machine","equipment":"Machine","category":"Strength","difficulty":"Beginner","primaryGroups":["Trapezius"],"tier":"Niche","popularity":10,"variantCount":0},{"id":"c741f359-a3eb-49d5-8666-ad3124629027","name":"Svend Bench Press (Weighted)","bodyPart":"Chest","slug":"svend-bench-press-weighted","equipment":"Weighted","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest"],"tier":"Niche","popularity":8,"variantCount":0},{"id":"0576d558-b98e-4ebe-9d14-810cde424678","name":"Calf Raise - Bench Press Machine (Machine)","bodyPart":"Legs","slug":"calf-raise-bench-press-machine-machine","equipment":"Machine","category":"Strength","difficulty":"Beginner","primaryGroups":["Calves"],"tier":"Niche","popularity":5,"variantCount":0}],"total":20,"count":20,"facets":{"category":[{"value":"Strength","count":102}],"difficulty":[{"value":"Intermediate","count":72},{"value":"Beginner","count":27},{"value":"Advanced","count":3}],"tier":[{"value":"Niche","count":52},{"value":"Variant","count":35},{"value":"Standard","count":15}],"equipment":[{"value":"Bench","count":88},{"value":"Barbell","count":32},{"value":"Dumbbell","count":32},{"value":"Kettlebell","count":9},{"value":"SmithMachine","count":9},{"value":"Machine","count":8},{"value":"ResistanceBand","count":8},{"value":"Cable","count":5},{"value":"EzBar","count":2},{"value":"Bodyweight","count":1},{"value":"StabilityBall","count":1},{"value":"Weighted","count":1}],"muscleGroup":[{"value":"Chest","count":84},{"value":"Shoulders","count":28},{"value":"Triceps","count":27},{"value":"Calves","count":1},{"value":"Trapezius","count":1}]}}}}},"400":{"description":"Invalid search parameters"}},"tags":["Exercises"],"x-codeSamples":[{"lang":"typescript","label":"TypeScript","source":"type ExerciseSummary = {\n id: string\n slug: string | null\n name: string\n equipment?: string\n difficulty?: string | null\n primaryGroups?: string[]\n}\n\ntype SearchResponse = {\n total: number\n count: number\n results: ExerciseSummary[]\n}\n\nexport async function searchExercises(query: string, limit = 20): Promise {\n const url = new URL('https://api.gymfit-api.com/v2/exercises/search')\n url.search = new URLSearchParams({ query, limit: String(limit) }).toString()\n\n const response = await fetch(url, {\n headers: { 'X-API-Key': process.env.GYMFIT_API_KEY ?? '' }\n })\n\n if (!response.ok) {\n const problem = await response.json()\n throw new Error(`${problem.code}: ${problem.detail}`)\n }\n\n return response.json()\n}"},{"lang":"swift","label":"Swift","source":"import Foundation\n\nstruct ExerciseSummary: Decodable {\n let id: String\n let slug: String?\n let name: String\n let equipment: String?\n let difficulty: String?\n let primaryGroups: [String]?\n}\n\nstruct SearchResponse: Decodable {\n let total: Int\n let count: Int\n let results: [ExerciseSummary]\n}\n\nlet apiKey = \"YOUR_API_KEY\"\n\nfunc searchExercises(_ query: String, limit: Int = 20) async throws -> SearchResponse {\n var components = URLComponents(string: \"https://api.gymfit-api.com/v2/exercises/search\")!\n components.queryItems = [\n URLQueryItem(name: \"query\", value: query),\n URLQueryItem(name: \"limit\", value: String(limit))\n ]\n var request = URLRequest(url: components.url!)\n request.setValue(apiKey, forHTTPHeaderField: \"X-API-Key\")\n\n let (data, response) = try await URLSession.shared.data(for: request)\n guard (response as? HTTPURLResponse)?.statusCode == 200 else {\n throw URLError(.badServerResponse)\n }\n return try JSONDecoder().decode(SearchResponse.self, from: data)\n}"},{"lang":"kotlin","label":"Kotlin","source":"import kotlinx.serialization.Serializable\nimport kotlinx.serialization.json.Json\nimport okhttp3.HttpUrl.Companion.toHttpUrl\nimport okhttp3.OkHttpClient\nimport okhttp3.Request\n\n@Serializable\ndata class ExerciseSummary(\n val id: String,\n val slug: String? = null,\n val name: String,\n val equipment: String? = null,\n val difficulty: String? = null,\n val primaryGroups: List = emptyList()\n)\n\n@Serializable\ndata class SearchResponse(val total: Int, val count: Int, val results: List)\n\nprivate val client = OkHttpClient()\nprivate val json = Json { ignoreUnknownKeys = true }\n\n// Blocking: call it from a coroutine on Dispatchers.IO\nfun searchExercises(query: String, limit: Int = 20): SearchResponse {\n val url = \"https://api.gymfit-api.com/v2/exercises/search\".toHttpUrl().newBuilder()\n .addQueryParameter(\"query\", query)\n .addQueryParameter(\"limit\", limit.toString())\n .build()\n val request = Request.Builder()\n .url(url)\n .header(\"X-API-Key\", BuildConfig.GYMFIT_API_KEY)\n .build()\n\n client.newCall(request).execute().use { response ->\n check(response.isSuccessful) { \"GymFit API: ${response.code}\" }\n return json.decodeFromString(response.body!!.string())\n }\n}"},{"lang":"dart","label":"Dart (Flutter)","source":"import 'dart:convert';\n\nimport 'package:http/http.dart' as http;\n\nconst apiKey = String.fromEnvironment('GYMFIT_API_KEY');\n\nclass ExerciseSummary {\n ExerciseSummary({\n required this.id,\n required this.name,\n this.slug,\n this.equipment,\n this.primaryGroups = const [],\n });\n\n factory ExerciseSummary.fromJson(Map json) => ExerciseSummary(\n id: json['id'] as String,\n name: json['name'] as String,\n slug: json['slug'] as String?,\n equipment: json['equipment'] as String?,\n primaryGroups: (json['primaryGroups'] as List? ?? []).cast(),\n );\n\n final String id;\n final String name;\n final String? slug;\n final String? equipment;\n final List primaryGroups;\n}\n\nFuture> searchExercises(String query, {int limit = 20}) async {\n final uri = Uri.https('api.gymfit-api.com', '/v2/exercises/search', {\n 'query': query,\n 'limit': '$limit',\n });\n final response = await http.get(uri, headers: {'X-API-Key': apiKey});\n\n if (response.statusCode != 200) {\n throw Exception('GymFit API: ${response.statusCode} ${response.body}');\n }\n\n final body = jsonDecode(response.body) as Map;\n return (body['results'] as List)\n .map((item) => ExerciseSummary.fromJson(item as Map))\n .toList();\n}"}]}},"/v2/exercises/suggest":{"get":{"operationId":"suggestExercises","summary":"Suggest exercises while typing","description":"Exercises to offer under a search box while a person types: what is typed so far (two characters at least) gives the most popular exercises whose name or text starts or holds it.\n\n**Not billable:** a search box calls this on every key. It counts in the rate limit but never in the monthly quota; a click on a suggestion is a billable `GET /v2/exercises/{id}`.\n\nFor the full result page, use `GET /v2/exercises/search`.","parameters":[{"name":"q","required":true,"in":"query","description":"The beginning of what is typed, two characters at least","schema":{"minLength":2,"maxLength":100,"example":"bench pr","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Number of suggestions","schema":{"minimum":1,"maximum":10,"default":8,"type":"number"}}],"responses":{"200":{"description":"Suggestions, the most popular first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuggestExercisesResponseDto"},"example":{"results":[{"id":"c2b6fccf-2c2c-43e1-aca3-a3cb73caa78b","slug":"bench-press-barbell","name":"Bench Press (Barbell)","equipment":"Barbell","category":"Strength"},{"id":"3f05cb6b-dfe4-4aaa-9e45-2cbb79ffbf20","slug":"bench-press-dumbbell","name":"Bench Press (Dumbbell)","equipment":"Dumbbell","category":"Strength"},{"id":"a1281637-139d-4864-903b-67d62037c16e","slug":"incline-bench-press-barbell","name":"Incline Bench Press (Barbell)","equipment":"Barbell","category":"Strength"},{"id":"e48f6911-2a0d-45b5-b854-61aca0570173","slug":"incline-bench-press-dumbbell","name":"Incline Bench Press (Dumbbell)","equipment":"Dumbbell","category":"Strength"},{"id":"8a764a28-b2d8-496e-9d08-fa352280b178","slug":"close-grip-bench-press-barbell","name":"Close Grip Bench Press (Barbell)","equipment":"Barbell","category":"Strength"},{"id":"c3eece11-94f5-49fc-9789-a03eb217e34b","slug":"decline-bench-press-barbell","name":"Decline Bench Press (Barbell)","equipment":"Barbell","category":"Strength"},{"id":"ca6c6d78-58ec-4984-b02d-68d784acc8a5","slug":"incline-bench-press-smith-machine","name":"Incline Bench Press (Smith Machine)","equipment":"SmithMachine","category":"Strength"},{"id":"9f14802d-441a-42b4-bd23-79b1e2c89d0e","slug":"bench-press-smith-machine","name":"Bench Press (Smith Machine)","equipment":"SmithMachine","category":"Strength"}],"count":8}}}},"400":{"description":"Less than two characters, or invalid parameters"}},"tags":["Exercises"]}},"/v2/exercises/{id}":{"get":{"operationId":"getExerciseById","summary":"Get exercise details","description":"Retrieve comprehensive information about a specific exercise.\n\n**Includes:**\n- Complete exercise metadata (name, equipment, target body part)\n- Muscle engagement details (target and synergist muscles)\n- Step-by-step instructions\n- Exercise variations\n\nThe exercise is found by its id or its slug (`bench-press-barbell`). The muscles it works can be drawn with `GET /v2/exercises/{id}/heatmap`.\n\n**Use cases:**\n- Display exercise details in workout builder\n- Show proper form and technique\n- Suggest exercise variations","parameters":[{"name":"id","required":true,"in":"path","description":"Id (UUID) or slug of the exercise","schema":{"example":"bench-press-barbell","type":"string"}}],"responses":{"200":{"description":"Detailed exercise information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExerciseDetailDto"},"example":{"id":"c2b6fccf-2c2c-43e1-aca3-a3cb73caa78b","name":"Bench Press (Barbell)","slug":"bench-press-barbell","bodyPart":"Chest","equipment":"Barbell","type":"Compound","description":"The classic flat-bench press with a barbell, a staple for pressing strength. It works the chest, the front delts and the triceps.","difficulty":"Intermediate","category":"Strength","force":"Push","trackingType":"WeightReps","laterality":"Bilateral","tier":"Standard","popularity":100,"purposes":["Strength"],"tips":["Keep your shoulder blades pulled together and your feet planted throughout.","Press the bar back in a slight arc so it finishes over your shoulders."],"mistakes":["Bouncing the bar off the chest.","Lifting the hips off the bench to push the bar up.","Flaring the elbows straight out to the sides."],"aliases":["Weighted Bench Press (Barbell)"],"primaryGroups":["Chest"],"secondaryGroups":["Shoulders","Triceps"],"family":{"id":"bench-press","label":"Bench press"},"equipments":[{"equipment":"Barbell","main":true},{"equipment":"Bench","main":false}],"targetMuscles":[{"id":"ffd76ee8-7633-4062-9c91-9092d637567a","name":"Pectoralis major","commonName":"Pecs","bodyPart":"Chest","group":"Chest"}],"secondaryMuscles":[{"id":"d0f075f6-831c-43b9-9749-15e1b74987be","name":"Deltoid","commonName":"Delts","bodyPart":"Shoulders","group":"Shoulders"},{"id":"dec5954e-80b5-493b-8911-a73ef54d96ee","name":"Triceps brachii","commonName":"Triceps","bodyPart":"Arms","group":"Triceps"}],"instructions":[{"order":1,"description":"Lie on a flat bench with your eyes under the bar, feet flat on the floor and shoulder blades pulled together."},{"order":2,"description":"Grip the bar a little wider than shoulder width, palms facing away, and unrack it over your chest with straight arms."},{"order":3,"description":"Inhale and lower the bar under control to your mid-chest, elbows at about 45 degrees from your body."},{"order":4,"description":"Pause briefly with the bar just touching your chest."},{"order":5,"description":"Exhale and press the bar back up until your arms are straight."},{"order":6,"description":"Repeat, then rack the bar when you finish."}],"base":null,"variations":[{"id":"a1281637-139d-4864-903b-67d62037c16e","name":"Incline Bench Press (Barbell)","bodyPart":"Chest","slug":"incline-bench-press-barbell","equipment":"Barbell","difficulty":"Intermediate","tier":"Standard","popularity":88},{"id":"8a764a28-b2d8-496e-9d08-fa352280b178","name":"Close Grip Bench Press (Barbell)","bodyPart":"Arms","slug":"close-grip-bench-press-barbell","equipment":"Barbell","difficulty":"Intermediate","tier":"Standard","popularity":72},{"id":"c3eece11-94f5-49fc-9789-a03eb217e34b","name":"Decline Bench Press (Barbell)","bodyPart":"Chest","slug":"decline-bench-press-barbell","equipment":"Barbell","difficulty":"Intermediate","tier":"Standard","popularity":65},{"id":"864c3482-fe80-4740-85c7-1c3fdfeba898","name":"Pause Bench Press (Barbell)","bodyPart":"Chest","slug":"pause-bench-press-barbell","equipment":"Barbell","difficulty":"Intermediate","tier":"Variant","popularity":45},{"id":"859bb806-b4d8-4200-aea1-f9758e412ed1","name":"Floor Chest Press (Barbell)","bodyPart":"Chest","slug":"floor-chest-press-barbell","equipment":"Barbell","difficulty":"Intermediate","tier":"Variant","popularity":40},{"id":"b1f8f62e-fa66-46cc-bb15-4ec670942d35","name":"Wide Bench Press (Barbell)","bodyPart":"Chest","slug":"wide-bench-press-barbell","equipment":"Barbell","difficulty":"Intermediate","tier":"Variant","popularity":35},{"id":"2957dbe9-bb1c-495e-bdf2-ab85c972ce0a","name":"Reverse Grip Bench Press (Barbell)","bodyPart":"Chest","slug":"reverse-grip-bench-press-barbell","equipment":"Barbell","difficulty":"Intermediate","tier":"Variant","popularity":25},{"id":"f0384fc8-ac7f-4943-98dd-9c0fb38e690c","name":"Bench Press Against Chains (Barbell)","bodyPart":"Chest","slug":"bench-press-against-chains-barbell","equipment":"Barbell","difficulty":"Intermediate","tier":"Variant","popularity":20},{"id":"7cffe3db-8bc3-418b-bc83-5f9f844a3985","name":"Banded Bench Press (Barbell)","bodyPart":"Chest","slug":"banded-bench-press-barbell","equipment":"Barbell","difficulty":"Intermediate","tier":"Variant","popularity":20}],"alternatives":[{"id":"3f05cb6b-dfe4-4aaa-9e45-2cbb79ffbf20","name":"Bench Press (Dumbbell)","bodyPart":"Chest","slug":"bench-press-dumbbell","equipment":"Dumbbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest"],"tier":"Standard","popularity":90,"score":0.96,"reasons":["same-target-muscles","same-movement","other-equipment"]},{"id":"af3d6a16-23a2-42be-a486-fc2c00e66098","name":"Chest Press (Machine)","bodyPart":"Chest","slug":"chest-press-machine","equipment":"Machine","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest"],"tier":"Standard","popularity":85,"score":0.93,"reasons":["same-target-muscles","same-movement","other-equipment","easier"]},{"id":"dda1be2c-e910-4115-a864-0864b119c179","name":"Push-up","bodyPart":"Chest","slug":"push-up","equipment":"Bodyweight","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest"],"tier":"Standard","popularity":97,"score":0.93,"reasons":["same-target-muscles","no-equipment","easier"]},{"id":"84177edb-a08d-4756-8be7-2bf6515c91e4","name":"Chest Dip","bodyPart":"Chest","slug":"chest-dip","equipment":"Bodyweight","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest","Triceps"],"tier":"Standard","popularity":85,"score":0.86,"reasons":["similar-muscles","no-equipment"]},{"id":"918ceabc-3449-4184-b4f9-c5bcf85e0a14","name":"Chest Press (Suspension)","bodyPart":"Chest","slug":"chest-press-suspension","equipment":"SuspensionTrainer","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest"],"tier":"Standard","popularity":55,"score":0.75,"reasons":["same-target-muscles","other-equipment"]},{"id":"d8439f9b-0ab6-4704-9447-1109842afa62","name":"Seated Dip (Machine)","bodyPart":"Chest","slug":"seated-dip-machine","equipment":"Machine","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest","Triceps"],"tier":"Standard","popularity":55,"score":0.74,"reasons":["similar-muscles","other-equipment","easier"]}],"easier":[{"id":"af3d6a16-23a2-42be-a486-fc2c00e66098","name":"Chest Press (Machine)","bodyPart":"Chest","slug":"chest-press-machine","equipment":"Machine","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest"],"tier":"Standard","popularity":85,"step":10},{"id":"77714948-0022-410c-a18a-53cd85224fa7","name":"Incline Chest Press (Machine)","bodyPart":"Chest","slug":"incline-chest-press-machine","equipment":"Machine","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest","Shoulders"],"tier":"Standard","popularity":65,"step":10},{"id":"ca6c6d78-58ec-4984-b02d-68d784acc8a5","name":"Incline Bench Press (Smith Machine)","bodyPart":"Chest","slug":"incline-bench-press-smith-machine","equipment":"SmithMachine","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest","Shoulders"],"tier":"Standard","popularity":65,"step":10}],"harder":[]}}}},"400":{"description":"Invalid id or slug"},"404":{"description":"Exercise not found"}},"tags":["Exercises"],"x-codeSamples":[{"lang":"typescript","label":"TypeScript","source":"type Muscle = {\n id: string\n name: string\n commonName: string | null\n group: string | null\n}\n\ntype Exercise = {\n id: string\n slug: string | null\n name: string\n difficulty?: string | null\n instructions: { order: number; description: string }[]\n targetMuscles: Muscle[]\n secondaryMuscles: Muscle[]\n tips?: string[]\n}\n\n/** null when the exercise does not exist */\nexport async function getExercise(idOrSlug: string): Promise {\n const response = await fetch(\n `https://api.gymfit-api.com/v2/exercises/${encodeURIComponent(idOrSlug)}`,\n { headers: { 'X-API-Key': process.env.GYMFIT_API_KEY ?? '' } }\n )\n\n if (response.status === 404) {\n return null\n }\n if (!response.ok) {\n throw new Error(`GymFit API: ${response.status}`)\n }\n\n return response.json()\n}"},{"lang":"swift","label":"Swift","source":"import Foundation\n\nstruct Muscle: Decodable {\n let id: String\n let name: String\n let commonName: String?\n let group: String?\n}\n\nstruct Step: Decodable {\n let order: Int\n let description: String\n}\n\nstruct Exercise: Decodable {\n let id: String\n let slug: String?\n let name: String\n let difficulty: String?\n let instructions: [Step]\n let targetMuscles: [Muscle]\n let secondaryMuscles: [Muscle]\n let tips: [String]?\n}\n\n/// nil when the exercise does not exist (apiKey: see the search)\nfunc getExercise(_ idOrSlug: String) async throws -> Exercise? {\n let url = URL(string: \"https://api.gymfit-api.com/v2/exercises/\\(idOrSlug)\")!\n var request = URLRequest(url: url)\n request.setValue(apiKey, forHTTPHeaderField: \"X-API-Key\")\n\n let (data, response) = try await URLSession.shared.data(for: request)\n switch (response as? HTTPURLResponse)?.statusCode {\n case 200: return try JSONDecoder().decode(Exercise.self, from: data)\n case 404: return nil\n default: throw URLError(.badServerResponse)\n }\n}"},{"lang":"kotlin","label":"Kotlin","source":"import kotlinx.serialization.Serializable\n\n@Serializable\ndata class Muscle(\n val id: String,\n val name: String,\n val commonName: String? = null,\n val group: String? = null\n)\n\n@Serializable\ndata class Step(val order: Int, val description: String)\n\n@Serializable\ndata class Exercise(\n val id: String,\n val slug: String? = null,\n val name: String,\n val difficulty: String? = null,\n val instructions: List,\n val targetMuscles: List,\n val secondaryMuscles: List,\n val tips: List = emptyList()\n)\n\n// null when the exercise does not exist. client and json: see the search.\n// Blocking: call it from a coroutine on Dispatchers.IO\nfun getExercise(idOrSlug: String): Exercise? {\n val request = Request.Builder()\n .url(\"https://api.gymfit-api.com/v2/exercises/$idOrSlug\")\n .header(\"X-API-Key\", BuildConfig.GYMFIT_API_KEY)\n .build()\n\n client.newCall(request).execute().use { response ->\n if (response.code == 404) return null\n check(response.isSuccessful) { \"GymFit API: ${response.code}\" }\n return json.decodeFromString(response.body!!.string())\n }\n}"},{"lang":"dart","label":"Dart (Flutter)","source":"import 'dart:convert';\n\nimport 'package:http/http.dart' as http;\n\nclass Muscle {\n Muscle({required this.name, this.commonName});\n\n factory Muscle.fromJson(Map json) =>\n Muscle(name: json['name'] as String, commonName: json['commonName'] as String?);\n\n final String name;\n final String? commonName;\n}\n\nclass Exercise {\n Exercise({required this.name, required this.steps, required this.targetMuscles});\n\n factory Exercise.fromJson(Map json) => Exercise(\n name: json['name'] as String,\n steps: [\n for (final step in json['instructions'] as List)\n (step as Map)['description'] as String,\n ],\n targetMuscles: [\n for (final muscle in json['targetMuscles'] as List)\n Muscle.fromJson(muscle as Map),\n ],\n );\n\n final String name;\n final List steps;\n final List targetMuscles;\n}\n\n/// null when the exercise does not exist (apiKey: see the search)\nFuture getExercise(String idOrSlug) async {\n final uri = Uri.https('api.gymfit-api.com', '/v2/exercises/$idOrSlug');\n final response = await http.get(uri, headers: {'X-API-Key': apiKey});\n\n if (response.statusCode == 404) return null;\n if (response.statusCode != 200) {\n throw Exception('GymFit API: ${response.statusCode}');\n }\n return Exercise.fromJson(jsonDecode(response.body) as Map);\n}"}]}},"/v2/exercises/{id}/alternatives":{"get":{"operationId":"getAlternatives","summary":"Get alternative exercises","description":"Find alternative exercises based on similarity scoring.\n\n**Similarity Algorithm:**\n- Muscle engagement similarity (70% weight): Uses Jaccard index to compare target and synergist muscles\n- Name similarity (30% weight): Fuzzy string matching\n- Minimum similarity threshold: 0.7 (70%)\n\n**Results are sorted by similarity score (highest first)**\n\n**Use cases:**\n- Suggest alternatives when equipment is unavailable\n- Provide exercise variety for progressive overload\n- Help with injury adaptations","parameters":[{"name":"id","required":true,"in":"path","description":"Id (UUID) or slug of the source exercise","schema":{"example":"bench-press-barbell","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of alternatives to return","schema":{"example":10,"type":"number"}}],"responses":{"200":{"description":"List of alternative exercises","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ExerciseAlternativeDto"}},"example":[{"id":"3f05cb6b-dfe4-4aaa-9e45-2cbb79ffbf20","name":"Bench Press (Dumbbell)","bodyPart":"Chest","slug":"bench-press-dumbbell","equipment":"Dumbbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest"],"tier":"Standard","popularity":90,"score":0.96,"reasons":["same-target-muscles","same-movement","other-equipment"]},{"id":"af3d6a16-23a2-42be-a486-fc2c00e66098","name":"Chest Press (Machine)","bodyPart":"Chest","slug":"chest-press-machine","equipment":"Machine","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest"],"tier":"Standard","popularity":85,"score":0.93,"reasons":["same-target-muscles","same-movement","other-equipment","easier"]},{"id":"dda1be2c-e910-4115-a864-0864b119c179","name":"Push-up","bodyPart":"Chest","slug":"push-up","equipment":"Bodyweight","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest"],"tier":"Standard","popularity":97,"score":0.93,"reasons":["same-target-muscles","no-equipment","easier"]},{"id":"84177edb-a08d-4756-8be7-2bf6515c91e4","name":"Chest Dip","bodyPart":"Chest","slug":"chest-dip","equipment":"Bodyweight","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest","Triceps"],"tier":"Standard","popularity":85,"score":0.86,"reasons":["similar-muscles","no-equipment"]},{"id":"918ceabc-3449-4184-b4f9-c5bcf85e0a14","name":"Chest Press (Suspension)","bodyPart":"Chest","slug":"chest-press-suspension","equipment":"SuspensionTrainer","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest"],"tier":"Standard","popularity":55,"score":0.75,"reasons":["same-target-muscles","other-equipment"]},{"id":"d8439f9b-0ab6-4704-9447-1109842afa62","name":"Seated Dip (Machine)","bodyPart":"Chest","slug":"seated-dip-machine","equipment":"Machine","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest","Triceps"],"tier":"Standard","popularity":55,"score":0.74,"reasons":["similar-muscles","other-equipment","easier"]}]}}},"404":{"description":"Source exercise not found"}},"tags":["Exercises"]}},"/v2/muscles/{id}/exercises":{"get":{"operationId":"getExercisesOfMuscle","summary":"List the exercises of a muscle","description":"The exercises that work a muscle, the most popular first.\n\nBy default the muscle is the main mover (`muscleRole=target`); `synergist` gives the exercises it only helps, `any` both.\n\nThe filters and the sort are those of `GET /v2/exercises/search`.","parameters":[{"name":"id","required":true,"in":"path","description":"Muscle UUID","schema":{"format":"uuid","type":"string"},"example":"ffd76ee8-7633-4062-9c91-9092d637567a"},{"name":"query","required":false,"in":"query","description":"Search query to filter exercises by name (case-insensitive)","schema":{"maxLength":100,"example":"bench press","type":"string"}},{"name":"type","required":false,"in":"query","description":"Filter by exercise type (compound or isolation)","schema":{"$ref":"#/components/schemas/Type"}},{"name":"limit","required":false,"in":"query","description":"Number of results to return","schema":{"minimum":1,"maximum":100,"default":20,"example":20,"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Number of results to skip for pagination","schema":{"minimum":0,"maximum":1000,"default":0,"example":0,"type":"number"}},{"name":"equipment","required":false,"in":"query","description":"Equipment the exercise uses. Several values, separated by commas, give the exercises that use any of them.","schema":{"type":"array","items":{"$ref":"#/components/schemas/Equipment"}}},{"name":"muscleRole","required":false,"in":"query","description":"With `muscle`: `target` for the exercises it is the main mover of (default), `synergist` for those it helps, `any` for both","schema":{"default":"target","enum":["target","synergist","any"],"type":"string"}},{"name":"tier","required":false,"in":"query","description":"How common the exercise is","schema":{"$ref":"#/components/schemas/ExerciseTier"}},{"name":"sort","required":false,"in":"query","description":"Order of the results. `relevance` is for a text search, the others sort the matches.","schema":{"default":"relevance","enum":["relevance","popularity","name","difficulty"],"type":"string"}},{"name":"category","required":false,"in":"query","description":"Kind of exercise","schema":{"$ref":"#/components/schemas/ExerciseCategory"}},{"name":"difficulty","required":false,"in":"query","description":"How hard the exercise is","schema":{"$ref":"#/components/schemas/Difficulty"}},{"name":"include","required":false,"in":"query","description":"`default` shows the exercises people do; `all` adds the rare ones and the exercises of rehab, plyometrics, aerobics and warm-up","schema":{"default":"default","enum":["default","all"],"type":"string"}}],"responses":{"200":{"description":"Exercises of the muscle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchExercisesResponseDto"},"example":{"results":[{"id":"c2b6fccf-2c2c-43e1-aca3-a3cb73caa78b","name":"Bench Press (Barbell)","bodyPart":"Chest","slug":"bench-press-barbell","equipment":"Barbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest"],"tier":"Standard","popularity":100},{"id":"3f05cb6b-dfe4-4aaa-9e45-2cbb79ffbf20","name":"Bench Press (Dumbbell)","bodyPart":"Chest","slug":"bench-press-dumbbell","equipment":"Dumbbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest"],"tier":"Standard","popularity":90},{"id":"9f14802d-441a-42b4-bd23-79b1e2c89d0e","name":"Bench Press (Smith Machine)","bodyPart":"Chest","slug":"bench-press-smith-machine","equipment":"SmithMachine","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest"],"tier":"Standard","popularity":62},{"id":"a1281637-139d-4864-903b-67d62037c16e","name":"Incline Bench Press (Barbell)","bodyPart":"Chest","slug":"incline-bench-press-barbell","equipment":"Barbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest","Shoulders"],"tier":"Standard","popularity":88},{"id":"e48f6911-2a0d-45b5-b854-61aca0570173","name":"Incline Bench Press (Dumbbell)","bodyPart":"Chest","slug":"incline-bench-press-dumbbell","equipment":"Dumbbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest","Shoulders"],"tier":"Standard","popularity":88},{"id":"d2204c30-e837-4fe8-88ed-843d424fb036","name":"Bench Press (Band)","bodyPart":"Chest","slug":"bench-press-band","equipment":"ResistanceBand","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest"],"tier":"Variant","popularity":30},{"id":"8a764a28-b2d8-496e-9d08-fa352280b178","name":"Close Grip Bench Press (Barbell)","bodyPart":"Arms","slug":"close-grip-bench-press-barbell","equipment":"Barbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Triceps","Chest"],"tier":"Standard","popularity":72},{"id":"c3eece11-94f5-49fc-9789-a03eb217e34b","name":"Decline Bench Press (Barbell)","bodyPart":"Chest","slug":"decline-bench-press-barbell","equipment":"Barbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest"],"tier":"Standard","popularity":65},{"id":"ca6c6d78-58ec-4984-b02d-68d784acc8a5","name":"Incline Bench Press (Smith Machine)","bodyPart":"Chest","slug":"incline-bench-press-smith-machine","equipment":"SmithMachine","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest","Shoulders"],"tier":"Standard","popularity":65},{"id":"864c3482-fe80-4740-85c7-1c3fdfeba898","name":"Pause Bench Press (Barbell)","bodyPart":"Chest","slug":"pause-bench-press-barbell","equipment":"Barbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest"],"tier":"Variant","popularity":45},{"id":"cad168c4-cb0b-424d-9b3b-b054cac28b94","name":"Decline Bench Press (Dumbbell)","bodyPart":"Chest","slug":"decline-bench-press-dumbbell","equipment":"Dumbbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest"],"tier":"Variant","popularity":45},{"id":"8aee8654-f607-4b38-9377-4fd36331caec","name":"Neutral Grip Bench Press (Dumbbell)","bodyPart":"Chest","slug":"neutral-grip-bench-press-dumbbell","equipment":"Dumbbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest"],"tier":"Variant","popularity":45},{"id":"af3d6a16-23a2-42be-a486-fc2c00e66098","name":"Chest Press (Machine)","bodyPart":"Chest","slug":"chest-press-machine","equipment":"Machine","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest"],"tier":"Standard","popularity":85},{"id":"f0384fc8-ac7f-4943-98dd-9c0fb38e690c","name":"Bench Press Against Chains (Barbell)","bodyPart":"Chest","slug":"bench-press-against-chains-barbell","equipment":"Barbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest"],"tier":"Variant","popularity":20},{"id":"b1f8f62e-fa66-46cc-bb15-4ec670942d35","name":"Wide Bench Press (Barbell)","bodyPart":"Chest","slug":"wide-bench-press-barbell","equipment":"Barbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest"],"tier":"Variant","popularity":35},{"id":"add56274-140c-474a-9ab7-b02e7e04b3b6","name":"Close-Grip Bench Press (Smith Machine)","bodyPart":"Arms","slug":"close-grip-bench-press-smith-machine","equipment":"SmithMachine","category":"Strength","difficulty":"Beginner","primaryGroups":["Triceps","Chest"],"tier":"Variant","popularity":30},{"id":"77714948-0022-410c-a18a-53cd85224fa7","name":"Incline Chest Press (Machine)","bodyPart":"Chest","slug":"incline-chest-press-machine","equipment":"Machine","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest","Shoulders"],"tier":"Standard","popularity":65},{"id":"2957dbe9-bb1c-495e-bdf2-ab85c972ce0a","name":"Reverse Grip Bench Press (Barbell)","bodyPart":"Chest","slug":"reverse-grip-bench-press-barbell","equipment":"Barbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest","Triceps"],"tier":"Variant","popularity":25},{"id":"78af288e-af16-485f-9e88-937fe30ac6a7","name":"Decline Bench Press (Smith Machine)","bodyPart":"Chest","slug":"decline-bench-press-smith-machine","equipment":"SmithMachine","category":"Strength","difficulty":"Beginner","primaryGroups":["Chest"],"tier":"Variant","popularity":25},{"id":"7cffe3db-8bc3-418b-bc83-5f9f844a3985","name":"Banded Bench Press (Barbell)","bodyPart":"Chest","slug":"banded-bench-press-barbell","equipment":"Barbell","category":"Strength","difficulty":"Intermediate","primaryGroups":["Chest"],"tier":"Variant","popularity":20}],"total":84,"count":20}}}},"404":{"description":"Muscle not found"}},"tags":["Muscles"]}},"/v2/exercises/{id}/heatmap":{"get":{"operationId":"getExerciseHeatmap","summary":"Get the muscle heatmap of an exercise","description":"SVG image of the body, front and back, with the target and secondary muscles of the exercise highlighted. Colors can be set to match your app.","parameters":[{"name":"id","required":true,"in":"path","description":"Id (UUID) or slug of the exercise","schema":{"example":"bench-press-barbell","type":"string"}},{"name":"view","required":false,"in":"query","description":"Side of the body to draw","schema":{"default":"both","enum":["front","back","both"],"type":"string"}},{"name":"target","required":false,"in":"query","description":"Color of the target muscles (hex, the # is optional)","schema":{"pattern":"HEX_COLOR","example":"E53935","type":"string"}},{"name":"secondary","required":false,"in":"query","description":"Color of the secondary muscles (hex, the # is optional)","schema":{"pattern":"HEX_COLOR","example":"F6A26B","type":"string"}},{"name":"base","required":false,"in":"query","description":"Color of the muscles the exercise does not work (hex, the # is optional). Defaults to the colors of the drawing","schema":{"pattern":"HEX_COLOR","example":"D9D9D9","type":"string"}},{"name":"body","required":false,"in":"query","description":"Color of the body and of the lines between the muscles (hex, the # is optional). Defaults to the colors of the drawing","schema":{"pattern":"HEX_COLOR","example":"2B2B30","type":"string"}},{"name":"outline","required":false,"in":"query","description":"Color of the contour of the body (hex, the # is optional). Defaults to the colors of the drawing","schema":{"pattern":"HEX_COLOR","example":"45454D","type":"string"}}],"responses":{"200":{"description":"The heatmap, as an SVG image","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"400":{"description":"Invalid id, slug, view or color"},"404":{"description":"Exercise not found"}},"tags":["Exercises"],"x-codeSamples":[{"lang":"typescript","label":"TypeScript","source":"// The heatmap is an SVG that needs the key: fetch it, then show it as an image\nexport async function heatmapUrl(idOrSlug: string, view = 'both'): Promise {\n const response = await fetch(\n `https://api.gymfit-api.com/v2/exercises/${encodeURIComponent(idOrSlug)}/heatmap?view=${view}`,\n { headers: { 'X-API-Key': process.env.GYMFIT_API_KEY ?? '' } }\n )\n\n if (!response.ok) {\n throw new Error(`GymFit API: ${response.status}`)\n }\n\n return URL.createObjectURL(await response.blob())\n}\n\n// \"Muscles"},{"lang":"swift","label":"Swift","source":"import WebKit\n\n// UIImage does not read SVG: a WKWebView draws it (apiKey: see the search)\n@MainActor\nfunc showHeatmap(of idOrSlug: String, in webView: WKWebView) async throws {\n let url = URL(string: \"https://api.gymfit-api.com/v2/exercises/\\(idOrSlug)/heatmap\")!\n var request = URLRequest(url: url)\n request.setValue(apiKey, forHTTPHeaderField: \"X-API-Key\")\n\n let (data, _) = try await URLSession.shared.data(for: request)\n let svg = String(decoding: data, as: UTF8.self)\n webView.isOpaque = false\n webView.loadHTMLString(\n \"\\(svg)\",\n baseURL: nil\n )\n}"},{"lang":"kotlin","label":"Kotlin (Compose)","source":"import androidx.compose.runtime.Composable\nimport androidx.compose.ui.platform.LocalContext\nimport coil.compose.AsyncImage\nimport coil.decode.SvgDecoder\nimport coil.request.ImageRequest\n\n// Coil 2 with its SVG decoder: io.coil-kt:coil-compose and io.coil-kt:coil-svg\n@Composable\nfun Heatmap(idOrSlug: String) {\n val request = ImageRequest.Builder(LocalContext.current)\n .data(\"https://api.gymfit-api.com/v2/exercises/$idOrSlug/heatmap\")\n .addHeader(\"X-API-Key\", BuildConfig.GYMFIT_API_KEY)\n .decoderFactory(SvgDecoder.Factory())\n .build()\n\n AsyncImage(model = request, contentDescription = \"Muscles worked\")\n}"},{"lang":"dart","label":"Dart (Flutter)","source":"import 'package:flutter/widgets.dart';\nimport 'package:flutter_svg/flutter_svg.dart';\n\n// flutter_svg draws the SVG and sends the key (apiKey: see the search)\nWidget heatmap(String idOrSlug) => SvgPicture.network(\n 'https://api.gymfit-api.com/v2/exercises/$idOrSlug/heatmap',\n headers: const {'X-API-Key': apiKey},\n semanticsLabel: 'Muscles worked',\n );"}]}},"/v2/equipment":{"get":{"operationId":"equipment","summary":"List the equipment","description":"Every value of `equipment`, with the number of exercises that use it. Lists change only when the catalog does: keep them.","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ReferenceItemDto"}},"example":[{"value":"Barbell","exercises":171,"total":367},{"value":"Dumbbell","exercises":239,"total":644},{"value":"Machine","exercises":130,"total":261},{"value":"Bodyweight","exercises":861,"total":2988},{"value":"Kettlebell","exercises":81,"total":213},{"value":"ResistanceBand","exercises":93,"total":354},{"value":"BattleRope","exercises":5,"total":21},{"value":"MedicineBall","exercises":12,"total":48},{"value":"BosuBall","exercises":4,"total":19},{"value":"PowerSled","exercises":3,"total":14},{"value":"SmithMachine","exercises":31,"total":83},{"value":"StabilityBall","exercises":22,"total":137},{"value":"TrapBar","exercises":6,"total":10},{"value":"Stepper","exercises":0,"total":0},{"value":"WheelRoller","exercises":2,"total":6},{"value":"Towel","exercises":7,"total":51},{"value":"Landmine","exercises":15,"total":30},{"value":"Cable","exercises":143,"total":356},{"value":"Bench","exercises":220,"total":695},{"value":"Box","exercises":25,"total":90},{"value":"EzBar","exercises":22,"total":57},{"value":"ParallelBars","exercises":13,"total":31},{"value":"PullUpBar","exercises":50,"total":136},{"value":"Rings","exercises":13,"total":80},{"value":"Rope","exercises":9,"total":17},{"value":"Sledgehammer","exercises":1,"total":1},{"value":"Stick","exercises":10,"total":43},{"value":"SuspensionTrainer","exercises":33,"total":145},{"value":"Weighted","exercises":35,"total":156},{"value":"Chair","exercises":38,"total":200},{"value":"FoamRoller","exercises":3,"total":19},{"value":"PreacherBench","exercises":14,"total":28},{"value":"Hurdle","exercises":0,"total":5},{"value":"Block","exercises":16,"total":36}]}}}},"tags":["Reference"]}},"/v2/categories":{"get":{"operationId":"categories","summary":"List the categories","description":"Every value of `category` (strength, cardio, stretching, mobility, yoga...), with the number of exercises.","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ReferenceItemDto"}},"example":[{"value":"Strength","exercises":1356,"total":3972},{"value":"Weightlifting","exercises":27,"total":43},{"value":"Plyometrics","exercises":22,"total":190},{"value":"Cardio","exercises":85,"total":607},{"value":"Stretching","exercises":251,"total":581},{"value":"Mobility","exercises":60,"total":235},{"value":"Yoga","exercises":99,"total":168}]}}}},"tags":["Reference"]}},"/v2/families":{"get":{"operationId":"families","summary":"List the families of movements","description":"The families (`squat`, `bench-press`, `row`...) an exercise belongs to, with the number of exercises. `id` is what `family` takes on the search.","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FamilyDto"}},"example":[{"id":"stretch-trunk","label":"Abdominal and side stretch","pattern":"stretch","exercises":9,"total":44},{"id":"core-activation","label":"Abdominal vacuum and draw-in","pattern":"core activation","exercises":1,"total":2},{"id":"stretch-adductors","label":"Adductor stretch","pattern":"stretch","exercises":14,"total":33},{"id":"agility-drill","label":"Agility drill","pattern":"agility","exercises":11,"total":26},{"id":"ankle-mobility","label":"Ankle and foot mobility","pattern":"ankle mobility","exercises":7,"total":11},{"id":"stretch-arms","label":"Arm stretch","pattern":"stretch","exercises":12,"total":44},{"id":"stretch-spine","label":"Back and spine stretch","pattern":"stretch","exercises":46,"total":113},{"id":"back-extension","label":"Back extension","pattern":"spinal extension","exercises":14,"total":50},{"id":"back-lever","label":"Back lever","pattern":"straight-arm hold","exercises":3,"total":3},{"id":"balance","label":"Balance drill","pattern":"balance","exercises":4,"total":8},{"id":"slam","label":"Ball slam and throw","pattern":"conditioning","exercises":3,"total":29},{"id":"battle-rope","label":"Battle rope","pattern":"conditioning","exercises":5,"total":16},{"id":"bench-press","label":"Bench press","pattern":"horizontal push","exercises":34,"total":173},{"id":"biceps-curl","label":"Biceps curl","pattern":"elbow flexion","exercises":61,"total":175},{"id":"box-jump","label":"Box jump","pattern":"jump","exercises":0,"total":13},{"id":"boxing","label":"Boxing and kickboxing","pattern":"conditioning","exercises":14,"total":84},{"id":"breathing","label":"Breathing and relaxation","pattern":"breathing","exercises":4,"total":5},{"id":"burpee","label":"Burpee","pattern":"combination","exercises":6,"total":19},{"id":"calf-raise","label":"Calf raise","pattern":"plantar flexion","exercises":31,"total":70},{"id":"stretch-calves","label":"Calf stretch","pattern":"stretch","exercises":25,"total":70},{"id":"chest-fly","label":"Chest fly","pattern":"horizontal adduction","exercises":21,"total":107},{"id":"stretch-chest","label":"Chest stretch","pattern":"stretch","exercises":17,"total":36},{"id":"chin-up","label":"Chin-up","pattern":"vertical pull","exercises":10,"total":41},{"id":"clean","label":"Clean","pattern":"olympic lift","exercises":20,"total":26},{"id":"clean-and-jerk","label":"Clean and jerk","pattern":"olympic lift","exercises":5,"total":8},{"id":"clean-and-press","label":"Clean and press","pattern":"olympic lift","exercises":8,"total":11},{"id":"climb","label":"Climb","pattern":"locomotion","exercises":6,"total":18},{"id":"crunch","label":"Crunch","pattern":"trunk flexion","exercises":34,"total":164},{"id":"cycling","label":"Cycling","pattern":"locomotion","exercises":5,"total":7},{"id":"dead-bug","label":"Dead bug and bird dog","pattern":"anti-extension","exercises":13,"total":25},{"id":"deadlift","label":"Deadlift","pattern":"hip hinge","exercises":19,"total":45},{"id":"dip","label":"Dip","pattern":"vertical push","exercises":13,"total":26},{"id":"face-pull","label":"Face pull","pattern":"horizontal abduction","exercises":7,"total":13},{"id":"foot-inversion-eversion","label":"Foot inversion and eversion","pattern":"inversion and eversion","exercises":2,"total":5},{"id":"forearm-rotation","label":"Forearm pronation and supination","pattern":"forearm rotation","exercises":3,"total":13},{"id":"front-lever","label":"Front lever","pattern":"straight-arm pull","exercises":4,"total":4},{"id":"front-raise","label":"Front raise","pattern":"shoulder flexion","exercises":13,"total":49},{"id":"glute-bridge","label":"Glute bridge","pattern":"hip extension","exercises":24,"total":87},{"id":"glute-kickback","label":"Glute kickback","pattern":"hip extension","exercises":15,"total":51},{"id":"stretch-glutes","label":"Glute stretch","pattern":"stretch","exercises":15,"total":36},{"id":"good-morning","label":"Good morning","pattern":"hip hinge","exercises":6,"total":19},{"id":"grip","label":"Grip and hang","pattern":"grip","exercises":3,"total":14},{"id":"hack-squat","label":"Hack squat","pattern":"squat","exercises":9,"total":13},{"id":"halo-and-pass","label":"Halo and around-the-body pass","pattern":"rotation","exercises":4,"total":6},{"id":"hammer-curl","label":"Hammer curl","pattern":"elbow flexion","exercises":20,"total":43},{"id":"stretch-hamstrings","label":"Hamstring stretch","pattern":"stretch","exercises":34,"total":69},{"id":"handstand","label":"Handstand","pattern":"inverted hold","exercises":5,"total":8},{"id":"handstand-push-up","label":"Handstand push-up","pattern":"vertical push","exercises":2,"total":4},{"id":"high-pull","label":"High pull","pattern":"olympic lift","exercises":4,"total":9},{"id":"hip-abduction","label":"Hip abduction","pattern":"hip abduction","exercises":21,"total":76},{"id":"hip-adduction","label":"Hip adduction","pattern":"hip adduction","exercises":6,"total":19},{"id":"stretch-hip-flexors","label":"Hip flexor stretch","pattern":"stretch","exercises":13,"total":26},{"id":"stretch-hips","label":"Hip mobility","pattern":"stretch","exercises":21,"total":83},{"id":"hip-rotation","label":"Hip rotation","pattern":"hip rotation","exercises":4,"total":10},{"id":"hip-thrust","label":"Hip thrust","pattern":"hip extension","exercises":12,"total":34},{"id":"human-flag","label":"Human flag","pattern":"lateral hold","exercises":1,"total":1},{"id":"inchworm","label":"Inchworm","pattern":"mobility","exercises":1,"total":4},{"id":"inverted-row","label":"Inverted row","pattern":"horizontal pull","exercises":13,"total":48},{"id":"jefferson-curl","label":"Jefferson curl","pattern":"spinal flexion","exercises":1,"total":1},{"id":"jerk","label":"Jerk","pattern":"olympic lift","exercises":5,"total":7},{"id":"jump","label":"Jump","pattern":"jump","exercises":4,"total":74},{"id":"jump-rope","label":"Jump rope","pattern":"conditioning","exercises":5,"total":7},{"id":"jump-squat","label":"Jump squat","pattern":"jump","exercises":4,"total":28},{"id":"jumping-jack","label":"Jumping jack","pattern":"jump","exercises":5,"total":44},{"id":"swing","label":"Kettlebell swing","pattern":"hip hinge","exercises":6,"total":18},{"id":"lat-pulldown","label":"Lat pulldown","pattern":"vertical pull","exercises":18,"total":45},{"id":"stretch-lats","label":"Lat stretch","pattern":"stretch","exercises":12,"total":20},{"id":"lateral-raise","label":"Lateral raise","pattern":"shoulder abduction","exercises":22,"total":48},{"id":"leg-curl","label":"Leg curl","pattern":"knee flexion","exercises":14,"total":57},{"id":"leg-extension","label":"Leg extension","pattern":"knee extension","exercises":4,"total":12},{"id":"leg-press","label":"Leg press","pattern":"squat","exercises":12,"total":19},{"id":"leg-raise","label":"Leg raise","pattern":"hip flexion","exercises":61,"total":198},{"id":"carry","label":"Loaded carry","pattern":"carry","exercises":11,"total":27},{"id":"low-impact-cardio","label":"Low-impact aerobics","pattern":"conditioning","exercises":2,"total":204},{"id":"lunge","label":"Lunge","pattern":"single leg","exercises":34,"total":153},{"id":"mountain-climber","label":"Mountain climber","pattern":"hip flexion","exercises":8,"total":30},{"id":"muscle-up","label":"Muscle-up","pattern":"vertical pull","exercises":3,"total":7},{"id":"neck","label":"Neck exercise","pattern":"neck","exercises":13,"total":32},{"id":"stretch-neck","label":"Neck stretch","pattern":"stretch","exercises":19,"total":39},{"id":"overhead-press","label":"Overhead press","pattern":"vertical push","exercises":53,"total":118},{"id":"pallof-press","label":"Pallof press","pattern":"anti-rotation","exercises":4,"total":13},{"id":"pelvic-tilt","label":"Pelvic tilt","pattern":"pelvic tilt","exercises":3,"total":8},{"id":"pike-push-up","label":"Pike push-up","pattern":"vertical push","exercises":3,"total":11},{"id":"planche","label":"Planche and maltese","pattern":"straight-arm push","exercises":4,"total":9},{"id":"plank","label":"Plank","pattern":"anti-extension","exercises":47,"total":120},{"id":"pull-through","label":"Pull-through","pattern":"hip hinge","exercises":2,"total":6},{"id":"pull-up","label":"Pull-up","pattern":"vertical pull","exercises":17,"total":52},{"id":"pullover","label":"Pullover","pattern":"shoulder extension","exercises":8,"total":37},{"id":"push-up","label":"Push-up","pattern":"horizontal push","exercises":55,"total":168},{"id":"stretch-quadriceps","label":"Quadriceps stretch","pattern":"stretch","exercises":10,"total":14},{"id":"rear-delt-fly","label":"Rear delt fly","pattern":"horizontal abduction","exercises":16,"total":47},{"id":"reverse-curl","label":"Reverse curl","pattern":"elbow flexion","exercises":9,"total":29},{"id":"reverse-hyperextension","label":"Reverse hyperextension","pattern":"hip extension","exercises":3,"total":20},{"id":"reverse-wrist-curl","label":"Reverse wrist curl","pattern":"wrist extension","exercises":7,"total":16},{"id":"rollout","label":"Rollout","pattern":"anti-extension","exercises":14,"total":27},{"id":"romanian-deadlift","label":"Romanian deadlift","pattern":"hip hinge","exercises":15,"total":34},{"id":"row","label":"Row","pattern":"horizontal pull","exercises":63,"total":217},{"id":"rowing-machine","label":"Rowing machine","pattern":"locomotion","exercises":2,"total":3},{"id":"run","label":"Run and walk","pattern":"locomotion","exercises":19,"total":56},{"id":"scapular-protraction","label":"Scapular protraction","pattern":"scapular protraction","exercises":6,"total":9},{"id":"scapular-retraction","label":"Scapular retraction","pattern":"scapular retraction","exercises":2,"total":14},{"id":"shoulder-mobility","label":"Shoulder mobility","pattern":"shoulder mobility","exercises":10,"total":39},{"id":"shoulder-rotation","label":"Shoulder rotation","pattern":"shoulder rotation","exercises":10,"total":35},{"id":"stretch-shoulders","label":"Shoulder stretch","pattern":"stretch","exercises":20,"total":50},{"id":"shrug","label":"Shrug","pattern":"scapular elevation","exercises":19,"total":35},{"id":"side-bend","label":"Side bend","pattern":"lateral flexion","exercises":10,"total":47},{"id":"side-plank","label":"Side plank","pattern":"anti-lateral flexion","exercises":11,"total":48},{"id":"pistol-squat","label":"Single-leg squat","pattern":"single leg","exercises":9,"total":30},{"id":"sissy-squat","label":"Sissy squat","pattern":"knee extension","exercises":2,"total":4},{"id":"sit-up","label":"Sit-up","pattern":"trunk flexion","exercises":26,"total":88},{"id":"sled","label":"Sled push and pull","pattern":"locomotion","exercises":4,"total":9},{"id":"snatch","label":"Snatch","pattern":"olympic lift","exercises":11,"total":18},{"id":"split-squat","label":"Split squat","pattern":"single leg","exercises":21,"total":63},{"id":"squat","label":"Squat","pattern":"squat","exercises":71,"total":262},{"id":"step-up","label":"Step-up","pattern":"single leg","exercises":13,"total":38},{"id":"stiff-leg-deadlift","label":"Stiff-leg deadlift","pattern":"hip hinge","exercises":4,"total":17},{"id":"straight-arm-pulldown","label":"Straight-arm pulldown","pattern":"shoulder extension","exercises":5,"total":13},{"id":"swimming","label":"Swimming","pattern":"locomotion","exercises":1,"total":1},{"id":"thruster","label":"Thruster (squat to press)","pattern":"combination","exercises":9,"total":16},{"id":"tibialis-raise","label":"Tibialis raise","pattern":"dorsiflexion","exercises":2,"total":4},{"id":"tire-flip","label":"Tire flip and strongman lift","pattern":"hinge and push","exercises":1,"total":8},{"id":"triceps-dip","label":"Triceps dip","pattern":"vertical push","exercises":15,"total":26},{"id":"triceps-extension","label":"Triceps extension","pattern":"elbow extension","exercises":50,"total":108},{"id":"triceps-kickback","label":"Triceps kickback","pattern":"elbow extension","exercises":16,"total":27},{"id":"triceps-pushdown","label":"Triceps pushdown","pattern":"elbow extension","exercises":10,"total":17},{"id":"trunk-rotation","label":"Trunk rotation","pattern":"rotation","exercises":46,"total":155},{"id":"tumbling","label":"Tumbling and rolls","pattern":"rolling","exercises":1,"total":3},{"id":"turkish-get-up","label":"Turkish get-up","pattern":"combination","exercises":2,"total":4},{"id":"upright-row","label":"Upright row","pattern":"shoulder abduction","exercises":10,"total":14},{"id":"wall-sit","label":"Wall sit","pattern":"squat","exercises":4,"total":14},{"id":"wall-slide","label":"Wall slide and wall angel","pattern":"scapular upward rotation","exercises":4,"total":11},{"id":"windmill","label":"Windmill","pattern":"lateral hinge","exercises":3,"total":11},{"id":"wrist-curl","label":"Wrist curl","pattern":"wrist flexion","exercises":11,"total":35},{"id":"wrist-mobility","label":"Wrist mobility","pattern":"wrist mobility","exercises":1,"total":9},{"id":"y-t-raise","label":"Y, T and W raise","pattern":"scapular control","exercises":12,"total":33},{"id":"yoga-pose","label":"Yoga pose","pattern":"mobility","exercises":94,"total":160}]}}}},"tags":["Reference"]}},"/v2/meta":{"get":{"operationId":"meta","summary":"What the catalog holds","description":"The size of the catalog and every value its enumerations take (difficulties, forces, tracking types, laterality, purposes, tiers, body parts, equipment, categories).","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaDto"},"example":{"exercises":{"default":1900,"total":5796},"muscles":49,"muscleGroups":21,"families":136,"values":{"equipment":["Barbell","Dumbbell","Machine","Bodyweight","Kettlebell","ResistanceBand","BattleRope","MedicineBall","BosuBall","PowerSled","SmithMachine","StabilityBall","TrapBar","Stepper","WheelRoller","Towel","Landmine","Cable","Bench","Box","EzBar","ParallelBars","PullUpBar","Rings","Rope","Sledgehammer","Stick","SuspensionTrainer","Weighted","Chair","FoamRoller","PreacherBench","Hurdle","Block"],"categories":["Strength","Weightlifting","Plyometrics","Cardio","Stretching","Mobility","Yoga"],"difficulties":["Beginner","Intermediate","Advanced"],"forces":["Push","Pull","Static"],"types":["Compound","Isolation"],"trackingTypes":["WeightReps","Reps","WeightedBodyweightReps","AssistedReps","Duration","WeightDuration","DistanceDuration","WeightDistance"],"lateralities":["Bilateral","Unilateral","Alternating"],"purposes":["Strength","Calisthenics","Weightlifting","Strongman","Plyometrics","Cardio","Aerobics","Stretching","Mobility","Yoga","Pilates","Rehab","WarmUp"],"tiers":["Standard","Variant","Niche"],"bodyParts":["Legs","Back","Chest","Shoulders","Arms","Core","Neck"]}}}}}},"tags":["Reference"]}}},"info":{"title":"GymFit API","description":"Exercises with the muscles they target, muscles, and fitness calculators (BMR, TDEE, BMI, IBW).\n\nFor agents and code generators: the OpenAPI specification is at [/openapi.json](/openapi.json), and this reference as Markdown at [/docs.md](/docs.md). AI assistants can call the API as an MCP server: see *AI assistants (MCP)* below.\n\n## Quickstart\n\n1. [Create a free account](https://www.gymfit-api.com/signup) and create a key in your dashboard: 1,000 requests a month, no credit card.\n2. Send the key in the `X-API-Key` header:\n\n```bash\ncurl \"https://api.gymfit-api.com/v2/exercises/search?query=bench%20press&limit=3\" \\\n -H \"X-API-Key: YOUR_API_KEY\"\n```\n\n3. Each result has an `id` and a `slug`. Read the whole exercise (muscles, steps, tips, variants, alternatives) with `GET /v2/exercises/{id}`, and draw its muscles with `GET /v2/exercises/{id}/heatmap`.\n\nKeep the key on your server in production: a key shipped in a mobile app or a web page can be read by anyone who opens it. The code samples of the routes call the API directly, as for a prototype.\n\n## Authentication\n\nSend your API key in the `X-API-Key` header. No key yet? [Sign up](https://www.gymfit-api.com/signup) for the free plan: 1,000 requests a month, no credit card. Create and manage your keys from your [dashboard](https://www.gymfit-api.com/dashboard): a key is only shown once, when it is created.\n\nSubscribed through RapidAPI? Keep calling the API through RapidAPI, with your RapidAPI key.\n\n## Search and filters\n\n`GET /v2/exercises/search` reads what people type: typos (`bech press`), abbreviations (`rdl`, `ohp`) and muscles (`quads`, `lower back`).\n\n- **Filters combine**: `?muscle=Pecs&equipment=Dumbbell,Cable&difficulty=Beginner`. The values come from `GET /v2/equipment`, `/v2/categories`, `/v2/families` and `/v2/muscle-groups`, each with how many exercises have it.\n- **Autocomplete**: `GET /v2/exercises/suggest?q=bench` while the person types. It is free and does not count in the quota.\n- **Filters with counts**: `facets=true` adds how many matches fall under each category, difficulty, tier, equipment and muscle group.\n- **Did you mean**: `suggest=true` adds `suggestion` when a word of the query looks misspelled.\n- **Pages**: `limit` (up to 100) and `offset`; `total` is the number of matches.\n- **One line per movement**: `group=true` shows each movement once, with its variants counted under it.\n\n## Muscle heatmap\n\n`GET /v2/exercises/{id}/heatmap` answers an SVG of the body, with the target muscles of the exercise and its secondary ones in color.\n\n- `view`: `front`, `back` or `both` (default).\n- Colors in hex, the `#` optional: `target`, `secondary`, `base` (the muscles the exercise does not work), `body` and `outline`. For example `?target=D4F53C&secondary=7A8C2E`.\n- The heatmap of an exercise does not change: it comes with `Cache-Control: private, max-age=86400`, keep it on your side instead of asking for it at each display.\n- It needs the key like every route: load it from your server, or fetch it with the key and show it (see the code samples of the route).\n\n## AI assistants (MCP)\n\nGymFit is also an [MCP](https://modelcontextprotocol.io) server: Claude, ChatGPT, Claude Code, Cursor, VS Code or any MCP client searches the exercises, reads them and runs the calculators for you, on your plan.\n\n**Claude, ChatGPT and the apps that sign in with OAuth**: add a custom connector with the URL `https://mcp.gymfit-api.com/mcp`, then sign in to GymFit and allow it. No key: the assistant uses your account, and you disconnect it from your [dashboard](https://www.gymfit-api.com/dashboard/ai).\n\n**Claude Code, Cursor and the clients that take a key**:\n\n- URL: `https://api.gymfit-api.com/mcp` (Streamable HTTP)\n- Key: in the `X-API-Key` header, or as `Authorization: Bearer YOUR_API_KEY` for clients that only take a token. A RapidAPI key does not work here: the MCP server takes a GymFit key.\n\nClaude Code:\n\n```bash\nclaude mcp add --transport http gymfit https://api.gymfit-api.com/mcp --header \"X-API-Key: YOUR_API_KEY\"\n```\n\nCursor (`.cursor/mcp.json`), and the same entry in most clients (VS Code names the list `servers` and adds `\"type\": \"http\"`):\n\n```json\n{\n \"mcpServers\": {\n \"gymfit\": {\n \"url\": \"https://api.gymfit-api.com/mcp\",\n \"headers\": { \"X-API-Key\": \"YOUR_API_KEY\" }\n }\n }\n}\n```\n\nKeep the key out of shared files: Cursor reads `${env:GYMFIT_API_KEY}` and Claude Code `${GYMFIT_API_KEY}` in a `.mcp.json`.\n\nThe tools are read-only: `search_exercises`, `get_exercise`, `find_alternatives`, `get_exercise_heatmap`, `search_muscles`, `get_muscle`, `list_filter_values`, `calculate_bmr`, `calculate_tdee`, `calculate_bmi`, `calculate_ideal_weight` and `get_usage`. Each tool call counts as one request of your quota, like a call to the API; `get_usage` is free. A limit reached is answered to the assistant as an error it can read, with the time to wait or the way to upgrade.\n\n## Plans, quotas and rate limits\n\n| Plan | Price / month | Requests / month | Beyond the quota | Requests / minute |\n|---|---|---|---|---|\n| Free | $0 | 1,000 | Refused | 30 |\n| Starter | $9 | 20,000 | $0.002 per request | 60 |\n| Pro | $29 | 100,000 | $0.001 per request | 300 |\n\nOnly successful (2xx) responses count in the quota. Every response carries:\n\n- `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the minute window resets)\n- `X-Quota-Limit`, `X-Quota-Used` and `X-Quota-Remaining` for the current billing period\n- `X-Request-Id`: mention it when you contact the support\n\nWhen a limit is reached, the API answers `429` with a `Retry-After` header: wait that many seconds before sending again, and space out the retries rather than sending them at once. Your consumption is also available from `GET /v2/usage`, which is free and does not count in your quota.\n\n## Errors\n\nErrors follow [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) (`application/problem+json`):\n\n```json\n{\n \"type\": \"https://api.gymfit-api.com/docs#error-invalid_api_key\",\n \"title\": \"Unauthorized\",\n \"status\": 401,\n \"code\": \"invalid_api_key\",\n \"detail\": \"Missing or invalid API key. Get a free key at https://www.gymfit-api.com/signup\",\n \"instance\": \"/v2/exercises/search\",\n \"requestId\": \"9f3c2d1e-5b7a-4c8e-9d6f-1a2b3c4d5e6f\"\n}\n```\n\nBranch on `code`, which is stable: `invalid_api_key`, `validation_failed` (with an `errors` list), `not_found`, `rate_limited`, `quota_exceeded`, `internal_error`...\n\n## Versions\n\nThis reference documents v2, under `/v2`. v1 stays available under `/v1` for existing integrations: the same routes, with the legacy `image` and `images` fields, and without the muscle heatmap.","version":"1.0.0","contact":{"name":"GymFit","url":"https://www.gymfit-api.com","email":"contact@gymfit-api.com"}},"tags":[{"name":"Exercises","description":"Search the 5,800 exercises, read one with its muscles, steps and variants, find its alternatives and draw its muscle heatmap."},{"name":"Muscles","description":"The muscles with their common names and groups, and the exercises that work them."},{"name":"Reference","description":"The values the search filters take, with how many exercises have each."},{"name":"Calculator","description":"BMR, TDEE, BMI and ideal body weight."},{"name":"Usage","description":"Your consumption and what is left of your quota. Free, not counted in the quota."}],"servers":[{"url":"https://api.gymfit-api.com"}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"Free key, no credit card: https://www.gymfit-api.com/signup (1,000 requests a month)"}},"schemas":{"UsageErrorsDto":{"type":"object","properties":{"invalidRequests":{"type":"number","description":"400 and 422 responses"},"authErrors":{"type":"number","description":"401 and 403 responses"},"notFound":{"type":"number"},"rateLimited":{"type":"number","description":"429 responses"},"otherClientErrors":{"type":"number"},"serverErrors":{"type":"number","description":"5xx responses"}},"required":["invalidRequests","authErrors","notFound","rateLimited","otherClientErrors","serverErrors"]},"UsageEntryDto":{"type":"object","properties":{"key":{"type":"string","description":"Day (YYYY-MM-DD), month (YYYY-MM), endpoint, or \"total\"","example":"2026-09-28"},"requests":{"type":"number"},"success":{"type":"number","description":"Successful (2xx) requests, the ones counted in the quota"},"errors":{"$ref":"#/components/schemas/UsageErrorsDto"},"averageLatencyMs":{"type":"number","nullable":true}},"required":["key","requests","success","errors","averageLatencyMs"]},"UsageReportDto":{"type":"object","properties":{"from":{"type":"string","example":"2026-09-01"},"to":{"type":"string","example":"2026-09-28"},"groupBy":{"type":"object"},"totals":{"$ref":"#/components/schemas/UsageEntryDto"},"data":{"type":"array","items":{"$ref":"#/components/schemas/UsageEntryDto"}}},"required":["from","to","groupBy","totals","data"]},"CurrentUsageDto":{"type":"object","properties":{"plan":{"type":"object","example":"pro"},"quota":{"type":"number","description":"Successful requests included in the period"},"used":{"type":"number"},"remaining":{"type":"number"},"overage":{"type":"number","description":"Requests beyond the quota, billed on paid plans"},"hardLimit":{"type":"boolean","description":"Free plan: requests are refused beyond the quota"},"overageCostUsd":{"type":"number","description":"Estimated cost of the overage so far, in USD"},"periodStart":{"format":"date-time","type":"string"},"periodEnd":{"format":"date-time","type":"string"},"status":{"type":"string","nullable":true,"description":"Subscription status, null on the free plan"},"cancelAtPeriodEnd":{"type":"boolean"}},"required":["plan","quota","used","remaining","overage","hardLimit","overageCostUsd","periodStart","periodEnd","status","cancelAtPeriodEnd"]},"BmrReqDTO":{"type":"object","properties":{"height":{"type":"number","description":"Height in centimeters","example":180,"minimum":1},"age":{"type":"number","description":"Age","example":25,"minimum":1},"weight":{"type":"number","description":"Body weight in kilograms","example":78,"minimum":1},"gender":{"type":"string","description":"Gender, which changes the constant of the equation","example":"male","enum":["male","female"]}},"required":["height","age","weight","gender"]},"TdeeReqDTO":{"type":"object","properties":{"height":{"type":"number","description":"Height in centimeters","example":180,"minimum":1},"age":{"type":"number","description":"Age","example":25,"minimum":1},"weight":{"type":"number","description":"Body weight in kilograms","example":78,"minimum":1},"gender":{"description":"Gender, which changes the constant of the equation","example":"male","enum":["male","female"],"type":"string"},"activityLevel":{"type":"string","description":"Level of physical activity","example":"active","enum":["sedentary","lightlyActive","active","veryActive"]}},"required":["height","age","weight","gender","activityLevel"]},"BmiReqDTO":{"type":"object","properties":{"height":{"type":"number","description":"Height in centimeters","example":180,"minimum":1},"weight":{"type":"number","description":"Body weight in kilograms","example":78,"minimum":1}},"required":["height","weight"]},"IbwReqDTO":{"type":"object","properties":{"height":{"type":"number","description":"Height in centimeters","example":180,"minimum":1}},"required":["height"]},"CalculresultResDTO":{"type":"object","properties":{"result":{"type":"number","description":"calculation result","example":1785}},"required":["result"]},"BodyPart":{"type":"string","description":"Primary body part targeted by the exercise","enum":["Legs","Back","Chest","Shoulders","Arms","Core","Neck"]},"MuscleSummaryDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier","format":"uuid"},"name":{"type":"string","description":"Anatomical name","example":"Pectoralis major"},"commonName":{"type":"object","nullable":true,"description":"The name people use","example":"Pecs"},"bodyPart":{"nullable":true,"$ref":"#/components/schemas/BodyPart"},"group":{"type":"object","nullable":true,"description":"Group of muscles (`GET /v2/muscle-groups`)","example":"Chest"}},"required":["id","name"]},"SearchMusclesResponseDto":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/MuscleSummaryDto"}},"total":{"type":"number","description":"Total count","minimum":0},"count":{"type":"number","description":"Count in this response","minimum":0}},"required":["results","total","count"]},"MuscleDetailDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier","format":"uuid"},"name":{"type":"string","description":"Anatomical name","example":"Pectoralis major"},"commonName":{"type":"object","nullable":true,"description":"The name people use","example":"Pecs"},"bodyPart":{"nullable":true,"$ref":"#/components/schemas/BodyPart"},"group":{"type":"object","nullable":true,"description":"Group of muscles (`GET /v2/muscle-groups`)","example":"Chest"},"aliases":{"description":"Other words people search the muscle by","example":["chest","pectorals"],"type":"array","items":{"type":"string"}},"heads":{"description":"Heads of the muscle, when it has several","example":["Clavicular (Upper)","Sternal (Lower)"],"type":"array","items":{"type":"string"}}},"required":["id","name","aliases","heads"]},"MuscleOfGroupDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Pectoralis major"},"commonName":{"type":"object","nullable":true,"example":"Pecs"},"heads":{"example":["Clavicular (Upper)"],"type":"array","items":{"type":"string"}}},"required":["id","name","heads"]},"MuscleGroupDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Name of the group, the one the exercises filter by","example":"Chest"},"aliases":{"description":"Other words people search the group by","example":["pecs","pectorals"],"type":"array","items":{"type":"string"}},"muscles":{"type":"array","items":{"$ref":"#/components/schemas/MuscleOfGroupDto"}}},"required":["id","name","aliases","muscles"]},"Type":{"type":"string","description":"Compound or isolation; none for a hold, a stretch or a drill","enum":["Compound","Isolation"]},"Equipment":{"type":"string","description":"Main equipment of the exercise","enum":["Barbell","Dumbbell","Machine","Bodyweight","Kettlebell","ResistanceBand","BattleRope","MedicineBall","BosuBall","PowerSled","SmithMachine","StabilityBall","TrapBar","Stepper","WheelRoller","Towel","Landmine","Cable","Bench","Box","EzBar","ParallelBars","PullUpBar","Rings","Rope","Sledgehammer","Stick","SuspensionTrainer","Weighted","Chair","FoamRoller","PreacherBench","Hurdle","Block"]},"ExerciseTier":{"type":"string","description":"Standard exercises are the ones people do, variants less so, niche ones are rare or odd","enum":["Standard","Variant","Niche"]},"TrackingType":{"type":"string","description":"How a set is logged: weight and reps, duration, distance...","enum":["WeightReps","Reps","WeightedBodyweightReps","AssistedReps","Duration","WeightDuration","DistanceDuration","WeightDistance"]},"Laterality":{"type":"string","enum":["Bilateral","Unilateral","Alternating"]},"ExerciseCategory":{"type":"string","description":"Kind of exercise","enum":["Strength","Weightlifting","Plyometrics","Cardio","Stretching","Mobility","Yoga"]},"Difficulty":{"type":"string","description":"How hard the exercise is for someone who trains","enum":["Beginner","Intermediate","Advanced"]},"Purpose":{"type":"string","enum":["Strength","Calisthenics","Weightlifting","Strongman","Plyometrics","Cardio","Aerobics","Stretching","Mobility","Yoga","Pilates","Rehab","WarmUp"]},"MovementForce":{"type":"string","enum":["Push","Pull","Static"]},"FacetValueDto":{"type":"object","properties":{"value":{"type":"string","example":"Strength"},"count":{"type":"number","minimum":1,"example":120}},"required":["value","count"]},"FacetsDto":{"type":"object","properties":{"category":{"type":"array","items":{"$ref":"#/components/schemas/FacetValueDto"}},"difficulty":{"type":"array","items":{"$ref":"#/components/schemas/FacetValueDto"}},"tier":{"type":"array","items":{"$ref":"#/components/schemas/FacetValueDto"}},"equipment":{"description":"An exercise counts under each equipment it uses","type":"array","items":{"$ref":"#/components/schemas/FacetValueDto"}},"muscleGroup":{"description":"The muscle groups the exercises work the most","type":"array","items":{"$ref":"#/components/schemas/FacetValueDto"}}},"required":["category","difficulty","tier","equipment","muscleGroup"]},"SearchExercisesResponseDto":{"type":"object","properties":{"total":{"type":"number","description":"Total number of exercises matching the criteria (useful for pagination)","minimum":0},"count":{"type":"number","description":"Number of results returned in this response","minimum":0},"results":{"description":"Array of exercises matching the search criteria","items":{"type":"array"},"type":"array"},"suggestion":{"type":"string","description":"The query put right, when `suggest=true` and a word of it looks misspelled","example":"bench press"},"facets":{"description":"Counts of the matches per filter, when `facets=true`","allOf":[{"$ref":"#/components/schemas/FacetsDto"}]}},"required":["total","count","results"]},"ExerciseSuggestionDto":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"object","nullable":true,"example":"bench-press-barbell"},"name":{"type":"string","example":"Bench Press (Barbell)"},"equipment":{"type":"string","example":"Barbell"},"category":{"type":"object","nullable":true,"example":"Strength"}},"required":["id","slug","name"]},"SuggestExercisesResponseDto":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ExerciseSuggestionDto"}},"count":{"type":"number","minimum":0}},"required":["results","count"]},"ExerciseStepDto":{"type":"object","properties":{"order":{"type":"number","minimum":1,"example":1},"description":{"type":"string","example":"Lie on the bench with your feet flat on the floor."}},"required":["order","description"]},"ExerciseMuscleDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the muscle","format":"uuid"},"name":{"type":"string","description":"Muscle name","example":"Pectoralis Major"},"bodyPart":{"nullable":true,"example":"Chest","$ref":"#/components/schemas/BodyPart"},"group":{"type":"object","nullable":true,"description":"Muscle group (for grouping related muscles)","example":"Hamstrings"},"commonName":{"type":"object","nullable":true,"description":"The name people use","example":"Pecs"}},"required":["id","name"]},"ExerciseFamilyDto":{"type":"object","properties":{"id":{"type":"string","example":"bench-press"},"label":{"type":"string","example":"Bench press"}},"required":["id","label"]},"ExerciseEquipmentDto":{"type":"object","properties":{"equipment":{"$ref":"#/components/schemas/Equipment"},"main":{"type":"boolean","description":"Whether it is the equipment the exercise works with"}},"required":["equipment","main"]},"ExerciseSummaryDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the exercise","format":"uuid"},"name":{"type":"string","description":"Name of the exercise","example":"Bench Press (Barbell)"},"bodyPart":{"nullable":true,"example":"Chest","$ref":"#/components/schemas/BodyPart"},"slug":{"type":"object","nullable":true,"description":"Stable name of the exercise, usable in a URL","example":"bench-press-barbell"},"equipment":{"example":"Barbell","$ref":"#/components/schemas/Equipment"},"category":{"nullable":true,"example":"Strength","$ref":"#/components/schemas/ExerciseCategory"},"difficulty":{"nullable":true,"example":"Intermediate","$ref":"#/components/schemas/Difficulty"},"primaryGroups":{"description":"Muscle groups the exercise works the most","example":["Chest","Triceps"],"type":"array","items":{"type":"string"}},"tier":{"nullable":true,"example":"Standard","$ref":"#/components/schemas/ExerciseTier"},"popularity":{"type":"object","nullable":true,"description":"How often the exercise is done, from 0 to 100","example":100},"variantCount":{"type":"number","description":"With the search grouped by movement: how many variants stand under this exercise","example":12}},"required":["id","name"]},"ExerciseAlternativeDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the exercise","format":"uuid"},"name":{"type":"string","description":"Name of the exercise","example":"Bench Press (Barbell)"},"bodyPart":{"nullable":true,"example":"Chest","$ref":"#/components/schemas/BodyPart"},"slug":{"type":"object","nullable":true,"description":"Stable name of the exercise, usable in a URL","example":"bench-press-barbell"},"equipment":{"example":"Barbell","$ref":"#/components/schemas/Equipment"},"category":{"nullable":true,"example":"Strength","$ref":"#/components/schemas/ExerciseCategory"},"difficulty":{"nullable":true,"example":"Intermediate","$ref":"#/components/schemas/Difficulty"},"primaryGroups":{"description":"Muscle groups the exercise works the most","example":["Chest","Triceps"],"type":"array","items":{"type":"string"}},"tier":{"nullable":true,"example":"Standard","$ref":"#/components/schemas/ExerciseTier"},"popularity":{"type":"object","nullable":true,"description":"How often the exercise is done, from 0 to 100","example":100},"variantCount":{"type":"number","description":"With the search grouped by movement: how many variants stand under this exercise","example":12},"score":{"type":"number","description":"How close the alternative is, from 0 to 1","example":0.93},"reasons":{"description":"Why it is an alternative: same-target-muscles, similar-muscles, same-movement, other-equipment, no-equipment, easier, harder","type":"array","items":{"type":"string"}}},"required":["id","name","score","reasons"]},"ExerciseLadderDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the exercise","format":"uuid"},"name":{"type":"string","description":"Name of the exercise","example":"Bench Press (Barbell)"},"bodyPart":{"nullable":true,"example":"Chest","$ref":"#/components/schemas/BodyPart"},"slug":{"type":"object","nullable":true,"description":"Stable name of the exercise, usable in a URL","example":"bench-press-barbell"},"equipment":{"example":"Barbell","$ref":"#/components/schemas/Equipment"},"category":{"nullable":true,"example":"Strength","$ref":"#/components/schemas/ExerciseCategory"},"difficulty":{"nullable":true,"example":"Intermediate","$ref":"#/components/schemas/Difficulty"},"primaryGroups":{"description":"Muscle groups the exercise works the most","example":["Chest","Triceps"],"type":"array","items":{"type":"string"}},"tier":{"nullable":true,"example":"Standard","$ref":"#/components/schemas/ExerciseTier"},"popularity":{"type":"object","nullable":true,"description":"How often the exercise is done, from 0 to 100","example":100},"variantCount":{"type":"number","description":"With the search grouped by movement: how many variants stand under this exercise","example":12},"step":{"type":"number","description":"How many steps of difficulty apart from this exercise","example":10}},"required":["id","name"]},"ExerciseDetailDto":{"type":"object","properties":{"name":{"type":"string","description":"Name of the exercise","example":"Bench Press (Barbell)","maxLength":255},"bodyPart":{"nullable":true,"example":"Chest","$ref":"#/components/schemas/BodyPart"},"equipment":{"example":"Barbell","$ref":"#/components/schemas/Equipment"},"instructions":{"description":"Step-by-step instructions, in order","type":"array","items":{"$ref":"#/components/schemas/ExerciseStepDto"}},"targetMuscles":{"description":"Muscles the exercise works the most","type":"array","items":{"$ref":"#/components/schemas/ExerciseMuscleDto"}},"secondaryMuscles":{"description":"Muscles that help","type":"array","items":{"$ref":"#/components/schemas/ExerciseMuscleDto"}},"id":{"type":"string","format":"uuid"},"slug":{"type":"object","nullable":true,"example":"bench-press-barbell"},"type":{"nullable":true,"$ref":"#/components/schemas/Type"},"description":{"type":"object","nullable":true,"description":"What the exercise is and what it works"},"difficulty":{"nullable":true,"$ref":"#/components/schemas/Difficulty"},"category":{"nullable":true,"$ref":"#/components/schemas/ExerciseCategory"},"force":{"nullable":true,"$ref":"#/components/schemas/MovementForce"},"trackingType":{"nullable":true,"$ref":"#/components/schemas/TrackingType"},"laterality":{"nullable":true,"$ref":"#/components/schemas/Laterality"},"tier":{"nullable":true,"$ref":"#/components/schemas/ExerciseTier"},"popularity":{"type":"object","nullable":true,"example":100},"purposes":{"type":"array","items":{"$ref":"#/components/schemas/Purpose"}},"tips":{"type":"array","items":{"type":"string"}},"mistakes":{"description":"Common mistakes","type":"array","items":{"type":"string"}},"aliases":{"description":"Other names of the exercise","type":"array","items":{"type":"string"}},"primaryGroups":{"description":"Muscle groups worked the most","type":"array","items":{"type":"string"}},"secondaryGroups":{"description":"Muscle groups that help","type":"array","items":{"type":"string"}},"family":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/ExerciseFamilyDto"}]},"equipments":{"type":"array","items":{"$ref":"#/components/schemas/ExerciseEquipmentDto"}},"base":{"nullable":true,"description":"The plain exercise this one is a variant of","allOf":[{"$ref":"#/components/schemas/ExerciseSummaryDto"}]},"variations":{"description":"Variants: the same movement with one thing changed (grip, stance, equipment, side...)","items":{"type":"array"},"type":"array"},"alternatives":{"description":"Exercises that work the same muscles, to replace this one","type":"array","items":{"$ref":"#/components/schemas/ExerciseAlternativeDto"}},"easier":{"description":"Easier versions of the same movement pattern","type":"array","items":{"$ref":"#/components/schemas/ExerciseLadderDto"}},"harder":{"description":"Harder versions of the same movement pattern","type":"array","items":{"$ref":"#/components/schemas/ExerciseLadderDto"}}},"required":["name","equipment","instructions","targetMuscles","secondaryMuscles","id","variations"]},"ReferenceItemDto":{"type":"object","properties":{"value":{"type":"string","description":"The value the filters take","example":"Barbell"},"exercises":{"type":"number","description":"Exercises of the default search with this value","minimum":0,"example":240},"total":{"type":"number","description":"Exercises of the whole catalog with this value","minimum":0,"example":610}},"required":["value","exercises","total"]},"FamilyDto":{"type":"object","properties":{"id":{"type":"string","description":"The value `family` takes","example":"squat"},"label":{"type":"string","description":"Name of the family","example":"Squat"},"pattern":{"type":"string","description":"Pattern of movement of the family","example":"squat"},"exercises":{"type":"number","minimum":0},"total":{"type":"number","minimum":0}},"required":["id","label","pattern","exercises","total"]},"CountsDto":{"type":"object","properties":{"default":{"type":"number","description":"Exercises of the default search","minimum":0},"total":{"type":"number","description":"Exercises of the whole catalog","minimum":0}},"required":["default","total"]},"ValuesDto":{"type":"object","properties":{"equipment":{"type":"array","items":{"type":"string"}},"categories":{"type":"array","items":{"type":"string"}},"difficulties":{"type":"array","items":{"type":"string"}},"forces":{"type":"array","items":{"type":"string"}},"types":{"type":"array","items":{"type":"string"}},"trackingTypes":{"type":"array","items":{"type":"string"}},"lateralities":{"type":"array","items":{"type":"string"}},"purposes":{"type":"array","items":{"type":"string"}},"tiers":{"type":"array","items":{"type":"string"}},"bodyParts":{"type":"array","items":{"type":"string"}}},"required":["equipment","categories","difficulties","forces","types","trackingTypes","lateralities","purposes","tiers","bodyParts"]},"MetaDto":{"type":"object","properties":{"exercises":{"$ref":"#/components/schemas/CountsDto"},"muscles":{"type":"number","minimum":0},"muscleGroups":{"type":"number","minimum":0},"families":{"type":"number","minimum":0},"values":{"$ref":"#/components/schemas/ValuesDto"}},"required":["exercises","muscles","muscleGroups","families","values"]}}},"security":[{"api_key":[]}]}