Docs navigation

Endpoints

Reference for all seven public endpoints

The API surface is intentionally small. Use `GET /v1/exercises` for search and `GET /v1/exercises/:id` for detail screens, then use the supporting metadata endpoints for filters and catalog stats.

Working with the videos array

Each exercise response includes a `videos` array. Most exercises today return `videos: []` — only a small set of demos have clips so far. Always check `videos.length > 0` before rendering, and show a placeholder for movements without a clip.

Aspect ratio varies. Most clips are 9:16 vertical (496x864), but some are 16:9 landscape (864x496). Read the `aspectRatio` field on each video and size the player from it — hardcoding vertical will letterbox the landscape clips.
Clips are short (≤ 5 seconds) and have no audio track. Autoplay with `muted` and `loop` to give a continuous demo without surprising the user.
Use `playsInline` on mobile so the video stays embedded instead of opening a fullscreen native player.
URLs are served from `cdn.exerciseapi.dev` (Cloudflare R2 + CDN). They're public — no signed URLs, no auth required to play. Cache aggressively at the client edge.
Treat the array as ordered. The first entry is the canonical demo today; future exercises may include alternate-angle clips.
The `images` field on each exercise is a relative path (e.g. `Barbell_Bench_Press_-_Medium_Grip/0.jpg`), not a full URL. If you want to use it as a poster or fallback, prepend your own image base URL.

Render snippet

function ExerciseVideo({ exercise }: { exercise: Exercise }) {
  const video = exercise.videos[0];
  if (!video) {
    return (
      <div
        role="img"
        aria-label={exercise.name + " (no video yet)"}
        className="aspect-[9/16] w-full max-w-sm bg-neutral-200"
      />
    );
  }
  return (
    <video
      src={video.url}
      autoPlay
      muted
      loop
      playsInline
      style={{ aspectRatio: video.aspectRatio.replace(":", " / ") }}
      className="w-full max-w-sm bg-black"
    />
  );
}

GET/v1/exercisesRequires X-API-Key

Search and browse exercises

Search, filter, paginate, or randomize the exercise catalog.

Query parameters

Name	Type	Required	Notes
q	string	No	Full-text search query. Length: 1 to 200 characters.
category	enum	No	Top-level training category. Allowed: strength, yoga, mobility, physical_therapy, stretching, pilates, calisthenics, plyometrics, conditioning, olympic_weightlifting, powerlifting, strongman
muscle	string	No	Display muscle group or anatomical muscle name. Length: 1 to 100 characters.
equipment	string	No	Equipment filter. Length: 1 to 100 characters.
level	enum	No	Difficulty level. Allowed: beginner, intermediate, advanced
force	enum	No	Movement force classification. Allowed: push, pull, static
mechanic	enum	No	Movement mechanic. Allowed: compound, isolation
random	boolean	No	Return random results instead of the default order. Default: false
limit	integer	No	Requested page size before plan-based clamping. Default: 20 Validated up to 100, then clamped to the plan cap.
offset	integer	No	Zero-based offset into the result set. Default: 0 Free tier requires `offset + limit <= 500`.

Request

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.exerciseapi.dev/v1/exercises?q=bench%20press&limit=10"

Response

