# MuscleWiki API

> Comprehensive exercise database (1,900+ exercises) with multi-angle video
> demonstrations (front/side views, male/female models), plus structured
> training routines and workouts, available in 14 languages. A REST API built
> for fitness apps and AI/LLM applications.

Base URL: https://api.musclewiki.com
Interactive docs: https://api.musclewiki.com/docs
OpenAPI spec (machine-readable): https://api.musclewiki.com/openapi.json
Get an API key: https://api.musclewiki.com/register?ref=llms-txt

## Authentication

Send your API key in the `X-API-Key` HTTP header on every request. Keys begin
with the `mw_` prefix and are created in your dashboard. `/health`, `/docs`,
`/openapi.json`, and `/llms.txt` are public; every data endpoint requires a
valid key. A missing key returns `401`; an invalid or expired key returns `403`.

Example request:

    curl -H "X-API-Key: mw_your_key" "https://api.musclewiki.com/search?q=barbell%20curl&limit=5"

## First-party MCP server (recommended for AI clients)

For any MCP-compatible host (Claude Code, Claude Desktop, Cursor, VS Code,
Windsurf, Zed, Cline, and others — MCP is an open standard, so the same server
works everywhere), install the first-party server instead of calling REST
directly — it gives a better multi-turn experience:

    npx @musclewiki/mcp

It runs locally over stdio and forwards every call to this API using YOUR key,
read from the `MUSCLEWIKI_API_KEY` environment variable. There is no shared key
and no hosted infrastructure: your tier, rate limits, and quota apply exactly as
they would for a direct request. 14 tools are exposed (search_exercises,
list_exercises, get_exercise, list_categories, list_muscles, list_filters,
get_random_exercise, get_statistics, plus the PROFESSIONAL/ENTERPRISE routine
& workout tools). Requires a TESTING-tier key or higher.

## Endpoints

Exercises
- GET /search?q={query}&limit={n} - Full-text search over names and steps (q: 2-200 chars; limit: 1-50).
- GET /exercises - List/browse exercises. Paginated (limit 1-100, offset >= 0) and filterable (see Filters).
- GET /exercises/{id} - One exercise by id (ids are non-consecutive integers >= 1).
- GET /exercises/{id}/videos - Just the video angles for an exercise.
- GET /random - A random exercise (optional filters, e.g. category, gender).

Discovery / reference
- GET /categories - Equipment categories with exercise counts.
- GET /muscles - Primary muscle groups with exercise counts.
- GET /filters - All valid filter values in one call (muscles, difficulties, forces, mechanics, grips, categories). Call this instead of guessing filter arguments.
- GET /statistics - Aggregate database statistics.
- GET /languages - Supported response languages (14 codes) for the `lang` parameter.

Routines & workouts (PROFESSIONAL and ENTERPRISE tiers only)
- GET /routines - List training routines (paginated).
- GET /routines/{id} - A routine with its workout references.
- GET /routines/{id}/full - A routine with all workouts and exercises expanded in one call (costs multiple internal reads).
- GET /workouts - List workouts (paginated; filter by difficulty, goal, equipment, muscles).
- GET /workouts/{id} - A workout with exercise references and prescription data (sets, reps, duration).
- GET /workouts/{id}/full - A workout with all exercises expanded in one call.

## Filters

The full filter set below applies to GET /exercises. GET /search accepts every
filter except `grips`. GET /random accepts only `category` and `gender`. Filters
sent to an endpoint that does not support them are ignored, not rejected.

- muscles - primary muscle group (e.g. biceps, chest, quadriceps).
- category - equipment category (e.g. dumbbell, barbell, bodyweight).
- difficulty - e.g. novice, beginner, intermediate, advanced.
- force - e.g. push, pull, hold.
- mechanic - compound or isolation.
- grips - grip variation, where applicable.
- gender - male or female (selects the matching video/bodymap variant).
- lang - response language (14 codes, e.g. pt-br, es-es, ja-jp; default en-us). Accepted by every data endpoint above; translates names, steps, muscles, categories, and routine/workout text while media URLs stay identical. Unsupported codes return 400. Non-English languages require GROWTH tier or higher (TESTING keys are English-only and get 403 with an upgrade_url; BASIC keys get all languages in the Playground). List codes via GET /languages.

