Moving from v1 to v2

v2 is a new exercise library: 1,900+ movements as 2,700+ clips, 720p MP4 animations at 30 fps, and male and female models. This guide shows what changes in your integration and how to move one screen at a time.

What stays the same

• Your API key. The same key works on v1 and v2, so both can run side by side while you migrate.
• Your plan and price. Current subscribers keep their plan and price for as long as their subscription stays active, with v2 included at no extra cost.
• v1 itself. v1 keeps working after v2 launches. You'll get at least 30 days' notice by email before it's retired.
• Languages. ?lang= works as in v1, with the same languages: Turkish (tr), German (de), Spanish (es), French (fr), Simplified Chinese (zh-SG) and Traditional Chinese (zh-HK). Names, instructions, tips, muscles and terms are translated; filter values stay in English.
• Filters, quotas and errors. bodyPart, target and equipment take the same values as in v1. Request quota, rate limits, usage headers and the error format don't change.

What changes

Migrate in five steps

1. Send the key in the header Change the path from /v1 to /v2, and move the key from ?api-key= to the X-WorkoutX-Key header. Keys in URLs end up in app bundles and server logs, so v2 refuses them.

   curl 'https://api.workoutxapp.com/v2/exercises?bodyPart=chest&limit=10' \
     -H "X-WorkoutX-Key: wx_your_key_here"

2. Map the exercise ids you've stored For each v1 id your app saves (in workouts, favorites or history), call the legacy endpoint once and store the v2 id it returns. Leading zeros are optional.

   GET /v2/exercises/legacy/0662
   
   {
     "v1Id": "0662",
     "v1Name": "Push-up",
     "match": "equivalent",
     "exercise": { "id": "ex_WOZL6H", "name": "Push Ups Bodyweight", ... }
   }

   The match field says how close the v2 exercise is:

   match	Meaning	What to do
   exact	The same movement	Replace automatically
   equivalent	The same movement, named differently	Replace automatically
   alternative	The same movement with other equipment, or a close variation	Suggest it, and let users confirm
   closest	The nearest exercise for the same muscles	Suggest it, and let users confirm
   none	No v2 exercise yet (exercise is null)	Keep the v1 exercise for now

   1,324 of the 1,327 v1 exercises have a v2 match. 582 of them are the same movement (exact or equivalent).
3. Replace the GIF with a video Play media.mp4 muted and looping, and show media.poster while it loads or in lists. MP4 plays natively on every platform and is usually smaller than the GIF it replaces.

   Web

   <video src="{media.mp4}" poster="{media.poster}"
          autoplay loop muted playsinline></video>

   iOS (Swift)

   let item = AVPlayerItem(url: URL(string: media.mp4)!)
   let player = AVQueuePlayer()
   let looper = AVPlayerLooper(player: player, templateItem: item)  // keep a reference
   player.isMuted = true
   player.play()

   Android (Kotlin, Media3 ExoPlayer)

   val player = ExoPlayer.Builder(context).build().apply {
       setMediaItem(MediaItem.fromUri(media.mp4))
       repeatMode = Player.REPEAT_MODE_ONE
       volume = 0f
       prepare()
       play()
   }

   Flutter (video_player)

   final controller = VideoPlayerController.networkUrl(Uri.parse(media.mp4));
   await controller.initialize();
   await controller.setLooping(true);
   await controller.setVolume(0);
   await controller.play();

4. Store ids, not media links Media links are signed and stop working 24–25 hours after they're issued (media.expiresAt). Save the exercise id, and get links when you show the exercise: from the exercise response, or from GET /v2/exercises/{id}/media when they've expired. Within the same hour the API returns identical links, so normal caching keeps working. Downloading the files or serving them from your own servers or CDN isn't permitted on any plan.
5. Offer the female model Male and female versions are separate exercises. counterpartId points at the same movement with the other model, so you can show it as a switch. To list one model only, filter with ?model=female or ?model=male.

Media by plan

A media view is one video or poster started; a player's follow-up range requests don't count. On Starter, once 1,000 different exercises have been used in any 30 days, new exercises come back with media: null and mediaLimitReached: true, while the ones you already use keep working. The X-Media-Exercises-Limit, -Used and -Remaining headers show where you are.

SDKs

v2 support in the JavaScript and Python SDKs ships with the launch (Swift and Flutter follow). They add wx.v2 with the same endpoints, and freshMedia(id), which reuses media links until they're close to expiry and fetches new ones after that.

Questions

Anything unclear, or a v1 exercise you need in v2? Email business@workoutxapp.com.