API Documentation

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. Perfect for fitness apps, workout planners, and health & wellness platforms.

What You Can Build

Key Features

Include this header in every request:

Quick Start

1. 1

   Create an Account

   Sign up for a free MuscleWiki API account. The free BASIC tier gives you playground access. Upgrade to TESTING ($10/mo) or higher for direct API access.

   Create Account →
2. 2

   Generate Your API Key

   After signing in, navigate to your dashboard and create an API key. You'll only see the full key once, so make sure to save it securely.

   Go to Dashboard →
3. 3

   Make Your First Request

   Use your API key in the X-API-Key header to authenticate requests and start accessing exercise data.

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

Every data endpoint accepts an optional lang query parameter that translates exercise names, instruction steps, muscles, categories, and routine/workout text. Omit it to get English (fully backwards compatible). Media and bodymap URLs are identical in every language — only text changes.

Supported Languages

Where it applies

Example Request

curl -H "X-API-Key: your-key" \
  "https://api.musclewiki.com/exercises/1?lang=pt-br"

{
  "id": 1,
  "name": "Rosca Direta",
  "primary_muscles": ["Bíceps"],
  "category": "Barra de Pesos",
  "difficulty": "Intermediário",
  "steps": ["Flexione os pesos para frente..."],
  "videos": [ ... ]   // identical URLs in every language
}

Routines are structured training programs composed of workouts. Each workout contains exercise references with prescription details (sets, reps, duration). The data follows a nested pattern: Routine → Workout references → Exercise references.

# 1. Your backend mints a token (never the device)
curl -X POST https://api.musclewiki.com/media/token \
  -H "X-API-Key: mw_your_key_here"

# → { "token": "eyJr...", "expires_in": 900 }

# 2. Hand the player a plain URL — no headers needed
https://api.musclewiki.com/stream/videos/unbranded/squat.mp4?token=eyJr...

Media endpoints use explicit subdirectory routes for better security and type safety. All video and image files are organized by category.

GET /stream/videos/branded/male-Barbell-barbell-curl-front.mp4

GET /stream/videos/unbranded/male-Barbell-barbell-curl-front.mp4

GET /stream/images/og_images/og-male-Barbell-barbell-curl-front.jpg

Bodymap images are anatomical muscle diagrams that highlight which muscles an exercise targets, grouped by training emphasis. They are available in male and female variants, with light and dark theme options.

{
  "id": 1,
  "name": "Barbell Curl",
  ...
  "bodymap_male": "https://api.musclewiki.com/stream/images/bodymaps/1?gender=male",
  "bodymap_female": "https://api.musclewiki.com/stream/images/bodymaps/1?gender=female"
}

curl --fail --show-error --request GET \
  --url 'https://api.musclewiki.com/stream/images/bodymaps/1?gender=male&theme=dark&view=front' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --output bodymap.png

curl --include --request GET \
  --url 'https://api.musclewiki.com/stream/images/bodymaps/1?gender=male&theme=dark&view=front' \
  --header 'X-API-Key: YOUR_API_KEY'

The API uses standard HTTP status codes and returns error details in JSON format. All errors include a detail field with a human-readable message.

{
  "detail": "Authentication required",
  "message": "Missing X-API-Key header"
}

{
  "detail": "Invalid or expired API key"
}

{
  "detail": "Exercise not found"
}

{
  "detail": "Monthly API quota exceeded",
  "message": "Monthly API quota exceeded. Please upgrade your plan or wait for the next billing cycle."
}

{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "ensure this value is less than or equal to 100",
      "type": "value_error.number.not_le"
    }
  ]
}

{
  "detail": "Internal server error"
}

The @musclewiki/mcp package is a first-party Model Context Protocol server. It runs locally over stdio and exposes the entire exercise database to any MCP-compatible AI assistant — Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Zed, and more — as native tools. Every call is forwarded to this API with your ownkey, so your tier, rate limits, and quota apply exactly as they would for a direct request. There is no shared key: the server reads your key from its local environment and sends it only to the MuscleWiki API to authenticate your own requests — never to the AI model or your assistant provider’s servers. Keep it in your local MCP client config; treat that config like any other secret and don’t commit it to source control.

Claude Code

claude mcp add musclewiki --env MUSCLEWIKI_API_KEY=mw_your_api_key_here -- npx -y @musclewiki/mcp

Any other MCP client

MCP is an open standard, so the sameserver works with every MCP-compatible host — there is no per-client build. Add one entry to your client’s config pointing at npx -y @musclewiki/mcp. Most clients (Claude Desktop, Cursor, Windsurf, Cline, …) use the mcpServers shape below verbatim:

{
  "mcpServers": {
    "musclewiki": {
      "command": "npx",
      "args": ["-y", "@musclewiki/mcp"],
      "env": {
        "MUSCLEWIKI_API_KEY": "mw_your_api_key_here"
      }
    }
  }
}

The location of the config (and, for VS Code and Zed, the wrapper key) differs per client — the command, args, and env inside are always the same:

Configuration

The server is configured entirely through environment variables in your MCP client config — no config file of its own.

Available tools

14 tools are exposed. You never name them yourself — describe what you want and the assistant picks and chains the right ones. Each maps to a single REST endpoint, so tier and quota apply per call.

• search_exercisesGET /searchFull-text search by name or steps, with optional filters
• list_exercisesGET /exercisesBrowse and filter — no query term needed
• get_exerciseGET /exercises/{id}One exercise by numeric ID
• list_categoriesGET /categoriesEquipment categories with counts
• list_musclesGET /musclesPrimary muscle groups with counts
• list_filtersGET /filtersEvery valid filter value — call first to avoid guessing
• get_random_exerciseGET /randomA random exercise, optionally filtered
• get_statisticsGET /statisticsAggregate database statistics
• list_routinesGET /routinesProfessional / EnterprisePaginated routines
• get_routineGET /routines/{id}Professional / EnterpriseA routine with its workout references
• get_routine_fullGET /routines/{id}/fullProfessional / EnterpriseA routine, all workouts + exercises expanded
• list_workoutsGET /workoutsProfessional / EnterprisePaginated workouts with filters
• get_workoutGET /workouts/{id}Professional / EnterpriseA workout with exercise prescriptions
• get_workout_fullGET /workouts/{id}/fullProfessional / EnterpriseA workout, all exercises expanded

Talk to it in plain language

Once connected, ask for what you want. The assistant handles tool selection and chaining. For example:

• “Find me five dumbbell exercises for biceps.”
• “What equipment categories exist, and how many exercises does each have?”
• “Show me a random bodyweight exercise with its instructions.”
• “Get exercise 42 and summarise its steps.”
• “Build me a beginner push/pull routine.”

Troubleshooting

Full reference, source, and changelog live in the @musclewiki/mcp package README.

Python Examples

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']})")

JavaScript Examples

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);
}

cURL Examples

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

Stream Branded Video

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

Stream OG Image

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

Response Models

The API uses three different response detail levels to optimize bandwidth:

Common Use Cases