Core Concepts

⚠️ Pre-Release / Under Construction

This page is currently under active development and is provided in a pre-release state.

Content may be incomplete, outdated, or inaccurate, and details may changewithout notice as the implementation evolves.

Please use this documentation for early reference only, and avoid relying on it for production-critical decisions until the page is marked as stable.

Workout Structure

A workout template is a hierarchy of blocks and steps:

WorkoutTemplate
├── name: "FTP Intervals"
├── sport: "cycling"
├── environment: "outdoor" (optional — indoor, outdoor, pool)
├── description: "Build threshold power"
├── pool_length_meters: null (only for swimming)
│
└── step_blocks: [
      StepBlock {
        completion_condition: { type: "reps", value: 4 }  ← Repeat 4 times
        steps: [
          WorkoutStep { ... },  ← Do this
          WorkoutStep { ... }   ← Then this
        ]
      }
    ]

Step Blocks

A step block groups one or more steps that execute together. The block's completion_condition controls repetition:

Block Completion	Behavior
{ "type": "reps", "value": 4 }	Repeat all steps 4 times
{ "type": "time", "value": 1200 }	Repeat until 20 minutes total
{ "type": "distance", "value": 5000 }	Repeat until 5km total
{ "type": "open" } or omitted	Execute once (no repeat)

Example: 4x400m Intervals

{
  "step_blocks": [{
    "completion_condition": { "type": "reps", "value": 4 },
    "steps": [
      {
        "completion_condition": { "type": "distance", "value": 400 },
        "intensity_type": "active"
      },
      {
        "completion_condition": { "type": "distance", "value": 200 },
        "intensity_type": "rest"
      }
    ]
  }]
}

This creates: 400m fast → 200m easy → 400m fast → 200m easy → 400m fast → 200m easy → 400m fast → 200m easy

Workout Steps

Each step defines:

Field	Required	Description
completion_condition	Yes	When this step ends
intensity_type	Yes	How hard (warmup/active/rest/cooldown)
intensity_targets	No	Target metrics (HR, power, pace, etc.)
notes	No	Text shown to athlete
strength	No	Exercise details for strength training
swimming	No	Stroke/equipment for swimming

Completion Conditions

How a step (or block) ends:

Type	Value	Description
time	Seconds	End after duration (e.g., 300 = 5 minutes)
distance	Meters	End after distance (e.g., 1000 = 1km)
reps	Count	End after N repetitions
calories	kcal	End after calories burned
open	—	Manual end (lap button)
hr_less_than	BPM	End when HR drops below
hr_greater_than	BPM	End when HR rises above
power_less_than	Watts	End when power drops below
power_greater_than	Watts	End when power rises above

Example: Recovery Until HR Drops

{
  "completion_condition": {
    "type": "hr_less_than",
    "value": 120
  },
  "intensity_type": "rest"
}

Intensity Types

Type	Display	Use For
warmup	Warmup	Gradual start
active	Work / Interval	Main effort
rest	Rest	Full stop between intervals
recovery	Recovery	Easy effort between intervals
cooldown	Cooldown	Gradual end

Intensity Targets

Targets define the goal metric for a step. You can have multiple targets per step (provider-dependent).

Target Types

Absolute Targets:

Target Type	Value Unit	Example	Provider Support
heart_rate	BPM	150-160 BPM	All providers
power	Watts	250-280W	All except Huawei
speed	m/s	4.0-4.5 m/s	All providers
pace	sec/km	270-300 sec/km (4:30-5:00/km)	All providers
cadence	rpm or spm	170-180 spm	All providers
rpe	1-10	7-8 RPE	Wahoo, TrainingPeaks only

Percentage Targets (require athlete parameters at scheduling):

Target Type	Requires	Example
heart_rate_max_percentage	max_heart_rate	80-85% of max HR
heart_rate_threshold_percentage	threshold_heart_rate	95-100% of threshold
power_percentage	ftp	90-95% of FTP
speed_percentage	threshold_speed	85-90% of threshold pace

Zone Targets (device-configured zones):

Target Type	Value	Provider Support
heart_rate_zone	1-5	All providers (Garmin native, others convert to BPM or %). Uses threshold HR (COROS, Zepp) or max HR (others) as baseline
power_zone	1-7	All except Huawei (Garmin native, others convert to % FTP or watts)

