API Documentation

Complete guide to integrating the MuscleWiki API - 1,800+ exercises with video demonstrations

Try it live — API Playground

Make real API calls, see rendered exercise cards and videos

Choose Your Authentication Method

Select how you want to access the MuscleWiki API

Overview

The MuscleWiki API provides comprehensive access to a database of 1,800+ 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

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

Key Features

1,800+ 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

Direct API Authentication

All requests require a valid API key. You can create and manage your API keys from your dashboard after signing up.

Include this header in every request:

X-API-Key

Your unique API key (format: mw_xxxxxxxxxxxxx)

Sign In to DashboardCreate Account

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 ($5/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.

Ready to Start Building?

Once you have your API key, try this simple example to fetch your first exercise:

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

Replace YOUR_API_KEY with your actual API key from the dashboard. You should see the "Barbell Curl" exercise with complete details and video URLs.

Health & Metadata

GET/

Get basic API information and available endpoints.

{
  "name": "MuscleWiki API",
  "version": "2.0.0",
  "docs": "/docs",
  "openapi": "/openapi.json",
  "health": "/health",
  "endpoints": {
    "exercises": "/exercises",
    "search": "/search",
    "random": "/random",
    "categories": "/categories",
    "muscles": "/muscles",
    "filters": "/filters",
    "statistics": "/statistics",
    "workouts": {
      "push": "/workouts/push",
      "pull": "/workouts/pull"
    }
  }
}
GET/health

Check API health status and database statistics.

Use Case: Verify API availability before making requests.

{
  "status": "healthy",
  "version": "2.0.0",
  "exercises_loaded": 1832
}
GET/statistics

Get comprehensive database statistics including exercise counts, category breakdown, difficulty distribution, and more.

Use Case: Display database statistics, build dynamic filter UIs, show available content.

GET/categories

List all equipment categories with exercise counts.

Use Case: Build category filters, show available equipment types.

[
  {"name": "barbell", "display_name": "Barbell", "count": 150},
  {"name": "dumbbell", "display_name": "Dumbbell", "count": 200},
  {"name": "bodyweight", "display_name": "Bodyweight", "count": 180}
]
GET/muscles

List all primary muscle groups with exercise counts.

Use Case: Build muscle group filters, display muscle targeting options.

GET/filters

Get all available filter values for building dynamic UIs.

Use Case: Build comprehensive filter interfaces with all available options.

Exercise Endpoints

GET/exercises

List exercises with pagination and optional filtering. Returns minimal information optimized for list views.

Query Parameters

limit - Maximum results to return (1-100, default: 20)
offset - Number of results to skip (default: 0)
search - Search in exercise names and steps (min 2 characters)
gender - Filter videos by gender (male or female)
category - Filter by equipment category (e.g., barbell, dumbbell)
muscles - Filter by muscle groups (e.g., Biceps, Chest)
difficulty - Filter by difficulty (novice, intermediate, advanced)
force - Filter by force type (push, pull, static)
mechanic - Filter by mechanic (isolation, compound)
grips - Filter by grip types (e.g., Overhand, Underhand)

Example Request

GET /exercises?limit=5&category=barbell&difficulty=intermediate

Example Response (Success)

{
  "total": 45,        // Total exercises matching filters
  "limit": 5,         // Requested limit
  "offset": 0,        // Current offset
  "count": 5,         // Number of results in this response
  "results": [        // Array of exercise objects (minimal format)
    {"id": 0, "name": "Barbell Curl"},
    {"id": 15, "name": "Barbell Bench Press"},
    {"id": 23, "name": "Barbell Squat"}
  ]
}

Pagination Format: All list endpoints return paginated results with total, limit, offset, and count fields for easy pagination handling.

GET/exercises/{exercise_id}

Get detailed information for a specific exercise by ID.

Path Parameters

exercise_id - Exercise ID (0-based index)

Query Parameters

detail - Return detailed info (boolean)
gender - Filter videos by gender

Response Detail Levels:

  • Standard (default): Full exercise data with videos, steps, and all attributes
  • Detailed (?detail=true): Standard data + metadata counts (video_count, step_count, etc.)

Use Case: Show exercise detail pages, display exercise instructions and videos, build exercise demonstration features.

GET/exercises/{exercise_id}/videos

Get only video URLs for a specific exercise. Optimized endpoint that reduces bandwidth by excluding other exercise data.

Use Case: Video-only display features, minimize bandwidth when only videos are needed, build video galleries.

Search & Discovery

GET/search

Search exercises by text query with intelligent relevance scoring. Searches in exercise names and instruction steps.

Search Features

Word-order independent matching
Relevance scoring (exact matches ranked higher)
Searches both exercise names and instruction steps
Results sorted by relevance

Example Request

GET /search?q=curl&limit=5&difficulty=intermediate
GET/random

Get a random exercise, optionally filtered by category. Perfect for "try something new" features.

Use Case: "Random exercise" features, workout variation generators, "try something new" buttons, surprise workout features.

Workout Builders

GET/workouts/push

Get exercises with push force type. Perfect for building push workout routines.

Use Case: Build "push day" workouts, create push/pull/legs split programs, filter exercises by movement pattern.

GET/workouts/pull

Get exercises with pull force type. Perfect for building pull workout routines.

Use Case: Build "pull day" workouts, create balanced workout programs, filter exercises by movement pattern.

Media Streaming

Authentication Required

All media streaming endpoints require authentication. You must include your API key in the X-API-Key header even when streaming videos or images.

Authenticated Streaming

These endpoints require authentication headers just like data endpoints. Each media request counts as an API call for metering purposes.

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/{filename}

Stream branded exercise video files. Supports byte-range requests for smooth playback and video seeking.

Path Parameters

filename - Video filename (e.g., male-Barbell-barbell-curl-front.mp4)

Example Request

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

Note: Supports HTTP range requests for efficient streaming and seeking. Users should only perform transient caching (e.g., in-memory playback buffers) as per the API Terms.

GET/stream/videos/unbranded/{filename}

Stream unbranded exercise video files. Supports byte-range requests for smooth playback.

Path Parameters

filename - Video filename (e.g., male-Barbell-barbell-curl-front.mp4)

Example Request

GET /stream/videos/unbranded/male-Barbell-barbell-curl-front.mp4
GET/stream/images/og_images/{filename}

Stream Open Graph image files for social sharing preview images. Supports automatic content-type detection for JPEG, PNG, GIF, and WebP formats.

Path Parameters

filename - Image filename (e.g., og-male-Barbell-barbell-curl-front.jpg)

Example Request

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

Error Responses

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.

401

Unauthorized

Missing or invalid API key. Ensure you include the X-API-Key header with every request.

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

Forbidden

Invalid, expired, or deactivated API key.

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

Not Found

Requested resource doesn't exist (e.g., invalid exercise ID or media file).

{
  "detail": "Exercise not found"
}
429

Rate Limit Exceeded

Monthly API quota exceeded. Upgrade your plan or wait for the next billing cycle.

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

Validation Error

Invalid query parameters or request format.

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

Internal Server Error

Unexpected server error. If this persists, contact support.

{
  "detail": "Internal server error"
}

Error Handling Best Practices

  • Always check HTTP status codes before parsing response bodies
  • Implement exponential backoff for 429 errors
  • Log error details for debugging but don't expose them to end users
  • For 500 errors, retry with exponential backoff (max 3 attempts)

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

Note: Replace YOUR_API_KEY with your actual API key from your dashboard. Need an API key? Create a free account.

curl --request GET \
  --url 'https://api.musclewiki.com/exercises/0' \
  --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:

Minimal Response

Used by /exercises list endpoint

Contains:

  • • id - Exercise identifier
  • • name - Exercise name
Perfect for: Lists, autocomplete, quick browsing

Standard Response

Used by most endpoints (default)

Contains:

  • • id - Exercise identifier
  • • name - Exercise name
  • • primary_muscles - Targeted muscle groups
  • • category - Equipment type
  • • force - Push/Pull/Hold (may be null)
  • • grips - Grip types used
  • • mechanic - Isolation/Compound (may be null)
  • • difficulty - Novice/Beginner/Intermediate/Advanced (may be null)
  • • steps - Step-by-step instructions
  • • videos - Video demonstrations with URLs
Perfect for: Most use cases, detail views, search results

Detailed Response

Used by /exercises/{id}?detail=true

Contains:

  • • All standard fields, plus:
  • • video_count - Total number of videos
  • • step_count - Total number of instruction steps
Perfect for: Admin interfaces, analytics, when you need complete data

Common Use Cases

Building an Exercise Browser

  1. 1GET /categories - Get available equipment types
  2. 2GET /exercises?category=barbell&limit=20 - List exercises
  3. 3GET /exercises/0 - Show detail for selected exercise

Exercise Search Feature

  1. 1GET /search?q=curl&limit=10 - Search for exercises
  2. 2GET /exercises/{id} - Get full details for selected result

Random Workout Generator

  1. 1GET /random?category=bodyweight - Get random exercise
  2. 2Repeat with different categories for variety

Push/Pull Workout Builder

  1. 1GET /workouts/push?difficulty=intermediate&limit=5
  2. 2GET /workouts/pull?difficulty=intermediate&limit=5
  3. 3Combine results for a balanced workout

Muscle-Specific Training

  1. 1GET /muscles - Get available muscle groups
  2. 2GET /exercises?muscles=Biceps&difficulty=intermediate
  3. 3Build muscle-specific workout plans

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 parameters for large result sets.

5

Search vs Filter

Use /search for text-based queries, /exercises with filters for structured queries.

Need Help?

Check out our live demo to see the API in action, or visit RapidAPI for support and subscription options.

View Live DemoGet API Key