Planned Workouts

A planned workout is a workout the user means to do on a day, planned by the user or by a coach they allowed to, with its steps, targets and planned time or distance. It is a plan rather than a record, so it is not an item: what was actually done stays an Activity, and each planned workout carries how it compares with it.

A step’s target can be absolute, a percentage of the user’s own threshold (maximum heart rate, threshold power or threshold pace), or one of the user’s zones, which is what lets one workout suit many athletes. Pace is given as a speed in meters per second.

Listing Planned Workouts

This method lists the workouts planned between two days, earliest first.

GEThttps://api.fitnesssyncer.com/api/planned/
Scopeplanned_workout_read
Example request
curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/planned/"
Query Parameter NameDescription
startThe first day, as YYYY-MM-DD in the user’s time zone. Default is today.
endThe last day, as YYYY-MM-DD. Default is 27 days after start, and a range longer than 366 days is shortened to 366.

Response

The HTTP Response Code will be a 200 on success and the body will be a Planned Workout List.

Get a Planned Workout

This method gets one planned workout by id.

GEThttps://api.fitnesssyncer.com/api/planned/id
Scopeplanned_workout_read
Response 200Planned Workout
Example request
curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/planned/id"

Request Parameters

None

Response

The body with a Planned Workout, or a 404 when there is no planned workout with that id.

How a Planned Workout Went

This method judges the activity a planned workout matched against each of its steps: how long each step lasted, the average of the measure its target is set in, the share of the step’s time inside the target, and whether it was on target. Repeats are written out one repetition per row, and each repeat’s first and last repetitions are compared for how far power or pace faded and how far heart rate drifted. The recording is lined up with the steps by its laps when there is one lap per step, as a device that ran the workout records; otherwise the steps are laid end to end from its start, and the alignment says which. A recording without samples gets only the totals. The last earlier time the same workout was done is summarized as well.

It reads the activity’s samples, so it needs the activity scope as well as the planned workout one.

GEThttps://api.fitnesssyncer.com/api/planned/id/analysis
Scopesource_data_activity_readplanned_workout_read
Example request
curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/planned/id/analysis"

Request Parameters

None

Response

The body with a Planned Workout Analysis, or a 404 when there is no planned workout with that id. A workout not yet done returns its status and nothing else.

Download a Planned Workout File

This method writes the workout in a file format a device or another service reads. A target the format cannot carry is left out, and a percentage is converted with the user’s thresholds where the format needs an absolute value.

GEThttps://api.fitnesssyncer.com/api/planned/id/file
Scopeplanned_workout_read
Response 200String
Example request
curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/planned/id/file"
Query Parameter NameDescription
formatOne of FIT (the default), ZWO, ERG, MRC, GarminJSON or Text.

Response

The file, with a Content-Disposition naming it, or a 400 for a format that cannot be written.

Plan a Workout

This method plans a new workout. The date is required. The workout is also sent to each of the services the user chose in Planning settings, such as Wahoo, Hammerhead, Intervals.icu, TrainerDay, Nolio or Rouvy.

PUThttps://api.fitnesssyncer.com/api/planned/
Scopeplanned_workout_write
Request bodyPlanned Workout
Response 200Planned Workout

Request Parameters

A body containing a Planned Workout

Response

The body with the created Planned Workout, including the id assigned to it and the same deliveryWarnings an update returns.

Update a Planned Workout

This method changes a planned workout. Send only the properties being changed; anything omitted is left as it is. Moving the date, replacing the steps and marking it skipped are all done this way. The workout is changed on the services it was sent to as well. A workout the user’s coach planned (byCoach) can only be marked skipped or not while that coach still coaches them; any other change is answered with a 403.

POSThttps://api.fitnesssyncer.com/api/planned/id
Scopeplanned_workout_write
Request bodyPlanned Workout
Response 200Planned Workout

Request Parameters

A body containing a Planned Workout

Response

The body with the updated Planned Workout. Its deliveryWarnings say, in the user’s language, what did not reach the services it is sent to and what they could not carry, and are empty when all of it arrived.

Delete a Planned Workout

This method deletes a planned workout, and removes it from the services it was sent to. A workout the user’s coach planned cannot be deleted while that coach still coaches them.

