Product Updates
Terra's Planned Workouts API: Deliver a coach's workout to any watch with AI
Build a session once with Terra's Planned Workouts API and it appears on any watch, from COROS to Apple, tuned to each athlete's own training trajectory.
TL;DR: The Planned Workouts API takes one session template and delivers it to each athlete's watch, tuned to their own numbers. You create a training session once as a template, and when you schedule it for a particular athlete, we take into account that athlete's individual FTP, maximum heart rate, or threshold speed and send the session to their watch. You can now also use AI to create those sessions: describe a workout in plain language and the AI builder in the Terra dashboard turns it into a structured template. Support is available for COROS, Wahoo, Suunto, TrainingPeaks, Huawei, Zepp, Hevy and Apple Watch amongst other platforms. If a particular platform can't represent a certain part of the session, we adjust the relevant step and let you know exactly what changes have been made. The
terra-planned-workouts skill helps in getting your coding agent started.
A coach can design a clean interval session by setting a power target, a heart-rate cap, and a cadence floor, and it will look perfect in the app. It still has to reach the athlete's watch, and each platform displays a workout in its own way and only supports a certain portion of what a coach is able to specify. The Planned Workouts API does that translation once, for every platform.
Why workout targets have to be personalised per athlete
The whole API rests on one idea, namely that the training targets should be relative to the individual athlete because setting the same absolute target would subject two different people to very different levels of strain. There is good evidence in support of this. In a randomised trial, the intensity calculated from each person's own thresholds was compared with the traditional method of employing a percentage of maximum, and the group that received individually tailored training improved their VO2max (a standard measure of aerobic fitness) by a great deal more, with considerably less variation in the extent to which the individuals responded. In a further study that followed the same approach, 79% of the individualised group responded, against 47% of the group trained on a percentage of maximum.
How Planned Workouts turns one template into each athlete's numbers
We deal with the problem in the same manner as a coach does by first preparing the workout as a template, setting out the steps and how long each one should last together with the targets, whether they are given in relative or absolute terms, and then arranging it according to the athlete's individual characteristics.
POST /v2/workouts/{workout_id}/plan?user_id=...
{ "planned_date": "2026-07-20",
"ftp": 280,
"max_heart_rate": 188 }
This athlete's device shows a step corresponding to 95 to 100% of their FTP as ranging from 266 to 280 watts, while a teammate's device shows it as 190 to 200 watts (the teammate also uses the same template and has an FTP of 200). On platforms that take the percentage directly, the athlete's own FTP on the device sets the watts. Targets may be set absolutely, for instance in terms of heart rate, power, pace, speed, cadence or RPE, or they can be based on a percentage of the maximum heart rate, the threshold heart rate, FTP or threshold speed, or they can be zone-based. On most platforms a single-value target is given a sensible range around it.
COROS, Wahoo, Suunto, TrainingPeaks, Huawei, Zepp, Hevy and Apple Watch, among others. For each of these platforms we provide the format that it demands, and we also address each platform's particular scheduling requirements, for example Zepp's seven-day sync window.
Apple deserves its own sentence since it functions differently in that the session goes through our iOS SDK, which then forwards it on to WorkoutKit so that it shows up in the native Workout app on the watch, and confirmation is then sent back to you once the phone has synced it.
How the API tells you what each watch changed
The part that matters most: if a platform is unable to express something within your template, we modify the step, create the workout anyway, and let you know about the changes. The response is still regarded as a success; it simply comes with a list of warnings.
{ "planned_workout_id": "…",
"warnings": [
{ "path": "workout.step_blocks[0].steps[0].intensity_targets",
"message": "Zepp supports one primary target and one optional cadence secondary target, ignoring 2 extra target(s)" } ]}
The way each platform designs its experience involves providing one target at each stage, including a single warmup and cooldown on Apple and short step names on some of the watches; that is how the platforms work, and the API fits the session to them. Thanks to the warnings, you will become aware of the problem at the moment the workout is pushed and will have access to a machine-readable format which you can pass on to the coach. If no such warnings are given, the first sign will be the athlete asking after the session why the cadence cue had never appeared.
Why structured training is now a mainstream expectation
In April 2025 Strava acquired Runna, and then, five weeks later, carried out the acquisition of The Breakaway, thereby entering the plan generation market twice during the same spring. Meanwhile, Apple added a custom workout builder with pace, heart-rate, cadence and power targets in iOS 26 and watchOS 26. What was once a feature restricted to coaching has now become one that mainstream users expect, and all the apps which provide training plans want this function to be available on the wrist.
How to build your first planned workout
The complete step and target reference is in the Planned Workouts docs and the per-platform behaviour in the provider compatibility matrix, and the Terra dashboard features an AI builder which takes a plain-language description of a session and converts it into a structured template from which you can schedule the session, providing a useful method of understanding the data structure prior to writing any code. Also, if an agent is responsible for writing your integration, the terra-planned-workouts skill will include the per-platform behaviours referred to above.
