# MuscleWiki API Documentation

Plain-markdown mirror of https://api.musclewiki.com/documentation, which is the canonical page.
Complete machine-readable reference: https://api.musclewiki.com/llms-full.txt and
https://api.musclewiki.com/openapi.json.

## Overview

The MuscleWiki API provides comprehensive access to a database of 1,900+ exercise
demonstrations with video tutorials, step-by-step instructions, and detailed
metadata. Built for fitness apps, workout planners, and health and wellness
platforms.

**Commercial use included.** All paid plans grant full commercial use rights. You
can build and ship products, SaaS applications, and client-facing platforms
without additional licensing fees or restrictions. Full terms:
https://api.musclewiki.com/api-terms?ref=md.

### What you can build

- Workout planning applications
- Exercise recommendation systems
- Fitness tracking apps
- Personal training platforms
- Exercise search and discovery tools
- Random workout generators

### Key features

- **1,900+ exercises** — comprehensive database covering all major muscle groups.
- **Video demonstrations** — multiple camera angles (front/side) and gender
  variants (male/female).
- **Smart search** — full-text search with relevance scoring.
- **Advanced filtering** — filter by muscle group, equipment, difficulty, force
  type, and more.
- **Optimized responses** — multiple detail levels to minimize bandwidth usage.
- **High performance** — built on FastAPI for exceptional speed.

## Authentication

Every request needs your API key in the `X-API-Key` header. Keys start with the
`mw_` prefix and are created in your dashboard.

    curl --request GET \
      --url 'https://api.musclewiki.com/exercises/1' \
      --header 'X-API-Key: YOUR_API_KEY'

A missing key returns `401`; an invalid or expired key returns `403`.

## Quick start

1. **Create an account.** The free BASIC tier gives you Playground access.
   Upgrade to TESTING or higher for direct API access. https://api.musclewiki.com/register?ref=md
2. **Generate your API key.** In the dashboard, create a key. You only see the
   full key once, so save it securely. https://api.musclewiki.com/dashboard/api-keys
3. **Make your first request.** Use the key in the `X-API-Key` header. The
   example above returns the "Barbell Curl" exercise with full details and video
   URLs.

Current prices and monthly quotas for every tier: https://api.musclewiki.com/llms-full.txt
(generated from the same constants the pricing page renders).

## Health and metadata

- `GET /health` — service health.
- `GET /statistics` — aggregate database statistics.
- `GET /categories` — equipment categories with exercise counts.
- `GET /muscles` — primary muscle groups with exercise counts.
- `GET /filters` — every valid filter value in one call. Call this instead of
  guessing filter arguments.
- `GET /languages` — supported `lang` codes. Open to every tier.

## Exercises

- `GET /exercises` — paginated, filterable list returning minimal records (id and
  name) for list views. Parameters: `limit` (1-100, default 20), `offset`
  (default 0), `search` (2-200 characters), `gender`, `category`, `muscles`,
  `difficulty`, `force`, `mechanic`, `grips`, `lang`.
- `GET /exercises/{id}` — one exercise. Ids are non-consecutive integers starting
  at 1. Add `detail=true` for metadata counts. Unknown ids return `404`.
- `GET /exercises/{id}/videos` — the video angles only.
- `GET /random` — a random exercise, optionally filtered by `category` and
  `gender`.

### Filters

- `muscles` — primary muscle group (e.g. Biceps, Chest). Repeatable.
- `category` — equipment category (e.g. Barbell, Dumbbells, Bodyweight). Matching
  tolerates case, space, and hyphen differences.
- `difficulty` — Novice, Beginner, Intermediate, Advanced.
- `force` — Push, Pull, Hold.
- `mechanic` — Compound, Isolation.
- `grips` — grip variation (e.g. Overhand, Underhand, Neutral). `/exercises` only.
- `gender` — male or female; selects the matching video and bodymap variant.

## Search and discovery