DELETEhttps://api.fitnesssyncer.com/api/planned/id
Scopeplanned_workout_write
Response 200Object
Fields
JSON ItemData TypeDescription
statusString
removedEverywhereBoolean
Example request
curl -X DELETE -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/planned/id"

Request Parameters

None

Response

The HTTP Response Code will be a 200 on success, a 403 for a workout the user’s coach planned, or a 404 when there is no planned workout with that id.

On success the body’s removedEverywhere is false when a service the workout was sent to could not be reached, so a copy may still be there. Say so to the user rather than reporting it gone.

Preview Workout Steps

This method reads steps written as text, in the stepsText property, and returns the planned workout they make without saving it, so an editor can show what it understood while the user types. Steps are written one to a line, as the website’s editor takes them: a line starting with a dash is a step, such as - 10m 50-65% FTP, and a line such as 5x repeats the steps under it until a blank line.

POSThttps://api.fitnesssyncer.com/api/planned/preview
Scopeplanned_workout_read
Request bodyPlanned Workout
Response 200Planned Workout

Request Parameters

A body containing a Planned Workout with sport and stepsText

Response

The body with the Planned Workout the text makes, including its steps and planned time. Nothing is saved.

Listing Saved Workouts and Plans

This method lists the workouts and multi-day plans the user has saved on the website’s training calendar, newest first.

GEThttps://api.fitnesssyncer.com/api/planned/library
Scopeplanned_workout_read
Example request
curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/planned/library"

Request Parameters

None

Response

The body with a Planned Workout Library.

Save a Workout or Plan to the Library

This method saves one planned workout, or every workout planned over some weeks as a named plan, to the user’s library, as Save to my library and Save weeks as a plan do on the website.

POSThttps://api.fitnesssyncer.com/api/planned/library
Scopeplanned_workout_write

Request Parameters

A body containing a Planned Workout Library Save: either workoutId, or start and weeks (1 to 16) with an optional name.

Response

The body with the Planned Workout Library Item saved, or a 404 when there is no planned workout with that id or nothing is planned in those weeks.

Generate a Draft Training Plan

This method writes a draft plan for running, cycling or swimming from a goal and the days the user can train, saves it to the user’s library as a plan, and returns it as a preview. Nothing is put on the calendar until the plan is applied. The plan is built by fixed rules rather than a model, so the same request always gives the same plan: its training phases are the ones the season plan proposes for a race, its first week starts from the user’s own minutes in that sport over the last four weeks when the token may also read their activities (source_data_activity_read), and otherwise starts gently, and its step targets are percentages of the user’s own thresholds, or written as an effort when there is none. It takes no injury or health condition into account.

POSThttps://api.fitnesssyncer.com/api/planned/library/generate
Scopeplanned_workout_write

Request Parameters

A body containing a Planned Workout Generate. Give a race from the season plan, or a date, or neither for a block of weeks.

Response

The body with a Planned Workout Generated Plan, or a 400 when no training day was given (PlanNoTrainingDays), the date leaves no time to plan for (PlanNoTimeToPlan), or the race is not one the token may name (PlanUnknownRace). To put it on the calendar, apply its item with its start as the date and its trainingDays, and every workout lands on the day the preview shows.

Delete a Saved Workout or Plan

This method removes a saved workout or plan from the library. Workouts already planned from it stay on the calendar.

DELETEhttps://api.fitnesssyncer.com/api/planned/library/id
Scopeplanned_workout_write
Example request
curl -X DELETE -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/planned/library/id"

Request Parameters

None

Response

The HTTP Response Code will be a 200 on success, including when there is no saved workout or plan with that id.

Plan a Saved Workout or Plan

This method plans a saved workout, or every workout of a saved plan, with the first on the given date and the rest on the days that follow as the plan lays them out. Each is sent to the user’s planned-workout destinations as one planned directly would be.

POSThttps://api.fitnesssyncer.com/api/planned/library/id/apply
Scopeplanned_workout_write

Request Parameters

A body containing a Planned Workout Apply

Response

The body with a Planned Workout List of the workouts planned, or a 404 when there is no saved workout or plan with that id.

Types

Planned Workout

