Body Scan API chevron_right Introduction

Body Scan API

Reference

The WorkoutX Body Scan API provides photo-based body composition analysis for fitness apps, telehealth platforms, and health tools. Send a single photo and receive body fat percentage, muscle score, body type, posture analysis, and estimated measurements — all as structured JSON.

Version

v1

Format

JSON

Auth

X-BodyScan-Key

Quick Start

# Analyze a body photo
curl -X POST 'https://amused-mercy-production-aeaa.up.railway.app/v1/analyze' \
  -H "X-BodyScan-Key: bsk_your_key_here" \
  -F "front_photo=@/path/to/photo.jpg" \
  -F "height_cm=178" \
  -F "weight_kg=80" \
  -F "age=28" \
  -F "gender=male"

Body Scan API chevron_right Authentication

Authentication

All Body Scan API requests require a X-BodyScan-Key header. Get your key from the Developer Portal after purchasing a credit pack.

curl -X POST 'https://amused-mercy-production-aeaa.up.railway.app/v1/analyze' \
  -H "X-BodyScan-Key: bsk_your_key_here" \
  ...
            

Key format: All Body Scan API keys begin with bsk_ — different from WorkoutX Exercise API keys (wx_). Each key belongs to a separate account.

Body Scan API chevron_right POST /analyze

POST /v1/analyze

Analyze Body Photo

The core endpoint. Send a photo with biometric data, receive full body composition analysis as JSON. Consumes 1 credit per successful call.

tips_and_updates

Always send a side photo when you can

A single front photo is a 2D estimate, so the underlying analysis methods can disagree with each other — that's why front-only scans return a body_fat_range (e.g. 13.1–16.1%, medium confidence) instead of one number. Adding side_photo gives the engine real depth/circumference data — the methods converge tightly, the margin narrows to ~±2%, and you get back a single precise body_fat_percentage instead. We'd rather show you an honest range than fake precision — but a 10-second second photo gets you the precise number.

Request

Content-Type: multipart/form-data

Field	Type	Required	Description
`front_photo`	file	required	Front-facing full-body photo. JPEG, PNG, or WebP. Max 15MB.
`height_cm`	number	required	Height in centimetres. Range: 100–250.
`weight_kg`	number	required	Weight in kilograms. Range: 30–300.
`age`	integer	required	Age in years. Range: 13–100.
`gender`	string	required	`male` or `female`
`side_photo`	file	optional	Side-facing photo. Enables 3D circumference calculation, narrows the body fat margin to ~±2%, and returns a single precise `body_fat_percentage` instead of a `body_fat_range` — we strongly recommend including it.
`goal`	string	optional	`fat_loss` · `muscle_gain` · `maintenance` · `general`. Personalises AI insights.
`external_user_id`	string	optional	Your app's user ID. Stored with the scan for history and progress tracking.

Response

{
  "scan_id": "bscan_7xK9mP",

  "body_composition": {
    "body_fat_percentage": 14.6,
    "body_fat_category":   "Fitness",
    "body_fat_mass_kg":    9.9,
    "lean_mass_kg":        58.1,
    "body_type":           "Ecto-Mesomorph",
    "bmi":                 21.0,
    "bmi_category":        "Normal",
    "body_fat_range": {  // front-photo-only scans — omitted when you also send side_photo
      "low":        13.1,
      "high":       16.1,
      "confidence": "medium",  // "high" | "medium" | "low"
      "note":       "Single-photo estimates vary by analysis method — this range reflects that. Add a side photo for a single precise number."
    }
  },

  "scores": {
    "muscle_score":   53,
    "symmetry_score": 99.0,
    "fitness_score":  80
  },

  "estimated_measurements": {
    "shoulder_width_cm":       44.2,
    "waist_circumference_cm":  78.5,
    "hip_circumference_cm":    91.2,
    "waist_to_hip_ratio":      0.86
  },

  "ai_insights": {
    "body_type_detail":        "Athletic frame with good muscle-building potential.",
    "posture_notes":           "Neutral posture, shoulders level.",
    "fat_distribution":        "balanced",
    "muscle_definition_score":  7
  },

  "photo_guidance": null,  // non-null if clothing/pose issues detected

  "credits": {
    "used": 1,
    "remaining": 499
  },

  "meta": {
    "formula_version":      "v1.0",
    "overall_confidence":   0.87,
    "processing_ms":        2731,
    "disclaimer":           "Estimates only. ±3-5% margin for body fat."
  },

  "created_at": "2025-06-03T10:00:00Z"
}
            

