Crunch Time: Embrace the Cookie Monster Within!

We use cookies to enhance your browsing experience and analyse our traffic. Nothing beyond essential cookies runs until you choose. You can change your mind any time in our Cookie Policy.

  • Unified API
  • Mobile SDK
  • Connection Widget
  • Streaming
  • Lab Reports API
  • Graph API
  • Health Scores
  • Health Rewards
  • Workouts & Routes
  • Predictions
  • Lab Testing
  • DNA Testing
  • AI Interface
  • Enterprise
  • Insurance
  • Integrations
  • Research
  • Podcast
  • Blog
  • Reports
  • Events
  • Documentation
  • Community
  • Example apps
  • Wearable Data
  • About
  • Customers
  • Partners
  • Startup Accelerator
  • Careers
  • Support
  • Pricing
Terra
PricingHLTH '26
Become an integrationGet started
next ventures
pioneer fund
samsung next
y combinator
general catalyst

The world's best health apps run on Terra data

Get started
ProductsIntegrationsAI InterfaceAuthenticationMobile DevelopmentDocumentationGraphAPIPredictionsDNA Testing
DocumentationAPISDKQuickstartExample Apps
CommunityBlogResearchCommunityPodcastAuthorsGithub
CompanyAboutCareersCustomersStartup AcceleratorBecome an IntegrationGDPRPrivacy PolicyYour Privacy ChoicesTerms of Purchase
© Terra API. 2026 — All rights reserved.
All articles

In this article:

  • 01Why workout targets have to be personalised per athlete
  • 02How Planned Workouts turns one template into each athlete's numbers
  • 03Which platforms Planned Workouts supports
  • 04How the API tells you what each watch changed
  • 05Why structured training is now a mainstream expectation
  • 06How to build your first planned workout
All articles

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.


26 October 2026

Terra's Planned Workouts API: Deliver a coach's workout to any watch with AI
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.

Get the latest Terra Research reports and insights every week as soon as they're published.

By continuing, I agree to the Privacy Policy and Terms of Service.

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.

Which platforms Planned Workouts supports

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.

Previous
Next

Continue reading

  • Terra API agent skills for building health products

    Give Claude, Cursor or Copilot the Terra API skills so your agent builds the integration from the current docs and gets the details right.

    15 October 2026

  • Eight Sleep data now flows through Terra API

    Members choose which apps receive their Eight Sleep sleep stages, heart rate, HRV, respiratory rate, snoring and sleep score, delivered through Terra API's sleep model.

    7 October 2026

  • Use synthetic data to rapidly prototype health products

    Synthetic users let you put your product through its paces with every health scenario, from marathoners to light sleepers, without waiting for those exact users to show up.

    18 September 2026