MuscleWiki API — frequently asked questions

28 answers about plans, quotas, the data itself, and what the licence lets you build — each one checked against the API and the API Terms.

Contents

Getting started

Accounts, API keys, and the fastest route to your first response.

How do I get an API key?
Create an account on api.musclewiki.com, then generate a key from the API Keys page in your dashboard. Keys start with the prefix mw_ and are sent on every request in the X-API-Key header. Creating a key is not restricted by plan — the free BASIC plan can create one too, but it works only through the Playground on this site and is refused when sent from your own application, so calling the API from your own code starts at the TESTING plan.
What authentication method do you use?
We use API key authentication with the X-API-Key header. There is no OAuth flow — one header on one HTTPS request is the whole handshake for every data endpoint. The one exception is media: a native client can call POST /media/token to exchange a permanent key for a short-lived, media-only token, so the permanent key never ships inside an app binary. You can generate and manage keys from your dashboard, and each key can be revoked individually, so a leaked key can be cut off without disturbing your other integrations.
How does the free tier work?
The free BASIC plan gives you 500 API calls a month through the interactive Playground on this site, so you can try the exercise, search, filtering, routine and workout endpoints against real responses before writing any code. No credit card is required and no card is stored. You can create an API key on this plan, but it is accepted only from the Playground and refused from your own application, so calling the API from your own code means moving to the TESTING plan ($10 per month) or higher.
What is the difference between the BASIC and TESTING plans?
BASIC is free and reaches the API only through the Playground on this site: 500 calls a month, and a key that the Playground accepts but your own application cannot use. TESTING costs $10 per month, includes 1,000 calls, and unlocks direct API access with your own key so your application can call the API itself. TESTING covers exercises, search, filtering and videos in English; routines, workouts, bodymap images and non-English languages need a higher plan.
Do I need an SDK, or can I call the API directly?
No SDK is required. The API is plain REST over HTTPS returning JSON, and authentication is a single X-API-Key header, so any HTTP client in any language works — curl, fetch, requests, Retrofit, whatever you already use. A machine-readable OpenAPI document is published at /openapi.json if you would rather generate a typed client for your own stack. The one first-party package we publish today is the MuscleWiki MCP server, for AI agents.
Is there an MCP server for AI agents?
Yes — run npx @musclewiki/mcp and any MCP client (Claude, Cursor, VS Code, Windsurf, Zed) gets the exercise database as 14 native tools it can call directly. It is a first-party server published by us, it speaks stdio, and it forwards every call to the API using your own API key, so your plan's limits and quota apply exactly as they do to your own code.

Back to contents

Pricing & billing

What plans cost, what counts as a call, and what happens at the ceiling.

How much does the API cost?
MuscleWiki API pricing starts free — 500 Playground calls a month — and runs from $10 to $199.99 per month, for 1,000 to 300,000 API calls per month. Most requests cost one API call — the expanded /full endpoints cost more and report their exact cost in a response header — and every paid plan includes commercial use rights. There is no setup fee, no per-seat charge and no overage billing — the monthly quota is a ceiling, not a meter.
What happens if I exceed my monthly API limit?
Requests past your monthly quota return HTTP 429. The JSON body carries a message and an upgrade URL, plus the timestamp your quota resets when that is known, and a matching Retry-After header so a client can back off correctly instead of retrying in a loop. You are never charged for calls beyond your plan — there is no overage billing. Before you get there, usage-alert emails go out at 80%, 90% and 100% of your quota on the self-serve plans — custom plans get 80% and 100% — and your dashboard shows live usage against the limit. Upgrading raises the limit immediately.
Do failed requests count against my quota?
Yes, if the request reached the API. Once your key is accepted, every request is counted once against your monthly quota regardless of what it returns — a 404 for an exercise ID that does not exist, or a 422 for a bad parameter, costs the same one call as a successful response. What is not counted is anything refused before the request reaches an endpoint: a missing or invalid API key, a request made after your quota is already used up, and a call to the routines or workouts endpoints from a plan that does not include them. Two rejections do land after the request has been dispatched and are therefore counted — asking for a non-English language, or for a bodymap image, on a plan that does not include it returns 403 and costs one call. Most endpoints cost exactly one call; the expanded ones report their true cost in the X-API-Calls-Cost response header.
Can I upgrade, downgrade or cancel my plan?
Yes, all three, from your dashboard. Changing plan in either direction goes through a fresh checkout and takes effect as soon as that completes — a downgrade's smaller quota and narrower endpoint access apply immediately, not at your next renewal — and it applies to the API key you already have, so the key never changes and nothing needs redeploying. There is no automatic proration or credit: the new plan is charged in full at checkout while the old subscription runs out the period you already paid for, so switch close to your renewal date if the timing matters. Cancelling is scheduled rather than immediate: you keep your paid plan, its quota and its endpoints until the end of the period you have already paid for, you are not charged again, and the account then moves to the free plan. A monthly plan has no minimum term and no cancellation fee; an annual plan is a twelve-month commitment charged upfront, so cancelling it stops the renewal rather than refunding the year. Custom plans are the exception — those terms are whatever we agreed with you.
Do I need a credit card to try the API?
No. The free BASIC plan needs no payment details of any kind: you sign up, and 500 Playground calls a month are available immediately. You only enter card details when you choose a paid plan, and that checkout is handled by Paddle — we never see or store your card number.
Is billing monthly or annual?
Either — every paid plan is offered on both cadences. Monthly plans renew each month. Annual plans are charged upfront for twelve months at a 25% discount and renew yearly until cancelled. Your monthly call quota is identical either way: annual billing is 25% off the price, not 25% more calls. The Monthly and Annual toggle on the pricing page shows the upfront amount for each plan.