JSON ItemData TypeDescription
idStringUnique id of the planned workout. Read-only.
dateStringThe day it is planned for, as YYYY-MM-DD.
minuteOfDayIntegerMinutes after midnight when it is planned for a time of day. Absent for a workout planned for the day, which is most of them.
sportStringThe kind of activity, as the canonical activity name (Running, Cycling, Swimming, Walking, Hiking, Rowing, Strength, Yoga, Elliptical, Cross Training or Other).
titleStringThe workout’s name. Truncated at 120 characters.
descriptionStringNotes for the athlete. Truncated at 4000 characters.
stepsArray of Planned Workout StepThe structure of the workout, in order. May be empty for a workout described only by its planned time or distance.
stepsTextStringThe steps written as text, one step to a line, as the website’s editor takes them, for example "Warmup", "- 10m 50-65% FTP", "5x", "- 3m 105% FTP", and for strength "- 3x10 Back Squat 60kg rest 90s". Returned in the User’s units. When written, it replaces steps and is read for the workout’s sport.
plannedSecondsDoublePlanned time in seconds. Read back as the sum of the timed steps when there are steps; set it directly for a workout without steps, or for one with a step that ends by distance or with the lap button, whose time the steps cannot say.
enteredSecondsDoubleThe planned time as it was set, whatever the steps add up to, and 0 when none was. Set it through plannedSeconds. A destination that needs a workout’s length, such as Wahoo, uses this when a step does not end by time. Read-only.
deliveryWarningsArray of StringOnly in the answer to creating or changing a workout, in the User’s language. What did not reach the platforms the User sends planned workouts to, and what those platforms could not carry. Empty when all of it arrived. Read-only.
plannedMetersDoublePlanned distance in meters, read back the same way as plannedSeconds.
sourceStringWhere the workout came from. Must be one of Athlete, Coach, File, Provider. Read-only.
byCoachBooleanWhether it is the work of a coach who still coaches the User, in which case it is the coach’s to change and the User may only mark it skipped or not. Once the coaching ends, or the coach’s plan lapses, this is false and the workout is the User’s. A workout’s source still says where it came from. Read-only.
skippedBooleanWhether the User marked it as skipped.
skipReasonStringWhy it was skipped, if the User said.
statusStringHow it compares with what was recorded. Must be one of Planned, Completed, Partial, Missed, Skipped. Completed means a recorded activity of the same sport on that day came within 20 percent of the plan; Partial means one was recorded but further off. Read-only.
complianceDoubleThe recorded amount over the planned one, by time where the plan has a time and otherwise by distance. Absent when nothing was recorded or the plan names no amount. Read-only.
matchedItemIdStringThe id of the recorded Activity this workout was matched to, so a calendar can show the two as one. Absent when nothing was matched. Read-only.
matchedTaskIdStringThe task id of that Activity, which with matchedItemId identifies it. Read-only.
modifiedLongWhen it was last changed, in milliseconds since the epoch. Read-only.

Planned Workout Step

JSON ItemData TypeDescription
repeatIntegerFor a repeat, how many times its steps are done.
stepsArray of Planned Workout StepFor a repeat, the steps repeated. They are steps, never further repeats.
intensityStringMust be one of Warmup, Active, Recovery, Rest, Cooldown.
durationStringWhat ends the step. Must be one of Time, Distance, LapButton, Calories, Repetitions.
durationValueDoubleSeconds, meters, calories or repetitions, as duration says. Absent for LapButton.
targetStringWhat the step asks the athlete to hold. Must be one of HeartRate, Power, Pace, Cadence. Absent for no target.
scaleStringHow low and high are expressed. Must be one of Absolute, PercentOfThreshold, Zone. A percentage is of maximum heart rate, threshold power or threshold pace; a zone is one of the User’s own zones.
lowDoubleThe bottom of the target range, in beats per minute, watts, meters per second (for pace) or revolutions per minute when absolute.
highDoubleThe top of the target range, in the same units as low.
noteStringA note shown with the step. For a strength set naming an exercise the catalog does not have, the exercise is written here.
exerciseStringFor a strength set, the exercise. One of BackSquat, FrontSquat, GobletSquat, LegPress, BenchPress, DumbbellBenchPress, InclineDumbbellPress, Deadlift, RomanianDeadlift, OverheadPress, DumbbellShoulderPress, BarbellRow, DumbbellRow, SeatedCableRow, PullUp, ChinUp, LatPulldown, Lunge, WalkingLunge, PushUp, Plank, BicepsCurl, BarbellCurl, TricepsPressdown, HipThrust, CalfRaise, LegCurl, LateralRaise, DumbbellFly, Shrug, Crunch; more may be added, so treat an unknown value as an exercise you cannot name. Absent for a step that is not an exercise from this list.
weightDoubleFor a strength set, the weight to lift in kilograms. Absent for none.

