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.
Example request
curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/planned/"| Query Parameter Name | Description |
|---|---|
| start | The first day, as YYYY-MM-DD in the user’s time zone. Default is today. |
| end | The 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.
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.
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.
Example request
curl -H "Authorization: Bearer AccessToken" "https://api.fitnesssyncer.com/api/planned/id/file"| Query Parameter Name | Description |
|---|---|
| format | One 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.
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.
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.
Fields
| JSON Item | Data Type | Description |
|---|---|---|
| status | String | |
| removedEverywhere | Boolean |
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.
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.
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.
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.
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.
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.
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 Item | Data Type | Description |
|---|---|---|
| id | String | Unique id of the planned workout. Read-only. |
| date | String | The day it is planned for, as YYYY-MM-DD. |
| minuteOfDay | Integer | Minutes after midnight when it is planned for a time of day. Absent for a workout planned for the day, which is most of them. |
| sport | String | The kind of activity, as the canonical activity name (Running, Cycling, Swimming, Walking, Hiking, Rowing, Strength, Yoga, Elliptical, Cross Training or Other). |
| title | String | The workout’s name. Truncated at 120 characters. |
| description | String | Notes for the athlete. Truncated at 4000 characters. |
| steps | Array of Planned Workout Step | The structure of the workout, in order. May be empty for a workout described only by its planned time or distance. |
| stepsText | String | The 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. |
| plannedSeconds | Double | Planned 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. |
| enteredSeconds | Double | The 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. |
| deliveryWarnings | Array of String | Only 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. |
| plannedMeters | Double | Planned distance in meters, read back the same way as plannedSeconds. |
| source | String | Where the workout came from. Must be one of Athlete, Coach, File, Provider. Read-only. |
| byCoach | Boolean | Whether 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. |
| skipped | Boolean | Whether the User marked it as skipped. |
| skipReason | String | Why it was skipped, if the User said. |
| status | String | How 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. |
| compliance | Double | The 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. |
| matchedItemId | String | The 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. |
| matchedTaskId | String | The task id of that Activity, which with matchedItemId identifies it. Read-only. |
| modified | Long | When it was last changed, in milliseconds since the epoch. Read-only. |
Planned Workout Step
| JSON Item | Data Type | Description |
|---|---|---|
| repeat | Integer | For a repeat, how many times its steps are done. |
| steps | Array of Planned Workout Step | For a repeat, the steps repeated. They are steps, never further repeats. |
| intensity | String | Must be one of Warmup, Active, Recovery, Rest, Cooldown. |
| duration | String | What ends the step. Must be one of Time, Distance, LapButton, Calories, Repetitions. |
| durationValue | Double | Seconds, meters, calories or repetitions, as duration says. Absent for LapButton. |
| target | String | What the step asks the athlete to hold. Must be one of HeartRate, Power, Pace, Cadence. Absent for no target. |
| scale | String | How 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. |
| low | Double | The bottom of the target range, in beats per minute, watts, meters per second (for pace) or revolutions per minute when absolute. |
| high | Double | The top of the target range, in the same units as low. |
| note | String | A note shown with the step. For a strength set naming an exercise the catalog does not have, the exercise is written here. |
| exercise | String | For 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. |
| weight | Double | For a strength set, the weight to lift in kilograms. Absent for none. |
Planned Workout List
| JSON Item | Data Type | Description |
|---|---|---|
| start | String | The first day returned, as YYYY-MM-DD. |
| end | String | The last day returned, as YYYY-MM-DD. |
| items | Array of Planned Workout | The planned workouts, earliest first. |
Planned Workout Library
| JSON Item | Data Type | Description |
|---|---|---|
| items | Array of Planned Workout Library Item | Newest first. |
Planned Workout Library Item
| JSON Item | Data Type | Description |
|---|---|---|
| id | String | Id to apply it by. |
| kind | String | Must be one of Workout, Plan. |
| name | String | The name it was saved under. |
| days | Integer | How many days it spans, at least one. |
| workouts | Integer | How many workouts it holds. |
| sport | String | The sport of its first workout. |
Planned Workout Library Save
| JSON Item | Data Type | Description |
|---|---|---|
| workoutId | String | Id of the planned workout to save. When given, the others are ignored. |
| start | String | The first day of the plan, as YYYY-MM-DD. |
| weeks | Integer | How many weeks from start the plan holds, from 1 to 16. |
| name | String | The plan’s name. |
Planned Workout Generate
| JSON Item | Data Type | Description |
|---|---|---|
| sport | String | Must be one of Running, Cycling, Swimming. Anything else is read as Running. |
| start | String | The first day of the plan, as YYYY-MM-DD. Leave it out, or give a day already past, to start today. |
| race | String | Id 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. |
| date | String | The 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. |
| weeks | Integer | How many weeks a block with no race or date holds, from 1 to 16. 8 when left out. |
| trainingDays | Array of String | The 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. |
| longDay | String | The day of the week for the long session, written as in trainingDays. The last training day of the week when left out. |
| experience | String | Must 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 Item | Data Type | Description |
|---|---|---|
| item | Planned Workout Library Item | |
| start | String | The 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. |
| trainingDays | Array of String | The days of the week the plan uses, to apply it with, so every workout lands on the day shown. |
| experience | String | The band the plan was written for. Must be one of Beginner, Intermediate, Advanced. |
| firstWeekMinutes | Integer | Minutes of training in the plan’s first full week. |
| summary | String | A sentence in the User’s language saying the draft is in the library and what its first week was based on. |
| warnings | Array of Planned Workout Generate Warning | What the User should know about the plan before applying it. |
| workouts | Array of Planned Workout Generated Day | Each workout of the plan on the day it falls on when applied as returned. |
Planned Workout Generate Warning
| JSON Item | Data Type | Description |
|---|---|---|
| code | String | Must be one of NoHistory, ShortRunUp, LongRunUp, TooManyDays, NoThreshold, SwimByEffort, HistoryNotShared. More may be added. |
| message | String | The warning in the User’s language. |
Planned Workout Generated Day
| JSON Item | Data Type | Description |
|---|---|---|
| date | String | The day it falls on, as YYYY-MM-DD. |
| sport | String | The sport it is planned as. |
| title | String | Its title, in the User’s language. |
| description | String | Its training phase and week of the plan, in the User’s language. |
| minutes | Integer | How long its steps take. |
Planned Workout Apply
| JSON Item | Data Type | Description |
|---|---|---|
| date | String | The day of its first workout, as YYYY-MM-DD. |
| trainingDays | Array of String | The 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 Item | Data Type | Description |
|---|---|---|
| workoutId | String | Id of the planned workout. |
| status | String | Where the workout stands. Must be one of Planned, Completed, Partial, Missed, Skipped. |
| matchedItemId | String | Id of the activity the workout matched. Absent when it matched none, and then nothing below is present either. |
| matchedTaskId | String | Id of the source the matched activity came from. |
| alignment | String | How 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). |
| plannedSeconds | Double | The planned time in seconds. |
| doneSeconds | Double | The recorded activity’s time in seconds. |
| plannedMeters | Double | The planned distance in meters. |
| doneMeters | Double | The recorded activity’s distance in meters. |
| targeted | Integer | How many steps have a target that could be judged. |
| onTarget | Integer | How many of those were on target and done in full. |
| steps | Array of Planned Workout Analysis Step | Every step in order, with repeats written out. |
| repeats | Array of Planned Workout Analysis Repeat | One entry per repeat whose steps have a target. |
| lastTime | Planned Workout Analysis Last Time |
Planned Workout Analysis Step
| JSON Item | Data Type | Description |
|---|---|---|
| intensity | String | Must be one of Warmup, Active, Recovery, Rest, Cooldown. |
| duration | String | What ends the step. Must be one of Time, Distance, LapButton, Calories, Repetitions. |
| durationValue | Double | Seconds, meters, calories or repetitions, as duration says. |
| target | String | Must be one of HeartRate, Power, Pace, Cadence. Absent for no target. |
| scale | String | Must be one of Absolute, PercentOfThreshold, Zone. |
| low | Double | The bottom of the target range as planned, on its scale. |
| high | Double | The top of the target range as planned, on its scale. |
| note | String | A note shown with the step. |
| set | Integer | For a step inside a repeat, the position of that repeat in the workout’s steps, from 0. Absent otherwise. |
| repetition | Integer | For a step inside a repeat, which repetition this is, from 1. |
| doneSeconds | Double | How long the step lasted, in seconds. |
| doneMeters | Double | The distance covered in the step, in meters. |
| verdict | String | Where 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. |
| onTarget | Boolean | Whether the step was on target and done in full. |
| targetLow | Double | The bottom of the target range in absolute units (beats per minute, watts, meters per second, revolutions per minute), widened by 3 percent. |
| targetHigh | Double | The top of the target range in absolute units, widened by 3 percent. |
| average | Double | The step’s average of the target’s measure, in the same units as targetLow. |
| inTarget | Double | The share of the step’s time spent inside the target range, from 0 to 1. |
| averageHeartRate | Double | The step’s average heart rate in beats per minute. |
| shortBy | Double | How 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 Item | Data Type | Description |
|---|---|---|
| set | Integer | The position of the repeat in the workout’s steps, from 0. |
| repetitions | Integer | How many repetitions were planned. |
| target | String | The measure compared. Must be one of HeartRate, Power, Pace, Cadence. |
| first | Double | The first repetition’s average of that measure. |
| last | Double | The last done repetition’s average of that measure. |
| fade | Double | How 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. |
| firstHeartRate | Double | The first repetition’s average heart rate. |
| lastHeartRate | Double | The last done repetition’s average heart rate. |
| drift | Double | The change in average heart rate from the first repetition to the last, in beats per minute. |
Planned Workout Analysis Last Time
| JSON Item | Data Type | Description |
|---|---|---|
| workoutId | String | Id of that planned workout. |
| date | String | Its day, as YYYY-MM-DD. |
| matchedItemId | String | Id of the activity it matched. |
| matchedTaskId | String | Id of the source that activity came from. |
| alignment | String | Must be one of Laps, Time, TotalsOnly. |
| targeted | Integer | How many steps had a target that could be judged. |
| onTarget | Integer | How many of those were on target and done in full. |
| doneSeconds | Double | The activity’s time in seconds. |
| fade | Double | The first repeat’s fade, when it has one. |