Docs chevron_right Introduction

WorkoutX API
Reference

The WorkoutX API provides programmatic access to 1,400+ exercises complete with GIF animations, body part filters, target muscle data, equipment types, step-by-step instructions, and secondary muscle information.

Base URL

api.workoutxapp.com

Version

v1

Format

JSON

Auth

API Key

Quick Start

# Fetch 5 exercises using your API key
curl 'https://api.workoutxapp.com/v1/exercises?limit=5' \
  -H "X-WorkoutX-Key: wx_your_key_here"

Docs chevron_right Authentication

Authentication

All API requests require authentication via an API key. You can pass your key in one of two ways.

HTTP Header (Recommended)

Send the key as a request header. This is the preferred method as it keeps the key out of server logs.

curl 'https://api.workoutxapp.com/v1/exercises' \
  -H "X-WorkoutX-Key: wx_your_key_here"

Query Parameter

Append the key as a query string parameter. Convenient for quick tests.

curl 'https://api.workoutxapp.com/v1/exercises?api-key=wx_your_key_here'

info

Don't have an API key?

Register for a free account on the Developer Portal to get your key instantly. Free tier includes 500 requests per month.

Docs chevron_right Endpoints

Endpoints

All endpoints are prefixed with https://api.workoutxapp.com/v1. All responses are JSON.

GET /v1/exercises

List all exercises with pagination. Returns an array of exercise objects based on your plan's limit.

Query Parameters

Name	Type	Required	Description
`limit`	integer	No	Default: 10. Max depends on plan.
`offset`	integer	No	Default: 0. Number of results to skip.

Example Request

curl 'https://api.workoutxapp.com/v1/exercises?limit=2&offset=0' \
  -H "X-WorkoutX-Key: wx_your_key_here"

Example Response

[
  {
    "id": "0001",
    "name": "3/4 sit-up",
    "bodyPart": "waist",
    "target": "abs",
    "equipment": "body weight",
    "gifUrl": "https://[supabase-url]/storage/v1/object/public/exercise-gifs/0001.gif",
    "instructions": ["Lie down on your back..."],
    "secondaryMuscles": ["hip flexors", "lower back"]
  },
  // ...
]

GET /v1/exercises/exercise/:id

Get a single exercise by its unique ID. Returns a single exercise object or a 404 if the ID does not exist.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Exercise ID string, e.g. `"0001"`

Example Request

curl 'https://api.workoutxapp.com/v1/exercises/exercise/0001' \
  -H "X-WorkoutX-Key: wx_your_key_here"

Example Response

{
  "id": "0001",
  "name": "3/4 sit-up",
  "bodyPart": "waist",
  "target": "abs",
  "equipment": "body weight",
  "gifUrl": "https://[supabase-url]/storage/v1/object/public/exercise-gifs/0001.gif",
  "instructions": [
    "Lie down on your back with your knees bent and feet flat on the floor.",
    "Place your hands behind your head or across your chest.",
    "Slowly lift your upper body until you are about three-quarters of the way up.",
    "Lower yourself back down with control."
  ],
  "secondaryMuscles": ["hip flexors", "lower back"]
}

GET /v1/exercises/bodyPart/:bodyPart

Filter exercises by body part. Returns a paginated array of matching exercises.

Parameters

Name	Type	Required	Description
`bodyPart`	string (path)	Yes	One of: `back`, `cardio`, `chest`, `lower arms`, `lower legs`, `neck`, `shoulders`, `upper arms`, `upper legs`, `waist`
`limit`	integer (query)	No	Default: 10. Max depends on plan.
`offset`	integer (query)	No	Default: 0.

Example Request

curl 'https://api.workoutxapp.com/v1/exercises/bodyPart/chest?limit=5' \
  -H "X-WorkoutX-Key: wx_your_key_here"

Example Response

[
  {
    "id": "0009",
    "name": "barbell bench press",
    "bodyPart": "chest",
    "target": "pectorals",
    "equipment": "barbell",
    "gifUrl": "https://[supabase-url]/storage/v1/object/public/exercise-gifs/0009.gif",
    "secondaryMuscles": ["triceps", "delts"]
  },
  // ...
]