Code Examples

JavaScript (fetch)

const form = new FormData();
form.append('front_photo', photoFile);
form.append('height_cm', '178');
form.append('weight_kg', '80');
form.append('age', '28');
form.append('gender', 'male');

const res = await fetch('https://amused-mercy-production-aeaa.up.railway.app/v1/analyze', {
  method: 'POST',
  headers: { 'X-BodyScan-Key': 'bsk_your_key_here' },
  body: form
});
const data = await res.json();
console.log(data.body_composition.body_fat_percentage); // 14.6
              

Python (requests)

import requests

files = {'front_photo': open('photo.jpg', 'rb')}
data  = {
    'height_cm': '178', 'weight_kg': '80',
    'age': '28', 'gender': 'male'
}
r = requests.post(
    'https://amused-mercy-production-aeaa.up.railway.app/v1/analyze',
    headers={'X-BodyScan-Key': 'bsk_your_key_here'},
    files=files, data=data
)
print(r.json()['body_composition']['body_fat_percentage'])
              

Body Scan API chevron_right POST /feedback

POST /v1/:scanId/feedback

Submit Feedback

Submit your actual measured body fat percentage to help calibrate the AI model. High-quality feedback (DEXA, hydrostatic, caliper) earns +3 bonus scan credits.

Field	Type	Description
`actual_body_fat`	number	Actual body fat %. Used to calibrate formula weights.
`actual_weight_kg`	number	Optional weight verification.
`feedback_type`	string	`dexa` · `hydrostatic` · `caliper` → +3 credits · `scale` · `self_estimate` → no bonus

curl -X POST 'https://amused-mercy-production-aeaa.up.railway.app/v1/bscan_7xK9mP/feedback' \
  -H "X-BodyScan-Key: bsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"actual_body_fat": 13.8, "feedback_type": "dexa"}'

// Response
{
  "status": "accepted",
  "bonus_credits": 3,
  "new_balance": 502
}
            

Body Scan API chevron_right GET /history

GET /v1/history

Scan History

Returns past scans for your account. Filter by external_user_id to get history for a specific end-user in your app.

curl 'https://amused-mercy-production-aeaa.up.railway.app/v1/history?external_user_id=usr_123&limit=10' \
  -H "X-BodyScan-Key: bsk_your_key_here"

// Response
{
  "scans": [
    {
      "id": "bscan_7xK9mP",
      "body_fat_pct": 14.6,
      "muscle_score": 53,
      "body_type": "Ecto-Mesomorph",
      "created_at": "2025-06-03T10:00:00Z"
    }
  ]
}
            

Body Scan API chevron_right GET /progress

GET /v1/progress

Progress Comparison

Compare two scans to show a user's progress. Returns body fat change, muscle score change, weight change, and a trend summary.

curl 'https://amused-mercy-production-aeaa.up.railway.app/v1/progress?from_scan_id=bscan_abc&to_scan_id=bscan_xyz' \
  -H "X-BodyScan-Key: bsk_your_key_here"

// Response
{
  "period_days": 30,
  "changes": {
    "body_fat_change":     -2.1,
    "muscle_score_change": +4,
    "weight_change_kg":    -1.5
  },
  "trend": "positive",
  "summary": "In 30 days: Lost 2.1% body fat, muscle score improved by 4 points."
}
            

Body Scan API chevron_right Credits & Billing

Credits & Billing

Body Scan API uses a one-time credit pack system. No subscriptions. Credits never expire. Each successful POST /analyze call consumes 1 credit.

GET /v1/billing/packs — List all available credit packs