`GET /search` performs full-text search across exercise names and instruction
steps with relevance sorting. Parameters: `q` (required, 2-200 characters),
`limit` (1-50, default 10), plus every exercise filter except `grips`.

    const url = 'https://api.musclewiki.com/search?q=curl&limit=5';
    const options = {
      method: 'GET',
      headers: {
        'X-API-Key': 'YOUR_API_KEY'
      }
    };

    try {
      const response = await fetch(url, options);
      const result = await response.json();
      console.log(result);
    } catch (error) {
      console.error(error);
    }

## Multilingual (14 languages)

Every data endpoint accepts `lang`. It translates exercise names, instruction
steps, muscle names, categories, and routine and workout text; media URLs are
identical across languages. `en-us` is the default when `lang` is omitted, and an
unsupported code returns `400`.

Non-English languages require GROWTH tier or higher. TESTING keys are
English-only and receive `403` with an `upgrade_url`; BASIC keys get every
language in the Playground. The full code list is at https://api.musclewiki.com/llms-full.txt or
programmatically from `GET /languages`.

Note that `difficulty`, `force`, and `mechanic` are validated against the
canonical English values under every language; only `category` and `muscles`
accept translated input.

## Routines and workouts

Available to PROFESSIONAL and ENTERPRISE tiers. Routines are structured training
programs composed of workouts, and workouts carry exercise references with
prescription data (sets, reps, duration).

- `GET /routines` — paginated list.
- `GET /routines/{id}` — one routine with its workout references.
- `GET /routines/{id}/full` — routine with every workout and exercise expanded.
- `GET /workouts` — paginated list; filter by `difficulty`, `goal`, `equipment`,
  `muscles`.
- `GET /workouts/{id}` — one workout with exercise references.
- `GET /workouts/{id}/full` — workout with every exercise expanded.

The `/full` endpoints cost multiple API calls; the exact cost is returned in the
`X-API-Calls-Cost` response header. TESTING and GROWTH keys receive `403` with an
`upgrade_url` on these paths.

## Media streaming

Videos and images are served from the API and require your key. Use the URLs
returned in exercise, routine, and workout responses rather than constructing
them by hand.

    curl --request GET \
      --url 'https://api.musclewiki.com/stream/videos/branded/male-Barbell-barbell-curl-front.mp4' \
      --header 'X-API-Key: YOUR_API_KEY' \
      --output video.mp4

    curl --request GET \
      --url 'https://api.musclewiki.com/stream/images/og_images/og-male-Barbell-barbell-curl-front.jpg' \
      --header 'X-API-Key: YOUR_API_KEY' \
      --output og-image.jpg

Branded and unbranded variants are both available:
`/stream/videos/branded/{filename}` and `/stream/videos/unbranded/{filename}`.

## Bodymap images

Highlighted muscle diagrams are exposed as `bodymap_male` and `bodymap_female`
stream URLs on exercise, routine, and workout responses. Append
`theme=light|dark` and `view=front|back` to select a variant:

    https://api.musclewiki.com/stream/images/bodymaps/1?gender=male&theme=light&view=front

Resource-scoped endpoints exist for each type:
`/stream/images/bodymaps/{exercise_id}`,
`/stream/images/bodymaps/routines/{routine_id}`, and
`/stream/images/bodymaps/workouts/{workout_id}`.

Bodymap fields are non-null for PROFESSIONAL and ENTERPRISE keys. TESTING and
GROWTH receive `null`.

## Error responses

Errors are JSON with a `detail` field. Tier restrictions also carry `message` and
`upgrade_url`.

| Status | Meaning |
|---|---|
| 400 | Unsupported `lang` code. |
| 401 | No `X-API-Key` header. |
| 402 | Custom-plan key provisioned but payment not completed. |
| 403 | Invalid or expired key, or a tier restriction. |
| 404 | Unknown exercise, routine, or workout id. |
| 422 | Request validation error — a parameter outside its documented bounds. |
| 429 | Monthly quota exceeded; resets at the start of your next billing cycle. |