{
  "data": [
    {
      "id": "Barbell_Bench_Press_-_Medium_Grip",
      "name": "Barbell Bench Press - Medium Grip",
      "keywords": [
        "bench press",
        "flat bench",
        "barbell press",
        "chest press",
        "BP",
        "bench",
        "flat barbell press"
      ],
      "primaryMuscles": [
        "pectoralis major sternal head",
        "pectoralis major clavicular head"
      ],
      "secondaryMuscles": [
        "deltoid anterior",
        "triceps brachii long head",
        "triceps brachii lateral head",
        "triceps brachii medial head"
      ],
      "equipment": "barbell",
      "force": "push",
      "level": "beginner",
      "mechanic": "compound",
      "category": "strength",
      "instructions": [
        "Lie back on a flat bench. Using a medium width grip (a grip that creates a 90-degree angle in the middle of the movement between the forearms and the upper arms), lift the bar from the rack and hold it straight over you with your arms locked. This will be your starting position.",
        "From the starting position, breathe in and begin coming down slowly until the bar touches your middle chest.",
        "After a brief pause, push the bar back to the starting position as you breathe out. Focus on pushing the bar using your chest muscles. Lock your arms and squeeze your chest in the contracted position at the top of the motion, hold for a second and then start coming down slowly again. Tip: Ideally, lowering the weight should take about twice as long as raising it."
      ],
      "exerciseTips": [
        "Retract your shoulder blades and maintain arch in your back",
        "Drive through your heels and engage your glutes for stability",
        "Lower the bar to your chest with control over 2-3 seconds"
      ],
      "commonMistakes": [
        "Bouncing the bar off the chest instead of controlled touch-and-go",
        "Flaring elbows too wide, creating shoulder impingement risk",
        "Lifting feet off the ground, reducing stability and power"
      ],
      "safetyInfo": "Always use a spotter or safety bars when lifting heavy weights. Avoid this exercise if you have shoulder impingement issues.",
      "overview": "The barbell bench press is a fundamental compound movement for building chest, shoulder, and tricep strength. It's considered the gold standard for upper body pressing power.",
      "variations": [
        "Machine Chest Press",
        "Single Arm Dumbbell Chest Press",
        "Standing Cable Chest Press",
        "Multi Grip Press",
        "Incline Push-Up Wide"
      ],
      "images": [
        "Barbell_Bench_Press_-_Medium_Grip/0.jpg",
        "Barbell_Bench_Press_-_Medium_Grip/1.jpg"
      ],
      "videos": [
        {
          "url": "https://cdn.exerciseapi.dev/v1/Barbell_Bench_Press_-_Medium_Grip.mp4",
          "format": "mp4",
          "resolution": "496x864",
          "aspectRatio": "9:16",
          "durationSeconds": 4,
          "generatedWith": "manual-upload",
          "generatedAt": "2026-04-12T00:00:00Z"
        }
      ]
    }
  ],
  "total": null,
  "limit": 10,
  "offset": 0
}

Behavior notes

`GET /v1/exercises` returns `total: null` when `q` is present. Filter-only requests return a numeric total.
`limit` is validated up to 100 and then clamped to your plan's per-request result cap.
Free-tier pagination depth is capped at `offset + limit <= 500`.
`muscle` accepts either a display group such as `chest` or an anatomical name.

GET/v1/exercises/:idRequires X-API-Key

Fetch one exercise

Return the full public exercise payload for a single ID.

Path parameters

Name	Type	Required	Notes
id	string	Yes	Exercise ID from list or search responses.

Request

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.exerciseapi.dev/v1/exercises/Barbell_Bench_Press_-_Medium_Grip"

Response

{
  "data": {
    "id": "Barbell_Bench_Press_-_Medium_Grip",
    "name": "Barbell Bench Press - Medium Grip",
    "keywords": [
      "bench press",
      "flat bench",
      "barbell press",
      "chest press",
      "BP",
      "bench",
      "flat barbell press"
    ],
    "primaryMuscles": [
      "pectoralis major sternal head",
      "pectoralis major clavicular head"
    ],
    "secondaryMuscles": [
      "deltoid anterior",
      "triceps brachii long head",
      "triceps brachii lateral head",
      "triceps brachii medial head"
    ],
    "equipment": "barbell",
    "force": "push",
    "level": "beginner",
    "mechanic": "compound",
    "category": "strength",
    "instructions": [
      "Lie back on a flat bench. Using a medium width grip (a grip that creates a 90-degree angle in the middle of the movement between the forearms and the upper arms), lift the bar from the rack and hold it straight over you with your arms locked. This will be your starting position.",
      "From the starting position, breathe in and begin coming down slowly until the bar touches your middle chest.",
      "After a brief pause, push the bar back to the starting position as you breathe out. Focus on pushing the bar using your chest muscles. Lock your arms and squeeze your chest in the contracted position at the top of the motion, hold for a second and then start coming down slowly again. Tip: Ideally, lowering the weight should take about twice as long as raising it."
    ],
    "exerciseTips": [
      "Retract your shoulder blades and maintain arch in your back",
      "Drive through your heels and engage your glutes for stability",
      "Lower the bar to your chest with control over 2-3 seconds"
    ],
    "commonMistakes": [
      "Bouncing the bar off the chest instead of controlled touch-and-go",
      "Flaring elbows too wide, creating shoulder impingement risk",
      "Lifting feet off the ground, reducing stability and power"
    ],
    "safetyInfo": "Always use a spotter or safety bars when lifting heavy weights. Avoid this exercise if you have shoulder impingement issues.",
    "overview": "The barbell bench press is a fundamental compound movement for building chest, shoulder, and tricep strength. It's considered the gold standard for upper body pressing power.",
    "variations": [
      "Machine Chest Press",
      "Single Arm Dumbbell Chest Press",
      "Standing Cable Chest Press",
      "Multi Grip Press",
      "Incline Push-Up Wide"
    ],
    "images": [
      "Barbell_Bench_Press_-_Medium_Grip/0.jpg",
      "Barbell_Bench_Press_-_Medium_Grip/1.jpg"
    ],
    "videos": [
      {
        "url": "https://cdn.exerciseapi.dev/v1/Barbell_Bench_Press_-_Medium_Grip.mp4",
        "format": "mp4",
        "resolution": "496x864",
        "aspectRatio": "9:16",
        "durationSeconds": 4,
        "generatedWith": "manual-upload",
        "generatedAt": "2026-04-12T00:00:00Z"
      }
    ]
  }
}

