Workouts

The push is synchronous#

There is no job to wait on and no event to listen for. The call returns once every provider has answered — typically under a second — so pushes is what actually happened.

Which providers get it#

Garmin, Wahoo, COROS, Suunto and Apple Watch take workouts. Omit provider and it goes to every one of those your user has connected; name one to target it. Naming any other provider is a 422.

Suunto is suunto, and the workout arrives as a SuuntoPlus Guide rather than on a calendar: the Suunto app syncs it to the watch, and your user selects it under SuuntoPlus before pressing start. Each step shows its target and a countdown, starts a lap, and moves on by itself; scheduled_date is shown as the day the guide is for.

Not every Suunto watch runs guides. The Suunto Run and Run 2 have no SuuntoPlus, and Suunto gives us no other way to put a workout on them — your user can still build one by hand in the Suunto app. A guide pushed for one is listed in the Suunto app as "Not compatible with watch". Suunto accepts the guide either way, so we go by the watch your user last recorded a workout with — if it is one of those two, the push comes back unsupported and no guide is created. A user who has not recorded a workout since connecting has no watch on record, and their push is synced whatever they wear. The 3, 5 and 9 families, Race, Vertical and Ocean all take guides.

Apple Watch is apple, and it is reached through your own iOS app rather than a server of Apple's: the workout is accepted here and the StrideeHealth SDK schedules it. It counts as connected once the athlete has allowed your app to add workouts.

What each status means#

pending is normal, on Wahoo and Apple#

Wahoo only puts a workout on the device within six days of its date, so a session scheduled for next month is pending for weeks. Don't retry it: when the date comes into range we finish the push and it becomes synced. There is no event for that — read the status from GET /v1/workouts/{id} when you render the calendar.

An Apple push is pending until the athlete's phone next syncs — usually the next time they open your app — and for a workout further out than the Workout app has room for, until earlier ones have passed. See Workouts on Apple Watch.

Editing#

PATCH /v1/workouts/{id} takes the whole workout, not a partial one, and re-pushes it. DELETE /v1/workouts/{id} takes it off the devices, then off us. COROS only deletes workouts dated today or later that haven't been done. An Apple Watch copy is replaced or removed at the phone's next sync.

The step format#

A workout is a list of steps. A step is either an interval, a repeat of intervals, a repeat_until — intervals repeated until a condition is met — or, in a strength workout, an exercise. See Strength.

Intervals are typed by their role — warmup, active, recovery, rest, cooldown, and main for a swim's main set — which is what the watch shows and how it colours the screen.

A workout may also carry a description, up to 2,000 characters: the coach's notes, shown beside the workout on Garmin, COROS and Wahoo.

Sports#

running, treadmill_running, cycling, indoor_cycling, swimming, hiking, cardio, hiit, yoga, pilates, generic, strength and multi_sport. Not every provider takes every one — a swim is unsupported on Wahoo — and the pushes array tells you which did.

indoor_cycling is a ride on a trainer and treadmill_running a run on a treadmill. Send them when you know the session is indoors: Suunto, Wahoo and Apple Watch start their indoor mode, with no GPS. Garmin and COROS have no indoor workout sport, so they get a plain ride or run, and the athlete picks Bike Indoor or Treadmill when they start it. cycling and running are unchanged.

cardio, hiit, yoga, pilates and generic are timed intervals. Garmin supports generic on some devices only. A strength workout is written as exercises. See Strength.

A swim carries four fields the others do not, and its targets behave differently. See Swimming. A multi_sport workout carries segments in place of steps. See Multi-sport.

Limits#

A repeat may not contain another repeat. Watches render one level and we would rather refuse than silently flatten a session into something you did not write. Beyond that: 200 passes per repeat, 500 steps once repeats are expanded. A repeat_until counts its steps once.

On the watch#

Only Garmin takes strength workouts. It gets each exercise as a set of reps, with the load and the rest after it, repeated once per set. The watch counts down the sets and records them against the exercise.

We match name against Garmin's exercise library, so the watch can show Garmin's own exercise and log your sets under it. Write names the way a gym would, like "Barbell back squat" or "Dumbbell bench press".

• A name we can match arrives as Garmin's exercise.
• A name we can only place in a movement family, such as a squat or a row, arrives under that family. When Garmin has a generic exercise for the family, the watch shows that as the step's title: "Nordic hamstring curl" arrives as Garmin's "Leg Curl", and the sets are logged against it.
• A name we can't place at all still arrives, as a reps step labelled with your name.

Your name, and your note after it, always go in the step's description, whatever title the watch shows. The sets, reps, load and rest never change.

If Garmin refuses an exercise we chose, we send the workout again without Garmin's exercise names, and then without their families, rather than fail it. This applies to every step in the workout at once, not only the one Garmin refused.

COROS and Wahoo can't carry a load, so a workout with an exercise step comes back unsupported from both rather than arriving as bare reps.

stroke — per step, optional#

freestyle, backstroke, breaststroke, butterfly, individual_medley, reverse_individual_medley (IM backwards), individual_medley_by_round (a different IM stroke each round), reverse_individual_medley_by_round, drill, mixed, choice.

Omitted means no stroke was prescribed; choice means "swimmer's choice", and the watch shows it.

drill — per step, optional#

kick, pull, drill.

A drill layers over a stroke: freestyle + pull shows as Free Pull. Without a stroke it applies to whatever the swimmer is doing.

butterfly is deprecated. It still works and is sent as stroke: "butterfly" with drill: "drill", so write that pair instead.

equipment — per step, optional#

fins, kickboard, paddles, pull_buoy, snorkel.

For no equipment, omit the field.

Rests#

A rest with a time duration is a fixed rest at the wall: "seconds": 20 is twenty seconds of rest, however long the swim before it took. The last rest of a repeat block is dropped.

main — the main set#

A step typed main is a swim's main set, shown as such on Garmin. It is swim-only.

Where the swim fields are refused#

All four are swim-only, and so are send-offs, main, css_offset and swim_instruction. Sending one on a run is a 422, not a field we quietly drop.

What reaches each provider#

What each provider can carry#

Garmin carries everything on this page. COROS, Wahoo and Suunto carry time, distance, yards, miles, reps and open durations, pace, heart_rate, power and cadence targets, and plain repeat blocks. Anything else — a threshold duration, a zone, a percentage, grade, resistance, an average, a secondary_target, a repeat_until, a send-off, a multi_sport workout, a strength exercise — comes back unsupported from those three rather than being turned into a different workout. The sport lists differ too: Wahoo takes running, treadmill_running, cycling, indoor_cycling and hiking; COROS takes running, treadmill_running, cycling, indoor_cycling and swimming; Suunto takes any sport, and ends a reps step on a lap press because a watch cannot count them.

Apple Watch sits between: it adds calories, heart_rate_zone, power_zone and a lap average to that list, takes every sport but strength and multi_sport, and needs a scheduled_date. What an Apple Watch can carry has the detail.

Rate limit#

60 device pushes a minute per account — one workout to a user with three watches is three. Apple pushes don't count: they call no provider. Over it is a 429; wait a minute. Providers rate-limit us across every customer, so spread a season's plan over a few minutes rather than sending it in one loop.