API Documentation

Everything you need to integrate MusclesWorked into your application.

Introduction

The MusclesWorked API provides programmatic access to our exercise-to-muscle mapping database. Query 856 exercises across 63 muscles with 7,310+ mappings. Available as both a REST API and an MCP server for AI agents.

Base URL

https://musclesworked.com/api/v1

All REST endpoints are prefixed with /api/v1. The API returns JSON responses with Content-Type: application/json.

Authentication

All /api/v1 endpoints require authentication. Pass your API key via the X-Api-Key header:

Request Header

X-Api-Key: mw_live_abc123...

You can also use the Authorization header with a Bearer token (Cognito JWT) for session-based authentication:

Bearer Token

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

To get an API key, sign in to the dashboard and create one from the API Keys page.

Endpoints

Browse

GET /exercises

Browse the full exercise catalog with optional filters and pagination.

Parameter	Type	In	Description
`equipment` optional	string	query	Filter by equipment type
`difficulty` optional	string	query	Filter by difficulty level
`movement_pattern` optional	string	query	Filter by movement pattern
`exercise_type` optional	string	query	`compound`, `isolation`, or `isometric`
`force_type` optional	string	query	`push`, `pull`, or `static`
`laterality` optional	string	query	`bilateral` or `unilateral`
`offset` optional	integer	query	Pagination offset (default: 0)
`limit` optional	integer	query	Page size (1-200, default: 50)

Request

curl "https://musclesworked.com/api/v1/exercises?equipment=barbell&difficulty=beginner&limit=3" \
  -H "X-Api-Key: mw_live_abc123"

Response

{
  "exercises": [
    {
      "id": "barbell_curl",
      "name": "Barbell Curl",
      "movement_pattern": "flexion",
      "equipment": "barbell",
      "difficulty": "beginner",
      "exercise_type": "isolation",
      "laterality": "bilateral",
      "force_type": "pull"
    }
  ],
  "total": 42,
  "offset": 0,
  "limit": 3
}

GET /muscles

Browse the full muscle catalog with optional group filter and pagination.

Parameter	Type	In	Description
`group` optional	string	query	Filter by muscle group (e.g. `chest`, `back`)
`offset` optional	integer	query	Pagination offset (default: 0)
`limit` optional	integer	query	Page size (1-200, default: 100)

Request

curl "https://musclesworked.com/api/v1/muscles?group=chest" \
  -H "X-Api-Key: mw_live_abc123"

Response

{
  "muscles": [
    { "id": "pectoralis_major_sternal", "name": "Pectoralis Major (Sternal)", "group": "chest" },
    { "id": "pectoralis_major_clavicular", "name": "Pectoralis Major (Clavicular)", "group": "chest" },
    { "id": "pectoralis_minor", "name": "Pectoralis Minor", "group": "chest" }
  ],
  "total": 3,
  "offset": 0,
  "limit": 100
}

GET /muscle-groups

List all muscle groups with muscle counts and member muscles. No filters or pagination needed.

Request

curl https://musclesworked.com/api/v1/muscle-groups \
  -H "X-Api-Key: mw_live_abc123"

Response

{
  "groups": [
    {
      "group": "chest",
      "group_label": "Chest",
      "muscle_count": 3,
      "muscles": ["pectoralis_major_sternal", "pectoralis_major_clavicular", "pectoralis_minor"]
    },
    {
      "group": "back",
      "group_label": "Back",
      "muscle_count": 7,
      "muscles": ["latissimus_dorsi", "..."]
    }
    // ... 13 more groups
  ],
  "total_groups": 15,
  "total_muscles": 63
}

Tools

GET /exercises/{exercise_id}/muscles

Get the primary, secondary, and stabilizer muscles activated by an exercise. Supports exact IDs (e.g. barbell_bench_press), names (bench press), and fuzzy search.

Parameter	Type	In	Description
`exercise_id` required	string	path	Exercise name or ID

Request

curl https://musclesworked.com/api/v1/exercises/bench%20press/muscles \
  -H "X-Api-Key: mw_live_abc123"

