Athlete Parameters

⚠️ 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.

Overview

Athlete parameters are provided when scheduling a workout to a specific user. They convert percentage-based targets to absolute values that the device can display.

Key concept: Templates are generic. Athlete parameters are applied at scheduling time.

Parameters

Parameter	Unit	Used By
max_heart_rate	BPM	heart_rate_max_percentage targets
threshold_heart_rate	BPM	heart_rate_threshold_percentage targets
ftp	Watts	power_percentage targets
threshold_speed	m/s	speed_percentage targets
pool_length_meters	Meters	Swimming workouts (overrides template)

When Parameters Are Required

Target Type	Required Parameter	What Happens Without It
heart_rate_max_percentage	max_heart_rate	Coercion warning, may use provider default
heart_rate_threshold_percentage	threshold_heart_rate	Coercion warning, may use provider default
power_percentage	ftp	Coercion warning, may use provider default
speed_percentage	threshold_speed	Coercion warning, may use provider default

Example: One Template, Two Athletes

Create Template (once)

POST /workouts
{
  "name": "Threshold Intervals",
  "sport": "cycling",
  "step_blocks": [{
    "completion_condition": { "type": "reps", "value": 3 },
    "steps": [{
      "completion_condition": { "type": "time", "value": 600 },
      "intensity_type": "active",
      "intensity_targets": [{
        "target_type": "power_percentage",
        "value_low": 95,
        "value_high": 100
      }]
    }]
  }]
}

Response: { "status": "success", "workout_id": "123" }

Schedule to Athlete A (FTP: 200W)

POST /workouts/123/plan?user_id=athlete_a
{
  "planned_date": "2026-02-10",
  "ftp": 200
}

Result on device: 3x10min @ 190-200W

Schedule to Athlete B (FTP: 300W)

POST /workouts/123/plan?user_id=athlete_b
{
  "planned_date": "2026-02-10",
  "ftp": 300
}

Result on device: 3x10min @ 285-300W

Conversion Formulas

Absolute HR = Percentage × max_heart_rate / 100
Absolute Power = Percentage × ftp / 100
Absolute Speed = Percentage × threshold_speed / 100

Example Conversion

Template target: heart_rate_max_percentage @ 80-85% Athlete's max_heart_rate: 190 BPM

Low:  80% × 190 = 152 BPM
High: 85% × 190 = 162 BPM

Device shows: 152-162 BPM

Heart Rate Zones vs Percentages

Approach	When to Use
heart_rate_zone (1-5)	Device has preconfigured zones
heart_rate_max_percentage	You know user's max HR
heart_rate_threshold_percentage	You know user's threshold HR
heart_rate (absolute BPM)	You've pre-calculated the values

Pool Length

For swimming workouts, pool_length_meters can be set in either:

1. Template - Default pool length for the workout

2. Schedule request - Override for specific user/pool

// Template with default pool length
POST /workouts
{
  "name": "Swim Intervals",
  "sport": "swimming",
  "environment": "pool",
  "pool_length_meters": 25,
  "step_blocks": [...]
}

// Override for 50m pool
POST /workouts/456/plan?user_id=X
{
  "planned_date": "2026-02-10",
  "pool_length_meters": 50
}

Best Practices

1. Always provide required parameters - Prevents coercion warnings

2. Store athlete parameters in your app - Fetch max HR, FTP from user profile

3. Use percentage targets for personalization - Same template works for all fitness levels

4. Use absolute targets for fixed workouts - When everyone should hit the same number