> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/planned-workouts-api/athlete-parameters.md).

# 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)

```json
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)

```json
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)

```json
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

```json
// 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tryterra.co/planned-workouts-api/athlete-parameters.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.