Response

{
  "exercise": {
    "id": "barbell_bench_press",
    "name": "Barbell Bench Press",
    "movement_pattern": "horizontal_push",
    "equipment": "barbell",
    "difficulty": "intermediate",
    "exercise_type": "compound",
    "laterality": "bilateral",
    "force_type": "push"
  },
  "primary": [
    { "muscle_id": "pectoralis_major_sternal", "muscle_name": "Pectoralis Major (Sternal)", "group": "chest", "role": "primary" },
    { "muscle_id": "anterior_deltoid", "muscle_name": "Anterior Deltoid", "group": "shoulders", "role": "primary" }
  ],
  "secondary": [
    { "muscle_id": "triceps_lateral_head", "muscle_name": "Triceps (Lateral Head)", "group": "triceps", "role": "secondary" }
  ],
  "stabilizers": [
    { "muscle_id": "rotator_cuff", "muscle_name": "Rotator Cuff", "group": "shoulders", "role": "stabilizer" }
  ]
}

GET /muscles/{muscle_id}/exercises

Find exercises that target a specific muscle. Filter by equipment, difficulty, movement pattern, exercise type, and muscle role.

Parameter	Type	In	Description
`muscle_id` required	string	path	Muscle name or ID
`equipment` optional	string	query	Filter by equipment type
`difficulty` optional	string	query	Filter by difficulty level
`movement_pattern` optional	string	query	Filter by movement pattern
`exercise_type` optional	string	query	`compound` or `isolation`
`role` optional	string	query	`primary`, `secondary`, or `stabilizer`
`limit` optional	integer	query	Max results (1-200, default: 50)

Request

curl "https://musclesworked.com/api/v1/muscles/biceps/exercises?equipment=dumbbell&limit=3" \
  -H "X-Api-Key: mw_live_abc123"

Response

{
  "muscle": {
    "id": "biceps_brachii_short_head",
    "name": "Biceps Brachii (Short Head)",
    "group": "biceps"
  },
  "exercises": [
    {
      "exercise": {
        "id": "dumbbell_bicep_curl",
        "name": "Dumbbell Bicep Curl",
        "equipment": "dumbbell",
        "difficulty": "beginner",
        "exercise_type": "isolation"
      },
      "role": "primary"
    }
  ],
  "total": 1
}

POST /workouts/analyze

Analyze a list of exercises for muscle coverage, gaps, push/pull imbalances, and movement pattern diversity.

Parameter	Type	In	Description
`exercises` required	string[]	body	Array of exercise names or IDs

Request

curl -X POST https://musclesworked.com/api/v1/workouts/analyze \
  -H "X-Api-Key: mw_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"exercises": ["bench press", "squat", "deadlift", "pull up"]}'

Response

{
  "exercises_found": ["Barbell Bench Press", "Barbell Squat", "Barbell Deadlift", "Pull Up"],
  "exercises_not_found": [],
  "total_exercises": 4,
  "muscle_group_coverage": [
    {
      "group": "chest",
      "group_label": "Chest",
      "muscles_hit": ["Pectoralis Major (Sternal)", "Pectoralis Major (Clavicular)"],
      "total_muscles_in_group": 3,
      "primary_sets": 2,
      "secondary_sets": 0,
      "stabilizer_sets": 1,
      "coverage_pct": 66.7
    }
    // ... more muscle groups
  ],
  "primary_muscles": ["Pectoralis Major (Sternal)", "Quadriceps", "..."],
  "secondary_muscles": ["Triceps (Lateral Head)", "..."],
  "stabilizer_muscles": ["Rotator Cuff", "..."],
  "gaps": ["calves"],
  "imbalances": [],
  "movement_patterns_used": ["horizontal_push", "squat", "hinge", "vertical_pull"],
  "movement_patterns_missing": ["horizontal_pull", "vertical_push", "lunge", "carry"]
}

GET /exercises/{exercise_id}/alternatives

Find alternative exercises ranked by muscle overlap score. Useful for adapting workouts to equipment availability or adding variety.

