> 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/unified-api/managing-user-health-data/write-data.md). # Writing data Terra allows you to write data back to a user's account, wherever supported by the respective [Provider](https://app.gitbook.com/s/eJJpVMsUARUJq9lYmL6t/unified-api/core-concepts#source-provider-integration). ## Writing Planned Workouts ### Overview Writing planned workouts allows you to create a workout plan for the user (such as those [commonly used with Zwift](https://whatsonzwift.com/workouts)) This will typically look like the following example:

Example workout from https://whatsonzwift.com/workouts/baby-on-board

Planned workouts consist of a **series of steps**. Each step has: * **Completion criteria** (called **duration** for all intents and purposes). For example: * distance (keep going until you cover 500m), * energy expenditure (keep going until you burn 200 kcal) * heart rate threshold (keep going until your heart rate reaches above 150 bpm) * etc.. * One or more **targets** to be maintained * heart rate (maintain heart rate between certain bounds) * speed (maintain speed between certain bounds) * grade (inclination above a certain threshold) * etc... * An associated **intensity** label * Warmup * Active * Cooldown * etc.. * An **exercise type** * Running * Cycling * Deadlifting * etc... * A series of sub-steps These modalities allow any workout to be described in a series of defined steps for each of its segments. Once written, a planned workout will be available in the user's library of workouts on the respective platform, and the user will then be able to follow the workout step by step on their wearable device ## Writing Planned Workouts ### Supported providers Currently supported [providers](https://app.gitbook.com/s/eJJpVMsUARUJq9lYmL6t/unified-api/supported-integrations) are: * Garmin * Hammerhead * Coros * TodaysPlan See the [https://app.gitbook.com/s/eJJpVMsUARUJq9lYmL6t/unified-api/supported-integrations](https://app.gitbook.com/s/eJJpVMsUARUJq9lYmL6t/unified-api/supported-integrations "mention") page for a full list of supported data types per [Provider](https://app.gitbook.com/s/eJJpVMsUARUJq9lYmL6t/unified-api/core-concepts#source-provider-integration) ### Usage In order to write a planned workout to the user's device, you may use the following endpoint {% openapi src="" path="/plannedWorkout" method="post" %} {% endopenapi %} The response will include `log_ids` which will be a list of the identifiers for the uploaded workout plans. You may use those identifiers to identify the workout plan later on in the [https://app.gitbook.com/s/eJJpVMsUARUJq9lYmL6t/unified-api/readme#get-plannedworkout](https://app.gitbook.com/s/eJJpVMsUARUJq9lYmL6t/unified-api/readme#get-plannedworkout "mention")endpoint, or to delete them using the [https://app.gitbook.com/s/eJJpVMsUARUJq9lYmL6t/unified-api/readme#delete-plannedworkout](https://app.gitbook.com/s/eJJpVMsUARUJq9lYmL6t/unified-api/readme#delete-plannedworkout "mention") ### Enum values The `steps`, `durations`, and `targets` objects use integer enums. The accepted values are below. Not every provider supports every value. Garmin accepts `target_type` values 0, 1, 2, 3, 4, 8, 11, 13, 14 and 15 only; a step whose targets fall entirely outside that set is rejected. **Step `type`** | Value | Meaning | | ----- | ----------- | | 0 | Step | | 1 | Repeat step | **Step `intensity`** | Value | Meaning | | ----- | --------- | | 0 | Rest | | 1 | Warm up | | 2 | Cool down | | 3 | Recovery | | 4 | Interval | | 5 | Active | **`duration_type`** | Value | Meaning | | ----- | ----------------- | | 0 | Time | | 1 | Distance (metres) | | 2 | Heart rate below | | 3 | Heart rate above | | 4 | Calories | | 5 | Open | | 6 | Power below | | 7 | Power above | | 8 | Repetition time | | 9 | Reps | | 10 | Fixed rest | | 11 | Time at valid CdA | | 12 | Steps | **`target_type`** | Value | Meaning | | ----- | ---------------------- | | 0 | Speed | | 1 | Heart rate | | 2 | Open | | 3 | Cadence | | 4 | Power | | 5 | Grade | | 6 | Resistance | | 7 | Power lap | | 8 | Swim stroke | | 9 | Speed lap | | 10 | Heart rate lap | | 11 | Pace | | 12 | Heart rate threshold % | | 13 | Heart rate max % | | 14 | Speed % | | 15 | Power % | | 16 | Repetition | | 17 | TSS | | 18 | IF | | 19 | RPE | ### Examples #### Aerobic fitness test The aerobic fitness test begins with a 5 minute warm-up. After warming up, the intensity will ramp up over the duration of 5 minutes, reaching a 91% max HR intensity. Once you are done with the all out effort, you will spend 2 minutes in a recovery step, before spending 5 minutes cooling down {% tabs %} {% tab title="General" %} ```json5 { "data": [ { "steps": [ { "type": 1, "order": 0, "description": "Warm Up BASIC", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Warm Up", "durations": [ { "duration_type": 0, "seconds": 300 } ], "targets": [ { "target_type": 13, "hr_percentage_high": 70.0, "hr_percentage_low": 60.0, "hr_percentage": null } ] } ] }, { "type": 1, "order": 0, "description": "Warm Up RAMP_UP", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Ramp Up 1", "durations": [ { "duration_type": 0, "seconds": 60 } ], "targets": [ { "target_type": 12, "hr_percentage_high": 79.5, "hr_percentage_low": 79.5, "hr_percentage": 79.5 }, { "target_type": 13, "hr_percentage_high": 70.0, "hr_percentage_low": 70.0, "hr_percentage": 70.0 }, { "target_type": 15, "power_percentage_high": 65, "power_percentage_low": 65, "power_percentage": 65 }, { "target_type": 3, "cadence_high": 95.0, "cadence_low": 85.0, "cadence": null } ] }, { "type": 0, "order": 0, "intensity": 5, "description": "Ramp Up 2", "durations": [ { "duration_type": 0, "seconds": 60 } ], "targets": [ { "target_type": 12, "hr_percentage_high": 85.8, "hr_percentage_low": 85.8, "hr_percentage": 85.8 }, { "target_type": 13, "hr_percentage_high": 76.0, "hr_percentage_low": 76.0, "hr_percentage": 76.0 }, { "target_type": 15, "power_percentage_high": 75, "power_percentage_low": 75, "power_percentage": 75 }, { "target_type": 3, "cadence_high": 95.0, "cadence_low": 85.0, "cadence": null } ] }, { "type": 0, "order": 0, "intensity": 5, "description": "Ramp Up 3", "durations": [ { "duration_type": 0, "seconds": 60 } ], "targets": [ { "target_type": 12, "hr_percentage_high": 91.6, "hr_percentage_low": 91.6, "hr_percentage": 91.6 }, { "target_type": 13, "hr_percentage_high": 82.0, "hr_percentage_low": 82.0, "hr_percentage": 82.0 }, { "target_type": 15, "power_percentage_high": 85, "power_percentage_low": 85, "power_percentage": 85 }, { "target_type": 3, "cadence_high": 95.0, "cadence_low": 85.0, "cadence": null } ] }, { "type": 0, "order": 0, "intensity": 5, "description": "Ramp Up 4", "durations": [ { "duration_type": 0, "seconds": 60 } ], "targets": [ { "target_type": 12, "hr_percentage_high": 96.7, "hr_percentage_low": 96.7, "hr_percentage": 96.7 }, { "target_type": 13, "hr_percentage_high": 87.0, "hr_percentage_low": 87.0, "hr_percentage": 87.0 }, { "target_type": 15, "power_percentage_high": 95, "power_percentage_low": 95, "power_percentage": 95 }, { "target_type": 3, "cadence_high": 95.0, "cadence_low": 85.0, "cadence": null } ] }, { "type": 0, "order": 0, "intensity": 5, "description": "Ramp Up 5", "durations": [ { "duration_type": 0, "seconds": 60 } ], "targets": [ { "target_type": 12, "hr_percentage_high": 101.4, "hr_percentage_low": 101.4, "hr_percentage": 101.4 }, { "target_type": 13, "hr_percentage_high": 91.0, "hr_percentage_low": 91.0, "hr_percentage": 91.0 }, { "target_type": 15, "power_percentage_high": 105, "power_percentage_low": 105, "power_percentage": 105 }, { "target_type": 3, "cadence_high": 95.0, "cadence_low": 85.0, "cadence": null } ] } ] }, { "type": 1, "order": 0, "description": "Recovery BASIC", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Recovery", "durations": [ { "duration_type": 0, "seconds": 120 } ], "targets": [ { "target_type": 12, "hr_percentage_high": 76.0, "hr_percentage_low": 69.0, "hr_percentage": null }, { "target_type": 13, "hr_percentage_high": 67.0, "hr_percentage_low": 60.0, "hr_percentage": null }, { "target_type": 15, "power_percentage_high": 60, "power_percentage_low": 50, "power_percentage": null } ] } ] }, { "type": 1, "order": 0, "description": "Main Session BASIC", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Sprint", "durations": [ { "duration_type": 0, "seconds": 8 } ], "targets": [ { "target_type": 12, "hr_percentage_high": null, "hr_percentage_low": 106.0, "hr_percentage": null }, { "target_type": 13, "hr_percentage_high": null, "hr_percentage_low": 98.5, "hr_percentage": null }, { "target_type": 15, "power_percentage_high": null, "power_percentage_low": 200, "power_percentage": null }, { "target_type": 3, "cadence_high": 120.0, "cadence_low": 100.0, "cadence": null } ] } ] }, { "type": 1, "order": 0, "description": "Recovery BASIC", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Recovery", "durations": [ { "duration_type": 0, "seconds": 180 } ], "targets": [ { "target_type": 12, "hr_percentage_high": 73.0, "hr_percentage_low": 65.0, "hr_percentage": null }, { "target_type": 13, "hr_percentage_high": 63.0, "hr_percentage_low": 57.0, "hr_percentage": null }, { "target_type": 15, "power_percentage_high": 55, "power_percentage_low": 45, "power_percentage": null } ] } ] }, { "type": 1, "order": 0, "description": "Main Session BASIC", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Sprint", "durations": [ { "duration_type": 0, "seconds": 8 } ], "targets": [ { "target_type": 12, "hr_percentage_high": null, "hr_percentage_low": 106.0, "hr_percentage": null }, { "target_type": 13, "hr_percentage_high": null, "hr_percentage_low": 98.5, "hr_percentage": null }, { "target_type": 15, "power_percentage_high": null, "power_percentage_low": 200, "power_percentage": null }, { "target_type": 3, "cadence_high": 120.0, "cadence_low": 100.0, "cadence": null } ] } ] }, { "type": 1, "order": 0, "description": "Recovery BASIC", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Recovery", "durations": [ { "duration_type": 0, "seconds": 300 } ], "targets": [ { "target_type": 12, "hr_percentage_high": 73.0, "hr_percentage_low": 65.0, "hr_percentage": null }, { "target_type": 13, "hr_percentage_high": 63.0, "hr_percentage_low": 57.0, "hr_percentage": null }, { "target_type": 15, "power_percentage_high": 55, "power_percentage_low": 45, "power_percentage": null } ] } ] }, { "type": 1, "order": 0, "description": "Main Session BASIC", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Aerobic Test", "durations": [ { "duration_type": 0, "seconds": 480 } ], "targets": [ { "target_type": 12, "hr_percentage_high": null, "hr_percentage_low": 106.0, "hr_percentage": null }, { "target_type": 13, "hr_percentage_high": null, "hr_percentage_low": 98.5, "hr_percentage": null }, { "target_type": 15, "power_percentage_high": null, "power_percentage_low": 98, "power_percentage": null }, { "target_type": 3, "cadence_high": 110.0, "cadence_low": 90.0, "cadence": null } ] } ] }, { "type": 1, "order": 0, "description": "Recovery BASIC", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Recovery", "durations": [ { "duration_type": 0, "seconds": 120 } ], "targets": [ { "target_type": 12, "hr_percentage_high": 73.0, "hr_percentage_low": 65.0, "hr_percentage": null }, { "target_type": 13, "hr_percentage_high": 63.0, "hr_percentage_low": 57.0, "hr_percentage": null }, { "target_type": 15, "power_percentage_high": 55, "power_percentage_low": 45, "power_percentage": null } ] } ] }, { "type": 1, "order": 0, "description": "Cool Down BASIC", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Cool Down", "durations": [ { "duration_type": 0, "seconds": 300 } ], "targets": [ { "target_type": 12, "hr_percentage_high": 73.0, "hr_percentage_low": 69.0, "hr_percentage": null }, { "target_type": 13, "hr_percentage_high": 63.0, "hr_percentage_low": 60.0, "hr_percentage": null }, { "target_type": 15, "power_percentage_high": 55, "power_percentage_low": 50, "power_percentage": null } ] } ] } ], "metadata": { "type": 1, "name": "Aerobic Fitness Test", "description": "The aerobic fitness test begins with a warm-up. After warming up, you will be required to complete two maximal sprints. Once you are done with the sprints, you will have to undergo a 9-minute all-out test. During the test, it is important to pace yourself and give your best effort, sustaining it for the entire duration of 8 minutes.", "provider": "COROS", "planned_date": "2025-01-29", "estimated_duration_seconds": 2100 } } ] } ``` {% endtab %} {% tab title="Adapted to Garmin" %} ```json { "data": [ { "steps": [ { "type": 1, "order": 0, "description": "Warm Up BASIC", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Warm Up", "durations": [ { "duration_type": 0, "seconds": 300 } ], "targets": [ { "target_type": 13, "hr_percentage_high": 70, "hr_percentage_low": 60, "hr_percentage": null } ] } ] }, { "type": 1, "order": 0, "description": "Warm Up RAMP_UP", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Ramp Up 1", "durations": [ { "duration_type": 0, "seconds": 60 } ], "targets": [ { "target_type": 13, "hr_percentage_high": 70, "hr_percentage_low": 70, "hr_percentage": 70 } ] }, { "type": 0, "order": 0, "intensity": 5, "description": "Ramp Up 2", "durations": [ { "duration_type": 0, "seconds": 60 } ], "targets": [ { "target_type": 13, "hr_percentage_high": 76, "hr_percentage_low": 76, "hr_percentage": 76 } ] }, { "type": 0, "order": 0, "intensity": 5, "description": "Ramp Up 3", "durations": [ { "duration_type": 0, "seconds": 60 } ], "targets": [ { "target_type": 13, "hr_percentage_high": 82, "hr_percentage_low": 82, "hr_percentage": 82 } ] }, { "type": 0, "order": 0, "intensity": 5, "description": "Ramp Up 4", "durations": [ { "duration_type": 0, "seconds": 60 } ], "targets": [ { "target_type": 13, "hr_percentage_high": 87, "hr_percentage_low": 87, "hr_percentage": 87 } ] } ] }, { "type": 1, "order": 0, "description": "Recovery BASIC", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Recovery", "durations": [ { "duration_type": 0, "seconds": 120 } ], "targets": [ { "target_type": 13, "hr_percentage_high": 67, "hr_percentage_low": 60, "hr_percentage": null } ] } ] }, { "type": 1, "order": 0, "description": "Main Session BASIC", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Sprint", "durations": [ { "duration_type": 0, "seconds": 8 } ], "targets": [ { "target_type": 13, "hr_percentage_high": null, "hr_percentage_low": 98.5, "hr_percentage": null } ] } ] }, { "type": 1, "order": 0, "description": "Recovery BASIC", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Recovery", "durations": [ { "duration_type": 0, "seconds": 180 } ], "targets": [ { "target_type": 13, "hr_percentage_high": 63, "hr_percentage_low": 57, "hr_percentage": null } ] } ] }, { "type": 1, "order": 0, "description": "Main Session BASIC", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Sprint", "durations": [ { "duration_type": 0, "seconds": 8 } ], "targets": [ { "target_type": 13, "hr_percentage_high": null, "hr_percentage_low": 98.5, "hr_percentage": null } ] } ] }, { "type": 1, "order": 0, "description": "Recovery BASIC", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Recovery", "durations": [ { "duration_type": 0, "seconds": 300 } ], "targets": [ { "target_type": 13, "hr_percentage_high": 63, "hr_percentage_low": 57, "hr_percentage": null } ] } ] }, { "type": 1, "order": 0, "description": "Main Session BASIC", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Aerobic Test", "durations": [ { "duration_type": 0, "seconds": 480 } ], "targets": [ { "target_type": 13, "hr_percentage_high": null, "hr_percentage_low": 98.5, "hr_percentage": null } ] } ] }, { "type": 1, "order": 0, "description": "Recovery BASIC", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Recovery", "durations": [ { "duration_type": 0, "seconds": 120 } ], "targets": [ { "target_type": 13, "hr_percentage_high": 63, "hr_percentage_low": 57, "hr_percentage": null } ] } ] }, { "type": 1, "order": 0, "description": "Cool Down BASIC", "durations": [ { "duration_type": 9, "reps": 1 } ], "steps": [ { "type": 0, "order": 0, "intensity": 5, "description": "Cool Down", "durations": [ { "duration_type": 0, "seconds": 300 } ], "targets": [ { "target_type": 13, "hr_percentage_high": 73, "hr_percentage_low": 69, "hr_percentage": null } ] } ] } ], "metadata": { "type": 1, "name": "Aerobic Fitness Test", "description": "The aerobic fitness test begins with a warm-up. After warming up, you will be required to complete two maximal sprints. Once you are done with the sprints, you will have to undergo a 9-minute all-out test. During the test, it is important to pace yourself and give your best effort, sustaining it for the entire duration of 8 minutes.", "provider": "GARMIN", "planned_date": "2025-01-29", "estimated_duration_seconds": 2100 } } ] } ``` {% endtab %} {% endtabs %}