{
  "packs": [
    { "id": "trial",   "scans": 10,   "price_usd": 19,   "price_per_scan": 1.90 },
    { "id": "starter", "scans": 100,  "price_usd": 199,  "price_per_scan": 1.99 },
    { "id": "growth",  "scans": 500,  "price_usd": 899,  "price_per_scan": 1.80 },
    { "id": "scale",   "scans": 1000, "price_usd": 1499, "price_per_scan": 1.499 }
  ]
}
            

POST /v1/billing/checkout — Create Stripe checkout session (requires JWT)

curl -X POST 'https://amused-mercy-production-aeaa.up.railway.app/v1/billing/checkout' \
  -H "Authorization: Bearer jwt_token" \
  -H "Content-Type: application/json" \
  -d '{"pack_id": "growth"}'

// Response
{ "checkout_url": "https://checkout.stripe.com/..." }
            

POST /v1/billing/enterprise — Enterprise inquiry (10,000+ scans)

curl -X POST 'https://amused-mercy-production-aeaa.up.railway.app/v1/billing/enterprise' \
  -H "Content-Type: application/json" \
  -d '{"email":"dev@company.com","company":"FitApp","volume":"50000"}'
            

Body Scan API chevron_right Photo Guidelines

Photo Guidelines

Follow these guidelines to maximise accuracy. Poor photos reduce confidence score and may disable some features.

check_circle Do

• Stand facing directly toward the camera
• Full body visible — head to ankles
• Wear underwear, fitted sports gear, or swimwear
• Arms slightly away from body
• Good, even lighting
• Plain or simple background

cancel Avoid

• Loose, baggy clothing (inflates waist measurement)
• Side angles or tilted body
• Cropped photos (head or feet cut off)
• Dark or very bright lighting
• Blurry or low-resolution photos
• Multiple people in frame

Clothing detection: If loose clothing is detected, the API automatically disables the Navy body fat formula (which requires accurate waist measurements) and returns a photo_guidance object with improvement tips. Body fat is still estimated via AI vision + BMI formulas.

Body Scan API chevron_right Credits & Pricing

Credits & Pricing

One-time credit packs. No subscriptions. Credits never expire. All packs include the full feature set.

Pack	Scans	Price	Per Scan
trial	10	$19	$1.90
starter	100	$199	$1.99
growth ★ Popular	500	$899	$1.80
scale	1,000	$1,499	$1.499
enterprise	10,000+	Custom	Contact Us

Body Scan API chevron_right Error Codes

Error Codes

All errors return JSON with error and message fields.

Status	Error	Cause
`400`	Bad Request	Missing required field or invalid value (e.g. gender not "male"/"female")
`401`	Unauthorized	Missing or invalid `X-BodyScan-Key` header
`402`	No Credits	Credit balance is 0. Purchase a pack to continue.
`409`	Trial Already Used	Trial pack can only be purchased once per account
`422`	Unprocessable	No person detected in photo, or body landmarks not visible enough
`503`	Service Unavailable	Scan engine temporarily unavailable. Retry after a few seconds.

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.

What's New · Jun 2026

health_and_safety Joint & Rehab Metadata is here — every exercise now ships with derived joint_focus, intensity_level, and movement_tags fields, and Ultra plan keys can filter /v1/exercises/search directly by joint, intensity, and movement tag. Built for physical therapy, rehab, mobility, and senior-fitness apps.

See the docs arrow_forward

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
`bodyPart`	string	No	Filter by body part, e.g. `chest`. Case-insensitive.
`target`	string	No	Filter by target muscle, e.g. `pectorals`.
`equipment`	string	No	Filter by equipment, e.g. `barbell`.
`name`	string	No	Partial name match, e.g. `squat`.
`effortLevel`	string	No	`beginner` · `intermediate` · `advanced`. Filters on `difficulty`.
`mechanics`	string	No	`compound` · `isolation`. Filters on `mechanic`.
`force`	string	No	`push` · `pull` · `hold` · `carry`.
`isUnilateral`	boolean	No	Single-sided / alternating movements only.
`sortMethod`	string	No	Sort by `name`, `bodyPart`, `target`, `equipment`, `effortLevel`, `mechanics`, `force`, `popularityRank`, or `caloriesBurnPerMin`.
`sortOrder`	string	No	`ascending` (default) · `descending`.
`limit`	integer	No	Default: 10. Max depends on plan.
`offset`	integer	No	Default: 0. Number of results to skip.
`lang`	string	No	🌍 Localize the response. `en` (default) · `de` · `es` · `fr` · `zh-SG` · `zh-HK`. Translates exercise names, instructions, body part, equipment, target, and category fields. Falls back to English for any untranslated exercise.

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",
    "difficulty": "beginner",
    "mechanic": "isolation",
    "force": "push",
    "caloriesPerMinute": 4.3,
    "popularityRank": 5,
    "gifUrl": "https://api.workoutxapp.com/v1/gifs/0001.gif"
    // + isUnilateral, recommendedSets/Reps, met, category, description, instructions, secondaryMuscles
  },
  // ...
]

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"`