GET /v1/exercises/target/:target

Filter exercises by target muscle group. Returns a paginated array of matching exercises.

Parameters

Name	Type	Required	Description
`target`	string (path)	Yes	e.g. `abs`, `biceps`, `calves`, `cardiovascular system`, `delts`, `forearms`, `glutes`, `hamstrings`, `lats`, `pectorals`, `quads`, `traps`, `triceps`, `upper back`
`limit`	integer (query)	No	Default: 10. Max depends on plan.
`offset`	integer (query)	No	Default: 0.

Example Request

curl 'https://api.workoutxapp.com/v1/exercises/target/biceps?limit=5' \
  -H "X-WorkoutX-Key: wx_your_key_here"

Example Response

[
  {
    "id": "0023",
    "name": "barbell curl",
    "bodyPart": "upper arms",
    "target": "biceps",
    "equipment": "barbell",
    "secondaryMuscles": ["forearms"]
  },
  // ...
]

GET /v1/exercises/equipment/:equipment

Filter exercises by the equipment required. Returns a paginated array of matching exercises.

Parameters

Name	Type	Required	Description
`equipment`	string (path)	Yes	e.g. `barbell`, `body weight`, `cable`, `dumbbell`, `kettlebell`, `resistance band`, `smith machine`, and more
`limit`	integer (query)	No	Default: 10. Max depends on plan.
`offset`	integer (query)	No	Default: 0.

Example Request

curl 'https://api.workoutxapp.com/v1/exercises/equipment/dumbbell?limit=5' \
  -H "X-WorkoutX-Key: wx_your_key_here"

Example Response

[
  {
    "id": "0042",
    "name": "dumbbell bicep curl",
    "bodyPart": "upper arms",
    "target": "biceps",
    "equipment": "dumbbell",
    "secondaryMuscles": ["forearms"]
  },
  // ...
]

GET /v1/exercises/name/:name

Search exercises by name using partial string matching. Useful for autocomplete or free-text search features.

Parameters

Name	Type	Required	Description
`name`	string (path)	Yes	Partial name string. Case-insensitive match.

Example Request

curl 'https://api.workoutxapp.com/v1/exercises/name/squat' \
  -H "X-WorkoutX-Key: wx_your_key_here"

Example Response

[
  {
    "id": "0201",
    "name": "barbell squat",
    "bodyPart": "upper legs",
    "target": "quads",
    "equipment": "barbell"
  },
  {
    "id": "0202",
    "name": "goblet squat",
    "bodyPart": "upper legs",
    "target": "quads",
    "equipment": "kettlebell"
  },
  // ...
]

GET /v1/exercises/search Basic+

Multi-filter search allowing you to combine body part, target muscle, equipment type, and name in a single query. Available on Basic plan and above.

workspace_premium

This endpoint requires a Basic plan or higher. Free plan users will receive a 403 error.

Query Parameters

Name	Type	Required	Description
`bodyPart`	string	No	Filter by body part.
`target`	string	No	Filter by target muscle.
`equipment`	string	No	Filter by equipment.
`name`	string	No	Partial name search.
`limit`	integer	No	Default: 10. Max depends on plan.
`offset`	integer	No	Default: 0.

Example Request

curl 'https://api.workoutxapp.com/v1/exercises/search?bodyPart=chest&equipment=barbell&limit=5' \
  -H "X-WorkoutX-Key: wx_your_key_here"

Example Response

[
  {
    "id": "0009",
    "name": "barbell bench press",
    "bodyPart": "chest",
    "target": "pectorals",
    "equipment": "barbell",
    "secondaryMuscles": ["triceps", "delts"]
  },
  // ...
]

GET /v1/exercises/bodyPartList

Get the complete list of all available body parts. Useful for populating filter dropdowns in your UI.

info

No parameters required. Returns a simple array of strings.

Example Request

curl 'https://api.workoutxapp.com/v1/exercises/bodyPartList' \
  -H "X-WorkoutX-Key: wx_your_key_here"

Example Response