Back to contents

Technical

Limits, response shape, media formats, languages, and what runs where.

Are there rate limits separate from the monthly quota?
No — with one narrow exception. The monthly call quota on your plan is the only volume limit we apply to the data and media-streaming endpoints: there is no per-second, per-minute or per-day rate limit on them, and no separate quota per endpoint. The exception is the media-token mint endpoint, POST /media/token, which accepts up to 10 requests per key per minute and answers 429 with a Retry-After header beyond that — a token is valid for 15 minutes, so a correctly implemented client refreshes far below that ceiling. The API Terms do reserve the right to restrict access in response to abusive traffic, and like most APIs we sit behind a CDN that independently protects against denial-of-service traffic, so if you are planning an unusually heavy burst — a bulk backfill, say — tell us first. That CDN layer sits outside our own application, so we cannot promise that no request is ever throttled there: treat 429 as possible on any endpoint, honour the Retry-After header, and back off rather than retrying immediately.
What data does each exercise include?
Every exercise returns a numeric ID and a stable set of fields for its name, primary muscles, equipment category, force type (push, pull or hold), grips, mechanic (isolation or compound), difficulty, written instructions and media. Values are not uniformly populated: force, mechanic and difficulty can be null; a small number of Recovery, Cardio and mobility exercises have no primary muscle list; and nearly every exercise includes step-by-step written instructions, with isolated source-data gaps tracked for correction. Each available video includes its URL, camera angle, gender variant and preview image. Male and female bodymap URLs are returned only when your plan includes bodymaps and that exercise has source images for them.
How many exercises have video demonstrations, and in what format?
All 1,943 exercises in the database have video demonstrations — there is no subset without them — which comes to 7,700+ video URLs in total. Nearly every exercise returns four: a male and a female demonstrator, each filmed from the front and from the side. Every video is an MP4 served over HTTPS from our streaming endpoints, and each one comes with a still preview image you can use as a poster frame. Videos are meant to be streamed straight from the URLs the API returns.
Which languages does the API support?
The API serves exercise, routine and workout text in 14 languages: English, Spanish, Portuguese, French, German, Italian, Polish, Russian, Turkish, Arabic, Persian, Hindi, Japanese and Chinese. Add a lang parameter — lang=pt-br, for example — to any data endpoint and you get translated names, instructions, muscles and categories back, while video and image URLs stay identical across languages. English is included on every plan; the other thirteen are available on the GROWTH plan and above, and to everyone in the free Playground.
How do I filter and search for specific exercises?
Two ways. The /search endpoint does text search with relevance sorting and tolerates word order, so "curl barbell" finds the barbell curl. The /exercises endpoint filters and paginates on structured fields — muscle group, equipment category, difficulty, force and mechanic — and /random returns one matching exercise if you want variety rather than a list. To discover what you can filter on, call /filters once: it returns every valid value in a single response, across 18 equipment categories, 45 muscle groups and four difficulty levels.
What are the routines and workouts endpoints?
Routines are structured training programmes built out of workouts, and workouts are ready-made sessions listing their exercises with prescription data — sets, reps and durations. You can fetch a routine with references to its workouts, or ask for the fully expanded version with every workout and exercise inlined in one response, which costs more than one API call and reports its exact cost in a response header. These endpoints are included on the PROFESSIONAL plan and above for direct API access — TESTING and GROWTH keys receive 403 with an upgrade link. They are also reachable from the free Playground on this site, like the rest of the API, so you can try them before choosing a plan.
Can I use the API in a mobile app, and does it work offline?
Yes — native iOS and Android apps are a primary use case, and there is nothing browser-specific about the API. Your permanent API key should stay on your own server rather than shipping inside the app binary: your backend exchanges it for a short-lived, media-only token that the app puts straight in a video URL, so a native player needs no custom headers. Fully offline use is not permitted, though, and the split matters: you may cache exercise text and metadata locally for up to 30 days, which is enough to open your app and browse the library without a round trip, but video and image assets may not be stored for offline playback. Media is licensed for streaming from the URLs the API returns, and the responses are sent with cache headers that say so.
Can I use the API in a native mobile app without embedding my API key?
Yes. Your backend calls POST /media/token to exchange its permanent API key for a short-lived, media-only token, then hands your app a plain video URL with the token in the query string — so AVPlayer and ExoPlayer need no custom headers and your permanent key never reaches the device. Tokens expire after 15 minutes by default, work only on media endpoints (never on data endpoints), and stop working immediately if the key behind them is revoked. Treat the resulting URL as a credential for as long as it lives: anyone who obtains it can stream media against your quota until it expires, so keep it out of your own logs, analytics and crash reports, and do not put it in a shared cache — we redact it from ours. Media fetched with a token meters against your key's quota exactly as a keyed request does.
How do I migrate from another exercise API?
There is no import tool, because the mapping is short enough to do with two endpoints. Call /filters once to get our full vocabulary of equipment categories, muscle groups and difficulty levels, and align it with the terms your current data uses. Run your existing exercise names through /search to find the MuscleWiki equivalent for each one. Then store our exercise ID alongside your own record rather than replacing your key with it — our IDs are MuscleWiki-specific integers, not a shared standard, and keeping both means your data survives if you ever change source again. The free Playground is enough to test all of this before you commit to a plan.