Query Parameters

Name	Type	Required	Description
`lang`	string	No	🌍 Localize the response. `en` (default) · `de` · `es` · `fr` · `zh-SG` · `zh-HK`. Translates name, instructions, bodyPart, equipment, target, category, difficulty, mechanic, and force. Falls back to English if the exercise has no translation yet.

Example Request

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

Example Response

{
  "id": "0001",
  "name": "3/4 Sit-up",
  "bodyPart": "Waist",
  "target": "Abs",
  "equipment": "Body Weight",
  "secondaryMuscles": ["Hip Flexors", "Lower Back"],
  "instructions": [
    "Lie flat on your back with your knees bent and feet flat on the ground.",
    "Place your hands behind your head with your elbows pointing outwards.",
    "Engaging your abs, slowly lift your upper body off the ground..."
  ],
  "gifUrl": "https://api.workoutxapp.com/v1/gifs/0001.gif",
  "category": "strength",
  "difficulty": "beginner",
  "mechanic": "isolation",
  "force": "push",
  "met": 3.5,
  "caloriesPerMinute": 4.3,
  "description": "3/4 Sit-up is a beginner single-joint isolation pushing exercise...",
  "isUnilateral": false,
  "popularityRank": 5,
  "recommendedSets": "3",
  "recommendedReps": "10-15",
  // Ultra plan — derived Joint & Rehab Metadata:
  "joint_focus": "lumbar_spine",
  "intensity_level": "gentle",
  "movement_tags": ["beginner-friendly", "controlled-movement", "minimal-equipment"]
}

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.
`lang`	string (query)	No	🌍 Localize the response. `en` (default) · `de` · `es` · `fr` · `zh-SG` · `zh-HK`. Falls back to English for any untranslated exercise.

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.
`lang`	string (query)	No	🌍 Localize the response. `en` (default) · `de` · `es` · `fr` · `zh-SG` · `zh-HK`. Falls back to English for any untranslated exercise.

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.
`lang`	string (query)	No	🌍 Localize the response. `en` (default) · `de` · `es` · `fr` · `zh-SG` · `zh-HK`. Falls back to English for any untranslated exercise.

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.
`jointFocus` Ultra	string	No	Filter by the derived primary joint a movement acts through (e.g. `knee`, `shoulder`, `lumbar_spine`). Part of Joint & Rehab Metadata — Ultra plan.
`intensityLevel` Ultra	string	No	Filter by derived overall-exertion band: `gentle`, `moderate`, or `vigorous` (computed from MET). Joint & Rehab Metadata — Ultra plan.
`movementTag` Ultra	string	No	Filter by a derived descriptive tag — e.g. `joint-friendly`, `beginner-friendly`, `controlled-movement`, `low-intensity`, `minimal-equipment`. Joint & Rehab Metadata — Ultra plan.
`limit`	integer	No	Default: 10. Max depends on plan.
`offset`	integer	No	Default: 0.
`lang`	string	No	🌍 Localize the response. `en` (default) · `de` · `es` · `fr` · `zh-SG` · `zh-HK`.

health_and_safety

Joint & Rehab Metadata (Ultra): every exercise record also ships with derived joint_focus, intensity_level, and movement_tags fields — computed from existing attributes (target muscle, difficulty, mechanic, MET). Ultra plan keys can filter directly on these via jointFocus, intensityLevel, and movementTag — handy for physical therapy, mobility, and senior-fitness style "gentle movement" shortlists. These are descriptive, anatomical/biomechanical fields, not medical or clinical recommendations — see our guide for details and examples.

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: Joint & Rehab Metadata Query Ultra

