Documentation

v2Last updated: Feb 2026

API Documentation

Everything you need to integrate YMove exercise videos into your application.

Get a key
AuthBase URLExercisesWorkouts & ProgramsForm AnalysisAccountMusclesTypesRate LimitsMonthly LimitsVideoSubscriptionsCode

Authentication

Include your API key in the X-API-Key header with every request:

curl -H "X-API-Key: ym_your_key_here" \
  https://exercise-api.ymove.app/api/v2/exercises

Alternatively, pass as a query parameter: ?api_key=ym_your_key_here

Base URL

https://exercise-api.ymove.app/api/v2

OpenAPI spec available at https://exercise-api.ymove.app/api/v2/openapi.json

Video URLs Expire After 48 Hours - Refetch Them

All video and thumbnail URLs returned by the API are pre-signed and temporary. They will stop working after 48 hours.

You must:

  • Never store or cache video URLs in your database
  • Always fetch fresh exercise data from the API before displaying videos
  • Re-fetch on error - if a video fails to load, call the API again to get new URLs

Never expose your API key in client-side code. Always call the YMove API from your backend and proxy the video URLs to your frontend.

Exercises

Browse, search, and retrieve exercise data with videos.

Workouts & Programs

Generate structured workouts and multi-week training programs.

Form Analysis

AI-powered exercise form analysis from video.

Account

Check your API usage, plan limits, and manage your subscription.

Muscle Groups Reference

chestbackshouldersbicepstricepsforearmsquadshamstringsglutescalvescorefull_body

Exercise Types Reference

Exercises can have multiple types. Use the exerciseType query parameter to filter by type. The response includes an array of types per exercise.

strengthyogastretchingcardioplyometriccalisthenicswarmupcooldownbalancemobilityisometricrehabilitationfunctionalcorehiit

Rate Limits

All v2 endpoints enforce per-minute rate limits based on your plan:

PlanRequests / minute
Demo10
Trial50
Light (Starter)250
Pro350
ScaleUnlimited
EnterpriseUnlimited

Exceeding the limit returns 429 with a retryAfterMs field.

Video minutes: Video duration is also counted against your plan's minute limit. Starter: 10,000 min/mo, Scale: 50,000 min/mo, Pro: 25,000 min/mo, Enterprise: 100,000 min/mo.

Form Analysis: Starter includes 10/month, Pro includes 25/month, Scale includes 50/month, Enterprise includes 200/month. Additional analyses are $0.25 each.

Check your usage at any time via the /usage endpoint.

Monthly Exercise Limits

To prevent bulk scraping, the number of unique exercises you can access with video URLs per month is capped. When the cap is exceeded, the API still returns exercise data but removes video properties entirely (videoUrl, videoHlsUrl, thumbnailUrl, videoDurationSecs, videos) from exercises you have not previously accessed. Exercises you already accessed within the 30-day window keep their video URLs.

PlanUnique exercises / month
Demo10
Trial100
Light (Starter)250
Pro350
ScaleUnlimited
EnterpriseUnlimited
Yearly (any plan)Unlimited

Accessing the same exercise multiple times only counts once. The window is a rolling 30 days. The /usage endpoint shows monthlyExercisesUsed and monthlyExerciseLimit.

When the cap is exceeded:

  • Responses include a _warning object with reason: "monthly_exercise_cap"
  • Video properties are removed entirely (not set to null) from new exercises — your app should handle missing keys
  • Previously accessed exercises still include full video URLs
  • All exercise metadata (title, instructions, muscle group, etc.) is always returned

Video Access

Video URLs in v2 responses are pre-signed CDN URLs that can be used directly in <video> and<img> tags without any additional authentication:

// Video URLs from API response work directly:
<video src={exercise.videoUrl} controls />
<img src={exercise.thumbnailUrl} alt={exercise.title} />

// Example URL format:
// https://vz-603865.b-cdn.net/abc123/play_720p.mp4?token=xyz&expires=1234567890

Important: Video URLs expire after 48 hours. Do not store or cache these URLs. Always fetch fresh exercise data from the API before displaying videos. If a video fails to load, re-fetch the exercise to get new signed URLs.

Watermarking: Trial and Starter plans receive watermarked videos. Pro and Enterprise plans receive clean, unwatermarked videos.

Why signed URLs? This approach keeps your API key secure — it never needs to be exposed in client-side code or URL parameters. The API handles authentication, and you get temporary URLs that work directly in the browser.

v1 deprecation notice: The v1 API continues to work, but all new features and protections are v2-only. We recommend migrating to v2 for the best experience.

Subscriptions & Upgrades

You can manage your subscription entirely through the API. Use your API key to check available plans, start a subscription, or upgrade your current plan.

Check available plans

GET /api/v2/upgrade
Headers: X-API-Key: ym_your_key_here

Response:
{
  "currentPlan": "demo",
  "availablePlans": [
    { "plan": "basic", "minutesLimit": 10000, "postureLimit": 10, "brandLimit": 1 },
    { "plan": "pro", "minutesLimit": 25000, "postureLimit": 25, "brandLimit": 1 },
    { "plan": "scale", "minutesLimit": 50000, "postureLimit": 50, "brandLimit": 3 },
    { "plan": "enterprise", "minutesLimit": 100000, "postureLimit": 200, "brandLimit": 10 }
  ],
  "billingPortalUrl": "https://billing.stripe.com/..." // if you have an active subscription
}

Start a subscription or upgrade

POST /api/v2/upgrade
Headers: X-API-Key: ym_your_key_here
Body: { "email": "you@example.com", "plan": "pro" }

Response:
{
  "url": "https://checkout.stripe.com/...",
  "message": "Open this URL to start your pro subscription."
}

The response contains a Stripe Checkout URL. Redirect your user to this URL to complete payment. Subscriptions start immediately (no trial period). The email field is required for demo keys, optional for existing subscribers.

Manage billing (existing subscribers)

If you already have an active subscription, the GET /api/v2/upgrade response includes a billingPortalUrl. Open this URL to change plans, update payment method, or cancel your subscription through Stripe's billing portal.

Available plans: basic (Starter), pro, scale, enterprise. See the Rate Limits section for details on each plan's limits.

Code Examples

const API_KEY = 'ym_your_key_here';
const BASE = 'https://exercise-api.ymove.app/api/v2';

// List chest exercises
const exercises = await fetch(`${BASE}/exercises?muscleGroup=chest&hasVideo=true`, {
  headers: { 'X-API-Key': API_KEY }
}).then(r => r.json());

// Generate a workout
const workout = await fetch(`${BASE}/workouts/generate?muscleGroup=back&difficulty=intermediate`, {
  headers: { 'X-API-Key': API_KEY }
}).then(r => r.json());

// Generate a 4-week program
const program = await fetch(`${BASE}/programs/generate?goal=muscle_building&daysPerWeek=4&weeks=4`, {
  headers: { 'X-API-Key': API_KEY }
}).then(r => r.json());

// Analyze exercise form from video (max 100MB)
const fs = require('fs');
const videoBase64 = fs.readFileSync('squat.mp4').toString('base64');
const analysis = await fetch(`${BASE}/posture/analyze`, {
  method: 'POST',
  headers: { 'X-API-Key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    video: { type: 'base64', data: videoBase64, media_type: 'video/mp4' },
    exercise_name: 'Barbell Back Squat',
    custom_instructions: 'Watch my knee tracking',
    num_frames: 16
  })
}).then(r => r.json());

Ready to get started?

Start your free trial and get your API key in seconds.

Start Free Trial