Docs chevron_right Introduction

WorkoutX API
Reference

The WorkoutX API provides programmatic access to 1,321 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"
]

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

Rate Limits

Response Headers

Reading Headers in Code

Error Codes

Example Error Responses

Plans & Quotas

WorkoutX API
Reference