Behavior notes

Returns `404 NOT_FOUND` when the ID does not exist.
The public schema matches `transformExercise` and excludes internal fields such as `source`.
Exercise IDs use `Capitalized_Snake_Case` format (e.g. `Barbell_Bench_Press`). Always retrieve IDs from the `id` field of search/list responses — never construct them client-side from the `name` field, as the format is not a simple lowercase slug.

GET/v1/musclesRequires X-API-Key

List muscle groups

Return display groups and their anatomical muscle names.

Request

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.exerciseapi.dev/v1/muscles"

Response

{
  "data": [
    {
      "displayGroup": "chest",
      "muscles": [
        "pectoralis major clavicular head",
        "pectoralis minor",
        "pectoralis major sternal head"
      ]
    },
    {
      "displayGroup": "back",
      "muscles": [
        "trapezius lower",
        "erector spinae",
        "teres major",
        "latissimus dorsi"
      ]
    }
  ]
}

Behavior notes

Use `displayGroup` values for user-facing filter pickers.
The `muscle` search parameter accepts either a `displayGroup` or an anatomical muscle name.

GET/v1/equipmentRequires X-API-Key

List equipment

Return the canonical equipment names used by the API.

Request

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.exerciseapi.dev/v1/equipment"

Response

{
  "data": [
    "ab wheel",
    "barbell",
    "body only",
    "cable",
    "dumbbell"
  ]
}

Behavior notes

Equipment values are returned as a simple string array.

GET/v1/categoriesRequires X-API-Key

List categories

Return categories, counts, and descriptions.

Request

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.exerciseapi.dev/v1/categories"

Response

{
  "data": [
    {
      "category": "strength",
      "count": 742,
      "description": "Traditional resistance training"
    },
    {
      "category": "yoga",
      "count": 184,
      "description": "Asanas, flows, and breath work"
    }
  ]
}

Behavior notes

Descriptions are part of the response payload for each category.

GET/v1/statsRequires X-API-Key

Library stats

Return aggregate catalog metadata and category counts.

Request

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.exerciseapi.dev/v1/stats"

Response

{
  "data": {
    "totalExercises": 2198,
    "categories": {
      "strength": 742,
      "yoga": 184,
      "mobility": 133
    },
    "lastUpdated": "2026-03-31T04:12:00.000Z",
    "dataVersion": "2026-03-31"
  }
}

Behavior notes

Includes total exercise count, per-category counts, last import timestamp, and data version.

GET/v1/healthPublic

Health check

Return service health for Supabase and Redis dependencies.

Request

curl "https://api.exerciseapi.dev/v1/health"

Response

{
  "status": "ok",
  "version": "1.0.0",
  "dataVersion": "2026-03-31",
  "exerciseCount": 2198,
  "checks": {
    "supabase": "ok",
    "redis": "ok"
  }
}

Behavior notes

This is the only public endpoint that does not require `X-API-Key`.
Returns `503` only when Supabase is unavailable. Redis-only failures degrade to `200` with a `degraded` status.