A "gentle movements" shortlist for the knee — beginner-level, single-joint, joint-friendly:

curl 'https://api.workoutxapp.com/v1/exercises/search?jointFocus=knee&effortLevel=beginner&movementTag=joint-friendly&limit=5' \
  -H "X-WorkoutX-Key: wx_your_ultra_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).
`seed`	string	—	Pass a seed for a reproducible plan (same seed + params → same workout). Omit for a fresh plan; the response always returns the `seed` used so you can reproduce it.

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",
  "seed": "06vhrfi3",
  "split": "push",
  "bodyFocus": ["chest", "shoulders", "upper arms"],
  "equipment": ["barbell", "dumbbell"],
  "totalExercises": 5,
  "estimatedDurationMinutes": 47,
  "warmup": [
    { "activity": "Light cardio", "durationMinutes": 3, "note": "Raise core temperature..." }
    // + dynamic mobility, ramp-up sets
  ],
  "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
  ],
  "cooldown": [
    { "activity": "Static stretching", "durationMinutes": 3, "note": "Hold ~30s each..." }
  ]
}
              

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.

GET /v1/workout/program New Ultra

Generate a periodised, multi-week training program with progressive overload. Exercises stay fixed per training day so users can add load/reps week to week, while sets and intensity follow a 4-week undulating block — three build weeks (RPE 7 → 8 → 9) followed by a deload — that repeats for the program length. Goes beyond single-session generation (/v1/workout/generate) for apps that ship full training plans.

Query Parameters

Name	Type	Description
`goal`	string	`muscle_gain` · `strength` · `fat_loss` · `endurance` · `mobility`
`level`	string	`beginner` · `intermediate` · `advanced`
`weeks`	integer	Program length, 2–12. Default 4.
`daysPerWeek`	integer	Training days per week, 2–6 (sets the weekly split). Default 3.
`duration`	integer	Per-session minutes, 20–120. Default 60.
`equipment`	string	Comma-separated available equipment. Omit for any.

Example Request

curl 'https://api.workoutxapp.com/v1/workout/program?goal=muscle_gain&level=intermediate&weeks=8&daysPerWeek=4&equipment=barbell,dumbbell' \
  -H "X-WorkoutX-Key: wx_your_ultra_key_here"
              

Example Response

{
  "goal": "muscle_gain",
  "level": "intermediate",
  "weeks": 8,
  "daysPerWeek": 4,
  "split": ["upper", "lower", "upper", "lower"],
  "progressionModel": "4-week undulating block (3 build weeks + deload), repeating",
  "program": [
    {
      "week": 1,
      "phase": "accumulation",
      "intensity": "RPE 7",
      "deload": false,
      "guidance": "Build week 1 — leave ~3 reps in reserve...",
      "days": [ /* fixed exercises with sets/reps/intensity */ ]
    },
    // week 3 → RPE 9 + extra set, week 4 → deload, then repeats
  ]
}
              

GET /v1/exercises/changes New Ultra

Keep a local mirror of the dataset in sync. Returns exercises added or updated on or after the since date — newest first, each annotated with addedAt, updatedAt, and changeType (added | updated). Poll it on a schedule to receive new exercises and GIFs added during your subscription, without re-pulling the entire catalogue.

Query Parameters

Name	Type	Required	Description
`since`	ISO date	Yes	Returns items changed on or after this, e.g. `2026-01-01`.
`limit`	integer	No	Page size.
`offset`	integer	No	Results to skip.

Example Request

curl 'https://api.workoutxapp.com/v1/exercises/changes?since=2026-01-01' \
  -H "X-WorkoutX-Key: wx_your_ultra_key_here"
              

Example Response

{
  "since": "2026-01-01T00:00:00.000Z",
  "asOf": "2026-06-16T10:00:00.000Z",
  "total": 3,
  "count": 3,
  "data": [
    {
      "id": "5202",
      "name": "Front Plank",
      "changeType": "added",
      "addedAt": "2026-06-14T...",
      "updatedAt": "2026-06-14T..."
      // + full exercise fields
    }
  ]
}
              