Parameter	Type	In	Description
`exercise_id` required	string	path	Exercise name or ID
`limit` optional	integer	query	Max alternatives (1-50, default: 10)

Request

curl "https://musclesworked.com/api/v1/exercises/bench%20press/alternatives?limit=2" \
  -H "X-Api-Key: mw_live_abc123"

Response

{
  "original": {
    "id": "barbell_bench_press",
    "name": "Barbell Bench Press",
    "equipment": "barbell"
  },
  "alternatives": [
    {
      "exercise": {
        "id": "dumbbell_bench_press",
        "name": "Dumbbell Bench Press",
        "equipment": "dumbbell"
      },
      "shared_primary_muscles": ["Pectoralis Major (Sternal)", "Anterior Deltoid"],
      "shared_secondary_muscles": ["Triceps (Lateral Head)"],
      "overlap_score": 0.92
    },
    {
      "exercise": {
        "id": "machine_chest_press",
        "name": "Machine Chest Press",
        "equipment": "machine"
      },
      "shared_primary_muscles": ["Pectoralis Major (Sternal)"],
      "shared_secondary_muscles": ["Triceps (Lateral Head)"],
      "overlap_score": 0.78
    }
  ]
}

GET /search/exercises

Fuzzy search exercises by name. Returns matching exercises with basic metadata.

Parameter	Type	In	Description
`q` required	string	query	Search query (min 2 characters)

Request

curl "https://musclesworked.com/api/v1/search/exercises?q=curl" \
  -H "X-Api-Key: mw_live_abc123"

Response

{
  "query": "curl",
  "results": [
    { "id": "barbell_curl", "name": "Barbell Curl", "equipment": "barbell" },
    { "id": "dumbbell_bicep_curl", "name": "Dumbbell Bicep Curl", "equipment": "dumbbell" },
    { "id": "hammer_curl", "name": "Hammer Curl", "equipment": "dumbbell" }
  ],
  "total": 3
}

GET /search/muscles

Fuzzy search muscles by name. Returns matching muscles with group info.

Parameter	Type	In	Description
`q` required	string	query	Search query (min 2 characters)

Request

curl "https://musclesworked.com/api/v1/search/muscles?q=deltoid" \
  -H "X-Api-Key: mw_live_abc123"

Response

{
  "query": "deltoid",
  "results": [
    { "id": "anterior_deltoid", "name": "Anterior Deltoid", "group": "shoulders" },
    { "id": "lateral_deltoid", "name": "Lateral Deltoid", "group": "shoulders" },
    { "id": "posterior_deltoid", "name": "Posterior Deltoid", "group": "shoulders" }
  ],
  "total": 3
}

Account

GET /auth/me

Get the current authenticated user's profile. Works with both API key and JWT authentication.

Request

curl https://musclesworked.com/api/v1/auth/me \
  -H "X-Api-Key: mw_live_abc123"

Response

{
  "sub": "Google_1234567890",
  "email": "user@example.com",
  "name": "Jane Doe",
  "status": "approved",
  "role": "user",
  "provider": "google"
}

MCP Server Setup

MusclesWorked is available as an MCP (Model Context Protocol) server, giving AI agents direct access to the exercise-muscle database via 6 tools.

claude_desktop_config.json

{
  "mcpServers": {
    "musclesworked": {
      "command": "npx",
      "args": ["musclesworked-mcp"],
      "env": {
        "MUSCLESWORKED_API_KEY": "mw_live_abc123"
      }
    }
  }
}

.claude/settings.json

{
  "mcpServers": {
    "musclesworked": {
      "command": "npx",
      "args": ["musclesworked-mcp"],
      "env": {
        "MUSCLESWORKED_API_KEY": "mw_live_abc123"
      }
    }
  }
}

.cursor/mcp.json

{
  "mcpServers": {
    "musclesworked": {
      "command": "npx",
      "args": ["musclesworked-mcp"],
      "env": {
        "MUSCLESWORKED_API_KEY": "mw_live_abc123"
      }
    }
  }
}