Planned Workout List

JSON ItemData TypeDescription
startStringThe first day returned, as YYYY-MM-DD.
endStringThe last day returned, as YYYY-MM-DD.
itemsArray of Planned WorkoutThe planned workouts, earliest first.

Planned Workout Library

JSON ItemData TypeDescription
itemsArray of Planned Workout Library ItemNewest first.

Planned Workout Library Item

JSON ItemData TypeDescription
idStringId to apply it by.
kindStringMust be one of Workout, Plan.
nameStringThe name it was saved under.
daysIntegerHow many days it spans, at least one.
workoutsIntegerHow many workouts it holds.
sportStringThe sport of its first workout.

Planned Workout Library Save

JSON ItemData TypeDescription
workoutIdStringId of the planned workout to save. When given, the others are ignored.
startStringThe first day of the plan, as YYYY-MM-DD.
weeksIntegerHow many weeks from start the plan holds, from 1 to 16.
nameStringThe plan’s name.

Planned Workout Generate

JSON ItemData TypeDescription
sportStringMust be one of Running, Cycling, Swimming. Anything else is read as Running.
startStringThe first day of the plan, as YYYY-MM-DD. Leave it out, or give a day already past, to start today.
raceStringId of a race in the season plan to train for, which wins over date. The season plan belongs to the FitnessSyncer apps, so only their token can name one; any other token that sends it is refused with PlanUnknownRace.
dateStringThe race or goal date, as YYYY-MM-DD. Leave both race and date out for a block of weeks that builds steadily with no peak and no taper.
weeksIntegerHow many weeks a block with no race or date holds, from 1 to 16. 8 when left out.
trainingDaysArray of StringThe days of the week the User can train, each written as a day name. Must be one of MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY. The plan may use fewer, and says so in its warnings.
longDayStringThe day of the week for the long session, written as in trainingDays. The last training day of the week when left out.
experienceStringMust be one of Beginner, Intermediate, Advanced. Leave it out to decide from the User’s recent training. With no recent training in the sport, the plan is always the Beginner one.

Planned Workout Generated Plan

JSON ItemData TypeDescription
itemPlanned Workout Library Item
startStringThe day to apply it from, as YYYY-MM-DD. It can be later than the start asked for, when the race is more than 16 weeks away.
trainingDaysArray of StringThe days of the week the plan uses, to apply it with, so every workout lands on the day shown.
experienceStringThe band the plan was written for. Must be one of Beginner, Intermediate, Advanced.
firstWeekMinutesIntegerMinutes of training in the plan’s first full week.
summaryStringA sentence in the User’s language saying the draft is in the library and what its first week was based on.
warningsArray of Planned Workout Generate WarningWhat the User should know about the plan before applying it.
workoutsArray of Planned Workout Generated DayEach workout of the plan on the day it falls on when applied as returned.

Planned Workout Generate Warning

JSON ItemData TypeDescription
codeStringMust be one of NoHistory, ShortRunUp, LongRunUp, TooManyDays, NoThreshold, SwimByEffort, HistoryNotShared. More may be added.
messageStringThe warning in the User’s language.

Planned Workout Generated Day

JSON ItemData TypeDescription
dateStringThe day it falls on, as YYYY-MM-DD.
sportStringThe sport it is planned as.
titleStringIts title, in the User’s language.
descriptionStringIts training phase and week of the plan, in the User’s language.
minutesIntegerHow long its steps take.

Planned Workout Apply

JSON ItemData TypeDescription
dateStringThe day of its first workout, as YYYY-MM-DD.
trainingDaysArray of StringThe days of the week the athlete trains, each written as a day name. Must be one of MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY. An abbreviation of three letters or more is read as that day, and case is ignored. Within each seven days from the start, the days the plan uses are taken in order and the first goes on the first training day, the second on the second, and so on, with every workout of a day moving together. A week using more days than are given here keeps the rest where the plan put them. Leave this out, or send an empty array, to keep the plan’s own days.