[
  "back",
  "cardio",
  "chest",
  "lower arms",
  "lower legs",
  "neck",
  "shoulders",
  "upper arms",
  "upper legs",
  "waist"
]

GET /v1/exercises/targetList

Get the complete list of all target muscles in the database. Use these values with the /target/:target endpoint.

Example Request

curl 'https://api.workoutxapp.com/v1/exercises/targetList' \
  -H "X-WorkoutX-Key: wx_your_key_here"

Example Response

[
  "abs",
  "biceps",
  "calves",
  "cardiovascular system",
  "delts",
  "forearms",
  "glutes",
  "hamstrings",
  "lats",
  "pectorals",
  "quads",
  "serratus anterior",
  "spine",
  "traps",
  "triceps",
  "upper back"
]

GET /v1/exercises/equipmentList

Get the complete list of all equipment types in the database. Use these values with the /equipment/:equipment endpoint.

Example Request

curl 'https://api.workoutxapp.com/v1/exercises/equipmentList' \
  -H "X-WorkoutX-Key: wx_your_key_here"

Example Response

[
  "barbell",
  "body weight",
  "cable",
  "dumbbell",
  "ez barbell",
  "kettlebell",
  "leverage machine",
  "medicine ball",
  "olympic barbell",
  "resistance band",
  "roller",
  "rope",
  "skierg machine",
  "sled machine",
  "smith machine",
  "stability ball",
  "stationary bike",
  "stepmill machine",
  "tire",
  "trap bar",
  "upper body ergometer",
  "weighted",
  "wheel roller"
]

GET /v1/exercises/:id/similar Smart ✨

Returns exercises similar to the given one, ranked by shared target muscle, body part, mechanics, force type, secondary muscles, and effort level. Each result includes a similarityScore (higher = more similar). Perfect for "you might also like" recommendations.

Query Parameters

Name	Type	Default	Description
`limit`	integer	10	Number of similar exercises to return
`offset`	integer	0	Pagination offset

Example Request

curl 'https://api.workoutxapp.com/v1/exercises/0025/similar?limit=5' \
  -H "X-WorkoutX-Key: wx_your_key_here"
              

Example Response

{
  "total": 312,
  "count": 5,
  "data": [
    {
      "id": "3294",
      "name": "Archer Push Up",
      "target": "Pectorals",
      "equipment": "Body Weight",
      "similarityScore": 115
    }
  ]
}
              

GET /v1/exercises/:id/alternatives Smart ✨

Find exercises that hit the same target muscle but use different equipment. Perfect for "I don't have a barbell at home" or "what can I do at the gym instead?" scenarios. Each result includes an alternativeScore.

Query Parameters