GET /v1/supplements New Pro & Ultra

A curated database of 29 evidence-rated supplements — proteins, creatine, pre-workout ingredients, vitamins, minerals, and joint-support compounds. Each record includes typical dosage, intake timing, training goals, an evidence_level rating (strong / moderate / emerging), benefits, stacking suggestions, and practical considerations. Perfect for adding a supplement guide or nutrition layer to your fitness app.

info

Informational content — not medical advice

The dataset contains no medical claims. Every response includes a disclaimer field advising users to consult a healthcare professional. Content is ranked by research evidence level so your users always see the best-supported options first.

Query Parameters

Name	Type	Description
`category`	string	`protein` · `performance` · `pre_workout` · `amino_acids` · `vitamins_minerals` · `hydration` · `recovery` · `joint_support` · `adaptogens` · `general_health`
`goal`	string	`muscle_gain` · `strength` · `fat_loss` · `endurance` · `recovery` · `mobility` · `general_health`
`timing`	string	`pre_workout` · `intra_workout` · `post_workout` · `morning` · `evening` · `with_meals` · `any_time`
`evidence`	string	`strong` · `moderate` · `emerging` — filter by research evidence level
`search`	string	Search by name, summary, or category (e.g. `creatine`)
`limit` / `offset`	integer	Standard pagination — same behaviour as `/v1/exercises`

Related Endpoints

Endpoint	Plan	Description
`/v1/supplements/{id}`	Pro+	Single supplement by ID (e.g. `creatine-monohydrate`)
`/v1/supplements/exercise/{exerciseId}`	Pro+	Supplements relevant to a given exercise — resistance exercises return strength-focused picks, cardio exercises return endurance & hydration picks
`/v1/supplements/filters`	Pro+	All available categories, goals, timings & evidence levels with counts
`/v1/supplements/stack`	Ultra	Goal-based stack builder — ordered supplement stack with a timing guide. `goal` required; `level` = `essential` (3) · `standard` (5) · `comprehensive` (8)

Example Requests

1 — Strong-evidence supplements for muscle gain

curl 'https://api.workoutxapp.com/v1/supplements?goal=muscle_gain&evidence=strong' \
  -H "X-WorkoutX-Key: wx_your_key_here"
              

2 — Supplements relevant to Barbell Bench Press

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

3 — Ultra: essential fat-loss stack with timing guide

curl 'https://api.workoutxapp.com/v1/supplements/stack?goal=fat_loss&level=essential' \
  -H "X-WorkoutX-Key: wx_your_key_here"
              

Example Response

{
  "id": "creatine-monohydrate",
  "name": "Creatine Monohydrate",
  "category": "performance",
  "goals": ["muscle_gain", "strength"],
  "timing": ["any_time"],
  "typical_dosage": "3-5 g daily",
  "evidence_level": "strong",
  "summary": "One of the most researched sports supplements...",
  "benefits": ["Extensively studied for strength and power performance", ...],
  "stacks_well_with": ["whey-protein", "carbohydrate-powder"],
  "considerations": "Daily consistency matters more than timing...",
  "disclaimer": "Informational content only — not medical advice..."
}
              

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 metadata; GIF library limits vary by plan.

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
check_circle 500 unique exercise GIFs

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
health_and_safety Joint & Rehab Metadata New

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

Body Scan API

Reference

Authentication

Analyze Body Photo

Request

Response

Code Examples

Submit Feedback

Scan History

Progress Comparison

Credits & Billing

Photo Guidelines

check_circle Do

cancel Avoid

Credits & Pricing

Error Codes

WorkoutX API Reference

Authentication

HTTP Header (Recommended)

Query Parameter

Endpoints

Query Parameters

Example Request

Example Response

Path Parameters

Query 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: Joint & Rehab Metadata Query Ultra

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

Query Parameters

Example Request

Example Response

Query Parameters

Example Request

Example Response

Query Parameters

Related Endpoints

Example Requests

Example Response

Rate Limits

Response Headers

Reading Headers in Code

Error Codes

Example Error Responses

Plans & Quotas

WorkoutX API
Reference