Planned Workout Analysis

JSON ItemData TypeDescription
workoutIdStringId of the planned workout.
statusStringWhere the workout stands. Must be one of Planned, Completed, Partial, Missed, Skipped.
matchedItemIdStringId of the activity the workout matched. Absent when it matched none, and then nothing below is present either.
matchedTaskIdStringId of the source the matched activity came from.
alignmentStringHow the recording was lined up with the steps. Must be one of Laps (one lap per step), Time (the steps laid end to end from the start of the recording), TotalsOnly (the recording has no samples, so there are no steps below).
plannedSecondsDoubleThe planned time in seconds.
doneSecondsDoubleThe recorded activity’s time in seconds.
plannedMetersDoubleThe planned distance in meters.
doneMetersDoubleThe recorded activity’s distance in meters.
targetedIntegerHow many steps have a target that could be judged.
onTargetIntegerHow many of those were on target and done in full.
stepsArray of Planned Workout Analysis StepEvery step in order, with repeats written out.
repeatsArray of Planned Workout Analysis RepeatOne entry per repeat whose steps have a target.
lastTimePlanned Workout Analysis Last Time

Planned Workout Analysis Step

JSON ItemData TypeDescription
intensityStringMust be one of Warmup, Active, Recovery, Rest, Cooldown.
durationStringWhat ends the step. Must be one of Time, Distance, LapButton, Calories, Repetitions.
durationValueDoubleSeconds, meters, calories or repetitions, as duration says.
targetStringMust be one of HeartRate, Power, Pace, Cadence. Absent for no target.
scaleStringMust be one of Absolute, PercentOfThreshold, Zone.
lowDoubleThe bottom of the target range as planned, on its scale.
highDoubleThe top of the target range as planned, on its scale.
noteStringA note shown with the step.
setIntegerFor a step inside a repeat, the position of that repeat in the workout’s steps, from 0. Absent otherwise.
repetitionIntegerFor a step inside a repeat, which repetition this is, from 1.
doneSecondsDoubleHow long the step lasted, in seconds.
doneMetersDoubleThe distance covered in the step, in meters.
verdictStringWhere the step’s average sits against its target. Must be one of OnTarget, Below, Above, NoTarget, NotDone. For pace, Below is slower. NoTarget is also used when a target could not be resolved, for example a percentage of a threshold the User has not set.
onTargetBooleanWhether the step was on target and done in full.
targetLowDoubleThe bottom of the target range in absolute units (beats per minute, watts, meters per second, revolutions per minute), widened by 3 percent.
targetHighDoubleThe top of the target range in absolute units, widened by 3 percent.
averageDoubleThe step’s average of the target’s measure, in the same units as targetLow.
inTargetDoubleThe share of the step’s time spent inside the target range, from 0 to 1.
averageHeartRateDoubleThe step’s average heart rate in beats per minute.
shortByDoubleHow much of the step was left undone, in seconds or meters as duration says, when it ended more than 15 percent early.

Planned Workout Analysis Repeat

JSON ItemData TypeDescription
setIntegerThe position of the repeat in the workout’s steps, from 0.
repetitionsIntegerHow many repetitions were planned.
targetStringThe measure compared. Must be one of HeartRate, Power, Pace, Cadence.
firstDoubleThe first repetition’s average of that measure.
lastDoubleThe last done repetition’s average of that measure.
fadeDoubleHow far power or pace fell from the first repetition to the last, as a share of the first. 0 for heart rate and cadence targets.
firstHeartRateDoubleThe first repetition’s average heart rate.
lastHeartRateDoubleThe last done repetition’s average heart rate.
driftDoubleThe change in average heart rate from the first repetition to the last, in beats per minute.

Planned Workout Analysis Last Time

JSON ItemData TypeDescription
workoutIdStringId of that planned workout.
dateStringIts day, as YYYY-MM-DD.
matchedItemIdStringId of the activity it matched.
matchedTaskIdStringId of the source that activity came from.
alignmentStringMust be one of Laps, Time, TotalsOnly.
targetedIntegerHow many steps had a target that could be judged.
onTargetIntegerHow many of those were on target and done in full.
doneSecondsDoubleThe activity’s time in seconds.
fadeDoubleThe first repeat’s fade, when it has one.