Name	Type	Description
`equipment`	string	Prefer alternatives using this equipment (e.g. `dumbbell`)
`excludeEquipment`	string	Exclude alternatives with this equipment (defaults to source exercise's equipment)
`limit`	integer	Results per page (default 10)

Example Request

curl 'https://api.workoutxapp.com/v1/exercises/0025/alternatives?equipment=dumbbell' \
  -H "X-WorkoutX-Key: wx_your_key_here"
              

Example Response

{
  "total": 48,
  "count": 3,
  "data": [
    {
      "id": "0289",
      "name": "Dumbbell Bench Press",
      "target": "Pectorals",
      "equipment": "Dumbbell",
      "alternativeScore": 115
    }
  ]
}
              

GET /v1/exercises/:id/calories Smart ✨

Estimate how many calories a user burns performing this exercise, scaled to their body weight. Uses MET-based formula: kcal = baseKcalPerMin × (weightKg / 70) × minutes. Every exercise in the database has a per-minute calorie value.

Query Parameters

Name	Type	Default	Description
`weightKg`	number	70	User's body weight in kilograms
`minutes`	number	10	Duration of the activity in minutes

Example Request

curl 'https://api.workoutxapp.com/v1/exercises/0025/calories?weightKg=80&minutes=15' \
  -H "X-WorkoutX-Key: wx_your_key_here"
              

Example Response

{
  "id": "0025",
  "name": "Barbell Bench Press",
  "bodyPart": "Chest",
  "target": "Pectorals",
  "weightKg": 80,
  "minutes": 15,
  "baseKcalPerMin": 5,
  "kcalPerMin": 5.71,
  "totalKcal": 85.7
}
              

GET /v1/workout/generate AI Generator Pro & Ultra

Generate a fully structured, ready-to-use workout plan with a single API call. Pass your user's goal, available time, fitness level, and equipment — the API returns a complete session with ordered exercises, sets, reps, and rest periods. Perfect for building AI-powered fitness apps, personalized training programs, or a "Today's Workout" feature without managing any exercise logic yourself.

auto_awesome

How the generator works

The engine filters exercises by your equipment and fitness level, then distributes them across the target muscle groups using the selected split. Compound movements are prioritized for strength/muscle gain goals; isolation movements are mixed in as accessories. Exercise count is automatically calculated to fit within your requested duration. Every call returns a freshly randomised selection — no two workouts are the same.

Query Parameters

Name	Type	Default	Description
`goal`	string	muscle_gain	`muscle_gain` · `strength` · `fat_loss` · `endurance` · `mobility`
`duration`	integer	45	Target workout length in minutes (20–120). Exercise count is auto-calculated to fit.
`level`	string	intermediate	`beginner` · `intermediate` · `advanced`
`split`	string	full_body	Which muscle groups to train in this session. `full_body` · `upper` · `lower` · `push` · `pull` · `legs` · `push_pull_legs` · `upper_lower` · `core`. Ignored if `bodyFocus` is provided.
`equipment`	string	—	Comma-separated list of available equipment (e.g. `barbell,dumbbell`). Omit to allow any equipment.
`bodyFocus`	string	—	Comma-separated body parts for full custom control (e.g. `chest,back`). Overrides `split`.
`exclude`	string	—	Comma-separated exercise IDs to exclude (e.g. exercises the user dislikes or already did today).

Example Requests

1 — Quick full-body workout (defaults)

curl 'https://api.workoutxapp.com/v1/workout/generate' \
  -H "X-WorkoutX-Key: wx_your_key_here"
              

2 — 30-minute beginner fat-loss session, bodyweight only

curl 'https://api.workoutxapp.com/v1/workout/generate?goal=fat_loss&duration=30&level=beginner&equipment=body+weight&split=full_body' \
  -H "X-WorkoutX-Key: wx_your_key_here"
              

3 — Advanced push day, barbell + dumbbell, exclude specific exercises

curl 'https://api.workoutxapp.com/v1/workout/generate?goal=muscle_gain&duration=60&level=advanced&split=push&equipment=barbell,dumbbell&exclude=0025,0034' \
  -H "X-WorkoutX-Key: wx_your_key_here"
              

Example Response

{
  "goal": "muscle_gain",
  "level": "intermediate",
  "split": "push",
  "bodyFocus": ["chest", "shoulders", "upper arms"],
  "equipment": ["barbell", "dumbbell"],
  "totalExercises": 5,
  "estimatedDurationMinutes": 42,
  "exercises": [
    {
      "order": 1,
      "sets": 4,
      "reps": "6-8",
      "restSeconds": 90,
      "note": "Primary compound movement",
      "exercise": {
        "id": "0025",
        "name": "Barbell Bench Press",
        "bodyPart": "Chest",
        "target": "Pectorals",
        "equipment": "Barbell",
        "gifUrl": "https://api.workoutxapp.com/v1/gifs/0025.gif"
      }
    },
    // ... more exercises
  ]
}
              

Split Reference

split value	Muscle groups trained
`full_body`	Chest, back, shoulders, legs, arms — balanced full session
`upper`	Chest, back, shoulders, upper & lower arms
`lower`	Quads, hamstrings, calves, lower back, core
`push`	Chest, shoulders, triceps
`pull`	Back, biceps, forearms
`legs`	Quads, hamstrings, calves, lower back
`push_pull_legs`	Full body PPL — all major groups in one session
`upper_lower`	Upper body focus — chest, back, shoulders, arms
`core`	Abs, lower back — targeted core session

Use bodyFocus for fully custom muscle group selection — it overrides split.

Docs chevron_right Rate Limits

Rate Limits

All plans are subject to both per-minute rate limits and monthly quotas. Exceeding either returns a 429 Too Many Requests response.

Plan	Monthly Quota	Rate Limit	Max Results
Free	500 / month	30 / min	10 per request
Basic	3,000 / month	150 / min	100 per request
Pro	10,000 / month	300 / min	Unlimited
Ultra	35,000 / month	600 / min	Unlimited

Response Headers

Every API response includes the following headers so you can monitor your usage programmatically:

Header	Description
`X-WorkoutX-Plan`	Your current subscription plan name.
`X-RateLimit-Limit`	Maximum requests allowed per minute.
`X-RateLimit-Remaining`	Requests remaining in the current minute window.
`X-Quota-Limit`	Total monthly quota for your plan.
`X-Quota-Remaining`	Requests remaining in the current monthly period.
`X-Quota-Reset`	Unix timestamp of when the monthly quota resets.

Reading Headers in Code

# Include -I to print response headers
curl -sI 'https://api.workoutxapp.com/v1/exercises?limit=1' \
  -H "X-WorkoutX-Key: wx_your_key_here"

# Example response headers:
X-WorkoutX-Plan: pro
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-Quota-Limit: 10000
X-Quota-Remaining: 9847
X-Quota-Reset: 1743379200

Docs chevron_right Error Codes

Error Codes

The API uses standard HTTP status codes. All error responses return a JSON body with a message field explaining what went wrong.

Status Code	Error	Description
`401`	Unauthorized	Missing or invalid API key. Verify your key is correct and included in the request.
`403`	Forbidden	Your API key or account has been disabled, or you are accessing a feature not available on your plan.
`404`	Not Found	The requested exercise ID does not exist in the database.
`429`	Too Many Requests	You have exceeded your per-minute rate limit or monthly quota. Check rate limit headers for reset timing.

Example Error Responses

// HTTP 401 Unauthorized
{
  "error": "Unauthorized",
  "message": "Missing or invalid API key. Pass your key via X-WorkoutX-Key header.",
  "status": 401
}

// HTTP 429 Too Many Requests
{
  "error": "Too Many Requests",
  "message": "Monthly quota exceeded. Upgrade your plan or wait for reset.",
  "status": 429
}

// HTTP 404 Not Found
{
  "error": "Not Found",
  "message": "Exercise with ID '9999' does not exist.",
  "status": 404
}

Docs chevron_right Plans

Plans & Quotas

Choose a plan that matches your usage. All plans include access to the full exercise database and GIF library.

Free

$0/mo

check_circle 500 req / month
check_circle 30 req / min
check_circle Max 10 results
remove_circle Multi-filter search

Basic

$9.99/mo

check_circle 3,000 req / month
check_circle 150 req / min
check_circle Max 100 results
check_circle Multi-filter search

Pro

Popular

$15.99/mo

check_circle 10,000 req / month
check_circle 300 req / min
check_circle Unlimited results
check_circle Multi-filter search

Ultra

$24.99/mo

check_circle 35,000 req / month
check_circle 600 req / min
check_circle Unlimited results
check_circle Multi-filter search

Ready to get started?

Create your account and get an API key in under a minute. Free plan, no credit card required.

vpn_key Get API Key Free

WorkoutX API Reference

Authentication

HTTP Header (Recommended)

Query Parameter

Endpoints

Query Parameters

Example Request

Example Response

Path Parameters

Example Request

Example Response

Parameters

Example Request

Example Response

Parameters

Example Request

Example Response

Parameters

Example Request

Example Response

Parameters

Example Request

Example Response

Query Parameters

Example Request

Example Response

Example Request

Example Response

Example Request

Example Response

Example Request

Example Response

Query Parameters

Example Request

Example Response

Query Parameters

Example Request

Example Response

Query Parameters

Example Request

Example Response

Query Parameters

Example Requests

Example Response

Split Reference

Rate Limits

Response Headers

Reading Headers in Code

Error Codes

Example Error Responses

Plans & Quotas

WorkoutX API
Reference