## MCP server

For MCP-compatible hosts (Claude Code, Claude Desktop, Cursor, VS Code, Windsurf,
Zed, Cline, and others), the first-party server gives a better multi-turn
experience than calling REST directly:

    npx @musclewiki/mcp

It runs locally over stdio and forwards every call using YOUR key, read from the
`MUSCLEWIKI_API_KEY` environment variable. There is no shared key and no hosted
infrastructure, so your tier and quota apply exactly as they would for a direct
request. 14 tools are exposed. Requires a TESTING-tier key or higher.

## Code examples

### Python

    import requests

    url = "https://api.musclewiki.com/exercises"
    headers = {
        "X-API-Key": "YOUR_API_KEY"
    }

    params = {
        "limit": 10,
        "category": "barbell"
    }

    response = requests.get(url, headers=headers, params=params)
    exercises = response.json()

    print(f"Total exercises: {exercises['total']}")
    for exercise in exercises['results']:
        print(f"- {exercise['name']} (ID: {exercise['id']})")

### cURL

    curl --request GET \
      --url 'https://api.musclewiki.com/exercises/1' \
      --header 'X-API-Key: YOUR_API_KEY'

Replace `YOUR_API_KEY` with your key from https://api.musclewiki.com/dashboard/api-keys.

## Response models

Three levels of detail control bandwidth:

- **Minimal** — id and name only. Returned by list endpoints.
- **Standard** — full exercise data. The default for single-resource endpoints.
- **Detailed** — standard plus metadata counts. Request with `detail=true`.

## Common use cases

**Building an exercise browser**
1. `GET /categories` — get available equipment types.
2. `GET /exercises?category=barbell&limit=20` — list exercises.
3. `GET /exercises/1` — show detail for the selected exercise.

**Exercise search feature**
1. `GET /search?q=curl&limit=10` — search for exercises.
2. `GET /exercises/{id}` — get full details for the selected result.

**Random workout generator**
1. `GET /random?category=bodyweight` — get a random exercise.
2. Repeat with different categories for variety.

**Push/pull workout builder**
1. `GET /exercises?force=push&difficulty=intermediate&limit=5`
2. `GET /exercises?force=pull&difficulty=intermediate&limit=5`
3. Combine the results for a balanced workout.

**Muscle-specific training**
1. `GET /muscles` — get available muscle groups.
2. `GET /exercises?muscles=Biceps&difficulty=intermediate`
3. Build muscle-specific workout plans.

**Commercial SaaS fitness app**
1. Sign up for a GROWTH, PROFESSIONAL, or ENTERPRISE plan — commercial use
   included.
2. Integrate exercise data, videos, and search into your product.
3. Ship to paying customers with no additional licensing fees.

## Best practices

1. **Use appropriate detail levels.** Use `/exercises` for lists, standard
   responses for most cases, and detailed responses only when needed.
2. **Filter early.** Apply filters at the API level rather than fetching all data
   and filtering client-side.
3. **Cache metadata.** Cache responses from `/categories`, `/muscles`, and
   `/filters` for up to 30 days as they change infrequently.
4. **Paginate large results.** Use `limit` and `offset` for large result sets.
5. **Search vs filter.** Use `/search` for text-based queries and `/exercises`
   with filters for structured queries.

## Links

- Canonical HTML page: https://api.musclewiki.com/documentation
- Complete machine-readable reference: https://api.musclewiki.com/llms-full.txt
- Curated index for LLM clients: https://api.musclewiki.com/llms.txt
- OpenAPI spec: https://api.musclewiki.com/openapi.json
- Interactive API explorer: https://api.musclewiki.com/docs
- Terms of use: https://api.musclewiki.com/api-terms?ref=md
- Get an API key: https://api.musclewiki.com/register?ref=md
- Contact: https://api.musclewiki.com/contact?ref=md