Once connected, your AI agent can call tools like get_muscles_worked("bench press") directly in conversation. The MCP server handles authentication and database access automatically.

Available MCP Tools

The MCP server exposes 6 tools:

Tool	Description
`get_muscles_worked(exercise)`	Get primary, secondary, and stabilizer muscles for any exercise
`find_exercises(muscle, filters...)`	Find exercises targeting a muscle, with equipment/difficulty/pattern filters
`analyze_workout(exercises[])`	Analyze a workout for muscle coverage, gaps, and imbalances
`get_alternatives(exercise)`	Find substitute exercises ranked by muscle overlap score
`search_exercises(query)`	Fuzzy search the exercise catalog by name
`search_muscles(query)`	Fuzzy search the muscle taxonomy by name

Enum Reference

The API uses the following enum values for filtering and categorization.

Equipment

Value	Description
`barbell`	Standard or Olympic barbell
`dumbbell`	Dumbbells (single or pair)
`kettlebell`	Kettlebells
`cable`	Cable machine / pulley
`machine`	Gym machine (plate-loaded or selectorized)
`bodyweight`	No equipment required
`band`	Resistance bands
`smith_machine`	Smith machine (guided barbell)
`trap_bar`	Hex / trap bar
`ez_bar`	EZ curl bar
`suspension`	TRX / suspension trainer
`medicine_ball`	Medicine ball
`plate`	Weight plate
`landmine`	Landmine attachment
`none`	No equipment

Difficulty

Value	Description
`beginner`	Simple movement, low coordination
`intermediate`	Moderate complexity
`advanced`	High skill/strength requirement

Movement Pattern

Value	Description
`horizontal_push`	Bench press, push-up
`horizontal_pull`	Barbell row, seated row
`vertical_push`	Overhead press, handstand push-up
`vertical_pull`	Pull-up, lat pulldown
`squat`	Squat variations
`hinge`	Deadlift, hip thrust
`lunge`	Lunge, split squat, step-up
`carry`	Farmer's walk, suitcase carry
`rotation`	Russian twist, woodchop
`anti_rotation`	Pallof press, plank variations
`flexion`	Curl, crunch
`extension`	Tricep extension, back extension
`isolation`	Single-joint movement
`abduction`	Lateral raise, hip abduction
`adduction`	Cable adduction, hip adduction

Exercise Type

Value	Description
`compound`	Multi-joint movement
`isolation`	Single-joint movement
`isometric`	Static hold (plank, wall sit)

Muscle Role

Value	Description
`primary`	Main mover — directly drives the exercise
`secondary`	Assists the primary movers
`stabilizer`	Stabilizes joints during movement

Muscle Group

Value	Description
`chest`	Pectoral muscles
`back`	Latissimus dorsi, traps, rhomboids, erectors
`shoulders`	Deltoids, rotator cuff
`biceps`	Biceps brachii, brachialis
`triceps`	Triceps brachii
`forearms`	Wrist flexors/extensors, brachioradialis
`core`	Rectus abdominis, obliques, transverse abdominis
`quadriceps`	Rectus femoris, vastus group
`hamstrings`	Biceps femoris, semimembranosus, semitendinosus
`glutes`	Gluteus maximus, medius, minimus
`calves`	Gastrocnemius, soleus
`hip_flexors`	Iliopsoas, rectus femoris
`adductors`	Inner thigh muscles
`abductors`	Outer thigh / hip muscles
`neck`	Sternocleidomastoid, neck extensors

Error Codes

The API uses standard HTTP status codes. Error responses include a JSON body with a detail field.

Error Response Format

{
  "detail": "Exercise not found: 'benc pres'. Try a more specific name."
}

Status	Meaning	Common Causes
400	Bad Request	Invalid parameters, search query too short
401	Unauthorized	Missing or invalid API key / token
403	Forbidden	Account pending approval or suspended
404	Not Found	Exercise or muscle not found (fuzzy search failed)
422	Validation Error	Invalid enum value or request body
429	Rate Limited	Too many requests — back off and retry
500	Internal Error	Unexpected server error — contact support