Target Value Formats

Targets support single values or ranges:

// Range (recommended)
{
  "target_type": "power_percentage",
  "value_low": 90,
  "value_high": 95
}

// Single value (Terra expands to ±5% range automatically, except RPE which stays as a point value)
{
  "target_type": "heart_rate",
  "value": 155
}

Sport Types

Sport	Description	Provider Support
running	Running	All providers
cycling	Cycling	All except Huawei
swimming	Swimming	Garmin, COROS, Suunto, TrainingPeaks, Zepp, Apple
strength	Weight training	Garmin, COROS, Suunto, TrainingPeaks, Apple, Hevy
rowing	Rowing	Garmin, Apple
yoga	Yoga	Garmin, Apple
pilates	Pilates	Garmin only
cardio	General cardio	Garmin only
trail_running	Trail running	Garmin, COROS, Wahoo, Suunto, Zepp
mountain_biking	Mountain biking	Garmin, Wahoo, Suunto, TrainingPeaks
backcountry_skiing	Backcountry / ski touring	Garmin, Suunto

Unsupported sport types are coerced to the provider's default (usually running) with a coercion warning. See Provider Compatibility for details.

Environment (Optional)

Use the environment field to distinguish indoor/outdoor variants:

Environment	Description
indoor	Indoor (treadmill, stationary bike, etc.)
outdoor	Outdoor
pool	Pool swimming

If omitted, the provider uses its default. Examples:

{ "sport": "running", "environment": "indoor" }    // Treadmill
{ "sport": "cycling", "environment": "indoor" }    // Stationary bike
{ "sport": "swimming", "environment": "pool" }     // Lap swimming
{ "sport": "swimming", "environment": "outdoor" }  // Open water swimming
{ "sport": "running" }                              // Default (outdoor)

Complete Example

A 30-minute cycling workout with warmup, FTP intervals, and cooldown:

{
  "name": "30min FTP Builder",
  "sport": "cycling",
  "description": "4x4min @ 95-100% FTP with 2min recovery",
  "step_blocks": [
    {
      "steps": [{
        "completion_condition": { "type": "time", "value": 300 },
        "intensity_type": "warmup",
        "intensity_targets": [{
          "target_type": "power_percentage",
          "value_low": 50,
          "value_high": 60
        }]
      }]
    },
    {
      "completion_condition": { "type": "reps", "value": 4 },
      "steps": [
        {
          "completion_condition": { "type": "time", "value": 240 },
          "intensity_type": "active",
          "intensity_targets": [{
            "target_type": "power_percentage",
            "value_low": 95,
            "value_high": 100
          }]
        },
        {
          "completion_condition": { "type": "time", "value": 120 },
          "intensity_type": "rest",
          "intensity_targets": [{
            "target_type": "power_percentage",
            "value_low": 40,
            "value_high": 50
          }]
        }
      ]
    },
    {
      "steps": [{
        "completion_condition": { "type": "time", "value": 300 },
        "intensity_type": "cooldown",
        "intensity_targets": [{
          "target_type": "power_percentage",
          "value_low": 40,
          "value_high": 50
        }]
      }]
    }
  ]
}

Validation Rules

Templates are validated when created. Key rules:

Field	Requirement
name	Required, non-empty
sport	Required, must be a valid sport type
step_blocks	At least one block required
Each block	At least one step required
Each step	intensity_type required (warmup, active, rest, recovery, cooldown)
Each step	completion_condition defaults to open if omitted
pool_length_meters	Only allowed for swimming workouts
value_low / value_high	Cannot use both value and value_low/value_high on the same target
Range targets	value_low must be strictly less than value_high
Athlete metrics	All values must be positive if provided (ftp, max_heart_rate, threshold_heart_rate, threshold_speed, pool_length_meters)
planned_date	Format: YYYY-MM-DD

Target value sanity checks (warnings, not hard rejections for most):

Target Type	Valid Range
Heart rate (BPM)	30–250
Power (watts)	1–2000
Speed (m/s)	0–15
Pace (sec/km)	1–7200
Cadence (rpm/spm)	1–300
RPE	1–10
Percentage targets	0–200%