Back to contents

Licensing & data

What you may do with the exercise data and the videos, in plain terms.

Can I use the API commercially?
Yes — commercial use is the intended use case, and every paid plan includes it at no extra licensing cost. You can build and ship fitness apps, SaaS products, client work and internal tools on it. The licence covers using the data inside your own application or service, for fitness, health and workout-related purposes. What it does not cover is passing the data on: reselling it, redistributing it, exposing it through your own API, or building a competing dataset out of it.
Can I cache or store API responses?
Text and metadata, yes — you may cache exercise names, instructions, muscles, categories and the rest for up to 30 days, and caching is encouraged because it makes your app faster and spends fewer calls. Media is stricter. Thumbnail and preview images may be cached for up to 24 hours, but only privately, in the end user's own client — not in a shared proxy or CDN. Videos may only be cached transiently, meaning ordinary playback buffers, and the API sends them with a no-store cache header that says exactly that. Permanent storage of any media is not permitted.
Can I download, store or re-host the videos?
No. Videos, thumbnails and bodymap images may not be downloaded, exported, copied into your own storage, or re-hosted on your servers, your CDN or a social platform, and they may not be embedded outside your own application. Play them directly from the URLs the API returns — that is what the licence covers, and it is why video responses carry a no-store cache header. Passing media through your own backend as a transparent proxy is a separate thing and is permitted, provided nothing on your side ever retains the video bytes. Scraping or bulk-exporting media is also prohibited, and doing it is grounds for immediate suspension.
Can I stream your videos through my own backend or edge?
Yes. A transparent server-side proxy that holds your API key and passes our responses straight through to your app is permitted — useful if you'd rather not adopt media tokens. Two conditions: video is never written to disk or to a shared/CDN cache on your side, and you pass our response headers through unchanged (we send Cache-Control: no-store on video deliberately). What your edge may hold is exactly what the headers allow: exercise text and metadata for up to 30 days, and nothing else. Thumbnails are sent private, so they may be cached in the end user's own client for 24 hours but not at a shared edge; bodymap images are sent no-store and may not be cached at all; video is never stored anywhere on your side. Note that every /stream request counts as one API call, including each range request your player issues.
Can I use the data to train an AI or machine-learning model?
Not without written permission from us. Using API content to train machine-learning models, AI systems or datasets — including pose estimation and computer-vision work on the videos — is outside every standard plan, and no amount of quota changes that. It is available under a separate written agreement, so if that is your use case, talk to us before you build on it rather than after. Using an AI agent to read the API at runtime is a different thing entirely and is perfectly fine — that is what our MCP server is for.
Do I have to credit MuscleWiki in my app?
Two things are required, and a third is merely appreciated. Required: the line "Exercise data and videos provided by MuscleWiki.com", verbatim, in your terms of service, privacy policy or equivalent legal document; and leaving the MuscleWiki branding embedded in the videos intact — do not crop, overlay or re-encode in a way that hides it. Failing either of those is a material breach and can result in suspension. A credit visible to your end users, in a footer, about screen or credits page and linked to musclewiki.com, is encouraged but not required: the wording is yours, and omitting it is not a breach and has no effect on your API access.
Is the API data updated regularly?
Data is served from a single dataset the API loads at startup, so when it changes, every plan sees the new data at the same moment — there is nothing to pull, no migration to run and no extra charge. The API is also unversioned: there is no /v1 prefix in any URL and no dated release to pin, so your integration keeps calling the same endpoints as the data grows. We publish notable changes in the changelog. We do not publish an update schedule, so if your planning depends on one, ask us rather than inferring it from this page.

Back to contents

Still have a question?

Try the API for yourself in the Playground, read the endpoint reference, or check the pricing in detail.

Open the PlaygroundRead the documentationCompare plans

Not answered here? Get in touch.