Retrieve the exact valid values from GET /filters. Category matching tolerates
differences in case, spaces, and hyphens.

## Data model

Each exercise carries an id, name, difficulty, equipment category, target
muscles, step-by-step instructions, and a set of videos. Videos come in two
angles (front/side) and two model variants (male/female). All text fields
(names, instructions, muscles, categories, routine/workout descriptions) are
translated into 14 languages, selected per request via the `lang` parameter;
media URLs never change across languages. Responses are
available at three levels of detail to control bandwidth:
- minimal  - id and name only (for lists).
- standard - full exercise data (default).
- detailed - standard plus metadata counts.

Bodymap images (highlighted muscle diagrams) are exposed as stream URLs on
exercise, routine, and workout responses for PROFESSIONAL and ENTERPRISE tiers.

## Tiers and monthly quotas

| Tier         | Price/mo | Calls/mo | Direct API key       | Routines/Workouts + Bodymaps | Multilingual (`lang`) |
|--------------|----------|----------|----------------------|------------------------------|-----------------------|
| BASIC        | Free     | 500      | No (Playground only) | Playground only              | Playground only       |
| TESTING      | $10      | 1,000    | Yes                  | No                           | No (English only)     |
| GROWTH       | $39.99   | 30,000   | Yes                  | No                           | Yes (14 languages)    |
| PROFESSIONAL | $99.99   | 100,000  | Yes                  | Yes                          | Yes (14 languages)    |
| ENTERPRISE   | $199.99  | 300,000  | Yes                  | Yes                          | Yes (14 languages)    |

Custom plans with negotiated quotas are also available. Quotas are always
monthly: a monthly subscription's quota resets on its billing anniversary, while
an annual subscription is billed yearly but still resets its monthly quota on
the 1st of each calendar month, as does the free plan. BASIC keys cannot call
the API directly — they work only through the interactive Playground on the
website. Full plan comparison: https://api.musclewiki.com/pricing

## Errors and rate limits

Errors are returned as JSON with a `detail` field:
- 401 - missing API key (no `X-API-Key` header).
- 402 - custom-plan key provisioned but payment not yet completed.
- 403 - invalid or expired API key, or a tier restriction (e.g. routines/workouts below PROFESSIONAL, non-English `lang` below GROWTH); tier restrictions include an `upgrade_url`.
- 404 - unknown exercise, routine, or workout id.
- 422 - request validation error.
- 429 - monthly quota exceeded; where the reset time is known the response carries a `reset_at` field (ISO-8601) and a `Retry-After` header giving the exact instant your quota refreshes (see the quota rules above), or upgrade for a higher quota.

## Optional

Secondary resources — skip these if you only need the API surface above.

- Complete reference in one fetch, LLM-optimised plain text: https://api.musclewiki.com/llms-full.txt
- Full documentation, guides, and code samples: https://api.musclewiki.com/documentation?ref=llms-txt
- The same documentation as plain markdown: https://api.musclewiki.com/documentation.md
- Pricing and plan comparison: https://api.musclewiki.com/pricing?ref=llms-txt
- The same pricing as plain markdown: https://api.musclewiki.com/pricing.md
- Interactive API Playground (browse and try endpoints in-browser): https://api.musclewiki.com/playground?ref=llms-txt
- Interactive API explorer (Swagger UI): https://api.musclewiki.com/docs
- First-party MCP server (npm): https://www.npmjs.com/package/@musclewiki/mcp
- Official TypeScript/JavaScript SDK (npm): https://www.npmjs.com/package/@musclewiki/client
- Official Python SDK (PyPI): https://pypi.org/project/musclewiki/