> 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/reference/health-and-fitness-api/planned-workouts.md).

# Planned Workouts

Workout templates, and the planned workouts that put them on a user's calendar.

## List workout templates

> Returns every workout template stored for your developer account.

```json
{"openapi":"3.2.0","info":{"title":"Terra API","version":"2026.11.19"},"tags":[{"name":"PlannedWorkouts","summary":"Planned Workouts","description":"Workout templates, and the planned workouts that put them on a user's calendar."}],"servers":[{"url":"https://access.tryterra.co/api/v2"}],"security":[{"ApiKeyAuth":[],"DevID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key for authentication"},"DevID":{"type":"apiKey","in":"header","name":"dev-id","description":"Your developer ID for authentication and tracking"}},"schemas":{"WorkoutTemplate":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","description":"Name of the workout"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description of the workout"},"environment":{"anyOf":[{"$ref":"#/components/schemas/EnvironmentType"},{"type":"null"}]},"pool_length_meters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Pool length in meters, for swim workouts"},"step_blocks":{"type":"array","items":{"$ref":"#/components/schemas/StepBlock"}},"estimated_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated total duration in seconds"},"estimated_distance_meters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated total distance in meters"},"estimated_calories":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated calories burned"},"estimated_tss":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Planned training stress score (0-9999), where the provider or author supplies one. Forwarded to TrainingPeaks, which ignores it when any step target is not RPE and derives it from the structure instead."},"estimated_intensity_factor":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Planned intensity factor (0-5), where the provider or author supplies one. Forwarded to TrainingPeaks, which ignores it when any step target is not RPE and derives it from the structure instead."},"workout_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Terra identifier of the stored template. Set by Terra in responses; ignored on create."},"sport":{"$ref":"#/components/schemas/WorkoutSport"}},"required":["name","step_blocks","sport"],"description":"A reusable workout template, created once and planned onto user calendars"},"EnvironmentType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"indoor"},{"type":"string","const":"outdoor"},{"type":"string","const":"pool"}],"description":"Environment a workout takes place in"},"StepBlock":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"completion_condition":{"$ref":"#/components/schemas/CompletionCondition","description":"When this block completes (e.g. repeat count via reps)"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/WorkoutStep"}}},"required":["completion_condition","steps"],"description":"A block of steps, repeated until its completion condition is met"},"CompletionCondition":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"$ref":"#/components/schemas/CompletionConditionType"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Single value for the condition (e.g. seconds for time, meters for distance)"},"value_low":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lower bound when the condition is a range"},"value_high":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Upper bound when the condition is a range"}},"required":["type"],"description":"Condition that completes a step or repeats a step block"},"CompletionConditionType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"time"},{"type":"string","const":"distance"},{"type":"string","const":"hr"},{"type":"string","const":"calories"},{"type":"string","const":"open"},{"type":"string","const":"power"},{"type":"string","const":"reps"},{"type":"string","const":"hr_percentage"},{"type":"string","const":"power_percentage"},{"type":"string","const":"hr_less_than"},{"type":"string","const":"hr_greater_than"},{"type":"string","const":"hr_percentage_less_than"},{"type":"string","const":"hr_percentage_greater_than"},{"type":"string","const":"power_less_than"},{"type":"string","const":"power_greater_than"},{"type":"string","const":"power_percentage_less_than"},{"type":"string","const":"power_percentage_greater_than"}],"description":"How a step or block is considered complete"},"WorkoutStep":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"completion_condition":{"$ref":"#/components/schemas/CompletionCondition","description":"When this step completes"},"intensity_targets":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/IntensityTarget"}},{"type":"null"}],"description":"Intensity targets to hold during the step"},"intensity_type":{"$ref":"#/components/schemas/WorkoutStepIntensity"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Free-text coaching notes shown to the athlete"},"controls":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/StepControl"}},{"type":"null"}],"description":"Equipment controls applied during the step"},"strength":{"anyOf":[{"$ref":"#/components/schemas/StrengthData"},{"type":"null"}]},"swimming":{"anyOf":[{"$ref":"#/components/schemas/SwimStepData"},{"type":"null"}]}},"required":["completion_condition","intensity_type"],"description":"A single step within a step block"},"IntensityTarget":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"target_type":{"$ref":"#/components/schemas/WorkoutStepTargetType"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Single target value, in the unit for target_type"},"value_low":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lower bound of the target range, in the unit for target_type. For pace, the lower number is the faster pace"},"value_high":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Upper bound of the target range, in the unit for target_type"}},"required":["target_type"],"description":"Target intensity range for a step (e.g. heart-rate or power zone). The unit of value, value_low and value_high depends on target_type: heart_rate in BPM; power in watts; speed in metres per second; pace in seconds per kilometre for every sport, swimming included, so 4:30/km is 270, not 4.5, and 1:30 per 100 m is 900, not 90; cadence in rpm or steps per minute; rpe from 1 to 10; heart_rate_zone (1-5) and power_zone (1-7) as zone numbers; the *_percentage types in percent of the athlete parameter given when planning (max_heart_rate, threshold_heart_rate, ftp or threshold_speed)."},"WorkoutStepTargetType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"speed"},{"type":"string","const":"heart_rate"},{"type":"string","const":"open"},{"type":"string","const":"cadence"},{"type":"string","const":"power"},{"type":"string","const":"swim_stroke"},{"type":"string","const":"speed_lap"},{"type":"string","const":"heart_rate_lap"},{"type":"string","const":"pace"},{"type":"string","const":"heart_rate_threshold_percentage"},{"type":"string","const":"heart_rate_max_percentage"},{"type":"string","const":"speed_percentage"},{"type":"string","const":"power_percentage"},{"type":"string","const":"repetition"},{"type":"string","const":"tss"},{"type":"string","const":"if"},{"type":"string","const":"rpe"},{"type":"string","const":"heart_rate_zone"},{"type":"string","const":"power_zone"}],"description":"Quantity an intensity target constrains"},"WorkoutStepIntensity":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"rest"},{"type":"string","const":"warmup"},{"type":"string","const":"cooldown"},{"type":"string","const":"recovery"},{"type":"string","const":"active"}],"description":"Intensity classification of a workout step"},"StepControl":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"$ref":"#/components/schemas/StepControlType"},"value":{"type":"number","description":"Control value (e.g. 0.02 for a 2% treadmill grade)"}},"required":["type","value"],"description":"Equipment control applied during a step"},"StepControlType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"grade"},{"type":"string","const":"resistance"}],"description":"Equipment control adjusted during a step (e.g. treadmill incline)"},"StrengthData":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"exercise_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display name of the exercise"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Weight to lift"},"weight_display_unit":{"anyOf":[{"$ref":"#/components/schemas/WeightUnit"},{"type":"null"}]},"exercise_category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Garmin Training API exerciseCategory string (e.g. BENCH_PRESS, SQUAT)"}},"description":"Strength-exercise details for a step"},"WeightUnit":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"kg"},{"type":"string","const":"lbs"}],"description":"Weight display unit for strength exercises"},"SwimStepData":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"stroke_type":{"anyOf":[{"$ref":"#/components/schemas/SwimStrokeType"},{"type":"null"}]},"drill_type":{"anyOf":[{"$ref":"#/components/schemas/DrillType"},{"type":"null"}]},"equipment":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/SwimEquipmentType"}},{"type":"null"}]}},"description":"Swimming details for a step"},"SwimStrokeType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"backstroke"},{"type":"string","const":"breaststroke"},{"type":"string","const":"drill"},{"type":"string","const":"butterfly"},{"type":"string","const":"freestyle"},{"type":"string","const":"mixed"},{"type":"string","const":"im"}],"description":"Swim stroke for a swimming step"},"DrillType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"kick"},{"type":"string","const":"pull"},{"type":"string","const":"drill"}],"description":"Swim drill type"},"SwimEquipmentType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"none"},{"type":"string","const":"swim_fins"},{"type":"string","const":"swim_kickboard"},{"type":"string","const":"swim_paddles"},{"type":"string","const":"swim_pull_buoy"},{"type":"string","const":"swim_snorkel"}],"description":"Swim equipment used during a step"},"WorkoutSport":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"running"},{"type":"string","const":"cycling"},{"type":"string","const":"swimming"},{"type":"string","const":"strength"},{"type":"string","const":"rowing"},{"type":"string","const":"yoga"},{"type":"string","const":"pilates"},{"type":"string","const":"cardio"},{"type":"string","const":"trail_running"},{"type":"string","const":"mountain_biking"},{"type":"string","const":"backcountry_skiing"},{"type":"string","const":"hiking"},{"type":"string","const":"walking"},{"type":"string","const":"elliptical"},{"type":"string","const":"stair_climbing"}],"description":"Sport a workout template targets. Indoor/outdoor is expressed separately via environment."},"UnauthorizedProblem":{"type":"object","description":"A refused credential, always with its code.","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance","code"]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]}},"responses":{"Unauthorized":{"description":"The credential is missing, invalid, expired or revoked (code `unauthorized`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedProblem"}}}},"Forbidden":{"description":"The credential is not authorized (code scope_missing or audience_restricted), the environment is disabled (environment_disabled), or the required product entitlement is missing (entitlement_required).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"AuthorizationUnavailable":{"description":"The credential or the product access could not be checked (code `authorization_unavailable`). Retry after the service recovers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/workouts":{"get":{"tags":["PlannedWorkouts"],"summary":"List workout templates","description":"Returns every workout template stored for your developer account.","operationId":"Workouts_ListWorkouts","responses":{"200":{"description":"Stored templates, each including its workout_id","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WorkoutTemplate"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"}}}}}}
```

## Create a workout template

> Stores a reusable workout template and returns its \`workout\_id\`.\
> \
> \- The template carries no date and is not pushed to any provider until you plan it onto a user's calendar with \`POST /workouts/{workout\_id}/plan\`.

```json
{"openapi":"3.2.0","info":{"title":"Terra API","version":"2026.11.19"},"tags":[{"name":"PlannedWorkouts","summary":"Planned Workouts","description":"Workout templates, and the planned workouts that put them on a user's calendar."}],"servers":[{"url":"https://access.tryterra.co/api/v2"}],"security":[{"ApiKeyAuth":[],"DevID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key for authentication"},"DevID":{"type":"apiKey","in":"header","name":"dev-id","description":"Your developer ID for authentication and tracking"}},"schemas":{"WorkoutTemplate":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","description":"Name of the workout"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description of the workout"},"environment":{"anyOf":[{"$ref":"#/components/schemas/EnvironmentType"},{"type":"null"}]},"pool_length_meters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Pool length in meters, for swim workouts"},"step_blocks":{"type":"array","items":{"$ref":"#/components/schemas/StepBlock"}},"estimated_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated total duration in seconds"},"estimated_distance_meters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated total distance in meters"},"estimated_calories":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated calories burned"},"estimated_tss":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Planned training stress score (0-9999), where the provider or author supplies one. Forwarded to TrainingPeaks, which ignores it when any step target is not RPE and derives it from the structure instead."},"estimated_intensity_factor":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Planned intensity factor (0-5), where the provider or author supplies one. Forwarded to TrainingPeaks, which ignores it when any step target is not RPE and derives it from the structure instead."},"workout_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Terra identifier of the stored template. Set by Terra in responses; ignored on create."},"sport":{"$ref":"#/components/schemas/WorkoutSport"}},"required":["name","step_blocks","sport"],"description":"A reusable workout template, created once and planned onto user calendars"},"EnvironmentType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"indoor"},{"type":"string","const":"outdoor"},{"type":"string","const":"pool"}],"description":"Environment a workout takes place in"},"StepBlock":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"completion_condition":{"$ref":"#/components/schemas/CompletionCondition","description":"When this block completes (e.g. repeat count via reps)"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/WorkoutStep"}}},"required":["completion_condition","steps"],"description":"A block of steps, repeated until its completion condition is met"},"CompletionCondition":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"$ref":"#/components/schemas/CompletionConditionType"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Single value for the condition (e.g. seconds for time, meters for distance)"},"value_low":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lower bound when the condition is a range"},"value_high":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Upper bound when the condition is a range"}},"required":["type"],"description":"Condition that completes a step or repeats a step block"},"CompletionConditionType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"time"},{"type":"string","const":"distance"},{"type":"string","const":"hr"},{"type":"string","const":"calories"},{"type":"string","const":"open"},{"type":"string","const":"power"},{"type":"string","const":"reps"},{"type":"string","const":"hr_percentage"},{"type":"string","const":"power_percentage"},{"type":"string","const":"hr_less_than"},{"type":"string","const":"hr_greater_than"},{"type":"string","const":"hr_percentage_less_than"},{"type":"string","const":"hr_percentage_greater_than"},{"type":"string","const":"power_less_than"},{"type":"string","const":"power_greater_than"},{"type":"string","const":"power_percentage_less_than"},{"type":"string","const":"power_percentage_greater_than"}],"description":"How a step or block is considered complete"},"WorkoutStep":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"completion_condition":{"$ref":"#/components/schemas/CompletionCondition","description":"When this step completes"},"intensity_targets":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/IntensityTarget"}},{"type":"null"}],"description":"Intensity targets to hold during the step"},"intensity_type":{"$ref":"#/components/schemas/WorkoutStepIntensity"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Free-text coaching notes shown to the athlete"},"controls":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/StepControl"}},{"type":"null"}],"description":"Equipment controls applied during the step"},"strength":{"anyOf":[{"$ref":"#/components/schemas/StrengthData"},{"type":"null"}]},"swimming":{"anyOf":[{"$ref":"#/components/schemas/SwimStepData"},{"type":"null"}]}},"required":["completion_condition","intensity_type"],"description":"A single step within a step block"},"IntensityTarget":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"target_type":{"$ref":"#/components/schemas/WorkoutStepTargetType"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Single target value, in the unit for target_type"},"value_low":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lower bound of the target range, in the unit for target_type. For pace, the lower number is the faster pace"},"value_high":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Upper bound of the target range, in the unit for target_type"}},"required":["target_type"],"description":"Target intensity range for a step (e.g. heart-rate or power zone). The unit of value, value_low and value_high depends on target_type: heart_rate in BPM; power in watts; speed in metres per second; pace in seconds per kilometre for every sport, swimming included, so 4:30/km is 270, not 4.5, and 1:30 per 100 m is 900, not 90; cadence in rpm or steps per minute; rpe from 1 to 10; heart_rate_zone (1-5) and power_zone (1-7) as zone numbers; the *_percentage types in percent of the athlete parameter given when planning (max_heart_rate, threshold_heart_rate, ftp or threshold_speed)."},"WorkoutStepTargetType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"speed"},{"type":"string","const":"heart_rate"},{"type":"string","const":"open"},{"type":"string","const":"cadence"},{"type":"string","const":"power"},{"type":"string","const":"swim_stroke"},{"type":"string","const":"speed_lap"},{"type":"string","const":"heart_rate_lap"},{"type":"string","const":"pace"},{"type":"string","const":"heart_rate_threshold_percentage"},{"type":"string","const":"heart_rate_max_percentage"},{"type":"string","const":"speed_percentage"},{"type":"string","const":"power_percentage"},{"type":"string","const":"repetition"},{"type":"string","const":"tss"},{"type":"string","const":"if"},{"type":"string","const":"rpe"},{"type":"string","const":"heart_rate_zone"},{"type":"string","const":"power_zone"}],"description":"Quantity an intensity target constrains"},"WorkoutStepIntensity":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"rest"},{"type":"string","const":"warmup"},{"type":"string","const":"cooldown"},{"type":"string","const":"recovery"},{"type":"string","const":"active"}],"description":"Intensity classification of a workout step"},"StepControl":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"$ref":"#/components/schemas/StepControlType"},"value":{"type":"number","description":"Control value (e.g. 0.02 for a 2% treadmill grade)"}},"required":["type","value"],"description":"Equipment control applied during a step"},"StepControlType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"grade"},{"type":"string","const":"resistance"}],"description":"Equipment control adjusted during a step (e.g. treadmill incline)"},"StrengthData":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"exercise_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display name of the exercise"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Weight to lift"},"weight_display_unit":{"anyOf":[{"$ref":"#/components/schemas/WeightUnit"},{"type":"null"}]},"exercise_category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Garmin Training API exerciseCategory string (e.g. BENCH_PRESS, SQUAT)"}},"description":"Strength-exercise details for a step"},"WeightUnit":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"kg"},{"type":"string","const":"lbs"}],"description":"Weight display unit for strength exercises"},"SwimStepData":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"stroke_type":{"anyOf":[{"$ref":"#/components/schemas/SwimStrokeType"},{"type":"null"}]},"drill_type":{"anyOf":[{"$ref":"#/components/schemas/DrillType"},{"type":"null"}]},"equipment":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/SwimEquipmentType"}},{"type":"null"}]}},"description":"Swimming details for a step"},"SwimStrokeType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"backstroke"},{"type":"string","const":"breaststroke"},{"type":"string","const":"drill"},{"type":"string","const":"butterfly"},{"type":"string","const":"freestyle"},{"type":"string","const":"mixed"},{"type":"string","const":"im"}],"description":"Swim stroke for a swimming step"},"DrillType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"kick"},{"type":"string","const":"pull"},{"type":"string","const":"drill"}],"description":"Swim drill type"},"SwimEquipmentType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"none"},{"type":"string","const":"swim_fins"},{"type":"string","const":"swim_kickboard"},{"type":"string","const":"swim_paddles"},{"type":"string","const":"swim_pull_buoy"},{"type":"string","const":"swim_snorkel"}],"description":"Swim equipment used during a step"},"WorkoutSport":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"running"},{"type":"string","const":"cycling"},{"type":"string","const":"swimming"},{"type":"string","const":"strength"},{"type":"string","const":"rowing"},{"type":"string","const":"yoga"},{"type":"string","const":"pilates"},{"type":"string","const":"cardio"},{"type":"string","const":"trail_running"},{"type":"string","const":"mountain_biking"},{"type":"string","const":"backcountry_skiing"},{"type":"string","const":"hiking"},{"type":"string","const":"walking"},{"type":"string","const":"elliptical"},{"type":"string","const":"stair_climbing"}],"description":"Sport a workout template targets. Indoor/outdoor is expressed separately via environment."},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"UnauthorizedProblem":{"type":"object","description":"A refused credential, always with its code.","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance","code"]}},"responses":{"BadRequest":{"description":"One or more parameters is malformed. The `detail` field describes the specific problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"The credential is missing, invalid, expired or revoked (code `unauthorized`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedProblem"}}}},"Forbidden":{"description":"The credential is not authorized (code scope_missing or audience_restricted), the environment is disabled (environment_disabled), or the required product entitlement is missing (entitlement_required).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"AuthorizationUnavailable":{"description":"The credential or the product access could not be checked (code `authorization_unavailable`). Retry after the service recovers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/workouts":{"post":{"tags":["PlannedWorkouts"],"summary":"Create a workout template","description":"Stores a reusable workout template and returns its `workout_id`.\n\n- The template carries no date and is not pushed to any provider until you plan it onto a user's calendar with `POST /workouts/{workout_id}/plan`.","operationId":"Workouts_CreateWorkout","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutTemplate"}}}},"responses":{"200":{"description":"Template stored","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["success"]},"workout_id":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"}}}}}}
```

## Get a workout template

> Returns one stored workout template.

```json
{"openapi":"3.2.0","info":{"title":"Terra API","version":"2026.11.19"},"tags":[{"name":"PlannedWorkouts","summary":"Planned Workouts","description":"Workout templates, and the planned workouts that put them on a user's calendar."}],"servers":[{"url":"https://access.tryterra.co/api/v2"}],"security":[{"ApiKeyAuth":[],"DevID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key for authentication"},"DevID":{"type":"apiKey","in":"header","name":"dev-id","description":"Your developer ID for authentication and tracking"}},"schemas":{"WorkoutTemplate":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","description":"Name of the workout"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description of the workout"},"environment":{"anyOf":[{"$ref":"#/components/schemas/EnvironmentType"},{"type":"null"}]},"pool_length_meters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Pool length in meters, for swim workouts"},"step_blocks":{"type":"array","items":{"$ref":"#/components/schemas/StepBlock"}},"estimated_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated total duration in seconds"},"estimated_distance_meters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated total distance in meters"},"estimated_calories":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated calories burned"},"estimated_tss":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Planned training stress score (0-9999), where the provider or author supplies one. Forwarded to TrainingPeaks, which ignores it when any step target is not RPE and derives it from the structure instead."},"estimated_intensity_factor":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Planned intensity factor (0-5), where the provider or author supplies one. Forwarded to TrainingPeaks, which ignores it when any step target is not RPE and derives it from the structure instead."},"workout_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Terra identifier of the stored template. Set by Terra in responses; ignored on create."},"sport":{"$ref":"#/components/schemas/WorkoutSport"}},"required":["name","step_blocks","sport"],"description":"A reusable workout template, created once and planned onto user calendars"},"EnvironmentType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"indoor"},{"type":"string","const":"outdoor"},{"type":"string","const":"pool"}],"description":"Environment a workout takes place in"},"StepBlock":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"completion_condition":{"$ref":"#/components/schemas/CompletionCondition","description":"When this block completes (e.g. repeat count via reps)"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/WorkoutStep"}}},"required":["completion_condition","steps"],"description":"A block of steps, repeated until its completion condition is met"},"CompletionCondition":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"$ref":"#/components/schemas/CompletionConditionType"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Single value for the condition (e.g. seconds for time, meters for distance)"},"value_low":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lower bound when the condition is a range"},"value_high":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Upper bound when the condition is a range"}},"required":["type"],"description":"Condition that completes a step or repeats a step block"},"CompletionConditionType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"time"},{"type":"string","const":"distance"},{"type":"string","const":"hr"},{"type":"string","const":"calories"},{"type":"string","const":"open"},{"type":"string","const":"power"},{"type":"string","const":"reps"},{"type":"string","const":"hr_percentage"},{"type":"string","const":"power_percentage"},{"type":"string","const":"hr_less_than"},{"type":"string","const":"hr_greater_than"},{"type":"string","const":"hr_percentage_less_than"},{"type":"string","const":"hr_percentage_greater_than"},{"type":"string","const":"power_less_than"},{"type":"string","const":"power_greater_than"},{"type":"string","const":"power_percentage_less_than"},{"type":"string","const":"power_percentage_greater_than"}],"description":"How a step or block is considered complete"},"WorkoutStep":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"completion_condition":{"$ref":"#/components/schemas/CompletionCondition","description":"When this step completes"},"intensity_targets":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/IntensityTarget"}},{"type":"null"}],"description":"Intensity targets to hold during the step"},"intensity_type":{"$ref":"#/components/schemas/WorkoutStepIntensity"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Free-text coaching notes shown to the athlete"},"controls":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/StepControl"}},{"type":"null"}],"description":"Equipment controls applied during the step"},"strength":{"anyOf":[{"$ref":"#/components/schemas/StrengthData"},{"type":"null"}]},"swimming":{"anyOf":[{"$ref":"#/components/schemas/SwimStepData"},{"type":"null"}]}},"required":["completion_condition","intensity_type"],"description":"A single step within a step block"},"IntensityTarget":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"target_type":{"$ref":"#/components/schemas/WorkoutStepTargetType"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Single target value, in the unit for target_type"},"value_low":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lower bound of the target range, in the unit for target_type. For pace, the lower number is the faster pace"},"value_high":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Upper bound of the target range, in the unit for target_type"}},"required":["target_type"],"description":"Target intensity range for a step (e.g. heart-rate or power zone). The unit of value, value_low and value_high depends on target_type: heart_rate in BPM; power in watts; speed in metres per second; pace in seconds per kilometre for every sport, swimming included, so 4:30/km is 270, not 4.5, and 1:30 per 100 m is 900, not 90; cadence in rpm or steps per minute; rpe from 1 to 10; heart_rate_zone (1-5) and power_zone (1-7) as zone numbers; the *_percentage types in percent of the athlete parameter given when planning (max_heart_rate, threshold_heart_rate, ftp or threshold_speed)."},"WorkoutStepTargetType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"speed"},{"type":"string","const":"heart_rate"},{"type":"string","const":"open"},{"type":"string","const":"cadence"},{"type":"string","const":"power"},{"type":"string","const":"swim_stroke"},{"type":"string","const":"speed_lap"},{"type":"string","const":"heart_rate_lap"},{"type":"string","const":"pace"},{"type":"string","const":"heart_rate_threshold_percentage"},{"type":"string","const":"heart_rate_max_percentage"},{"type":"string","const":"speed_percentage"},{"type":"string","const":"power_percentage"},{"type":"string","const":"repetition"},{"type":"string","const":"tss"},{"type":"string","const":"if"},{"type":"string","const":"rpe"},{"type":"string","const":"heart_rate_zone"},{"type":"string","const":"power_zone"}],"description":"Quantity an intensity target constrains"},"WorkoutStepIntensity":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"rest"},{"type":"string","const":"warmup"},{"type":"string","const":"cooldown"},{"type":"string","const":"recovery"},{"type":"string","const":"active"}],"description":"Intensity classification of a workout step"},"StepControl":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"$ref":"#/components/schemas/StepControlType"},"value":{"type":"number","description":"Control value (e.g. 0.02 for a 2% treadmill grade)"}},"required":["type","value"],"description":"Equipment control applied during a step"},"StepControlType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"grade"},{"type":"string","const":"resistance"}],"description":"Equipment control adjusted during a step (e.g. treadmill incline)"},"StrengthData":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"exercise_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display name of the exercise"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Weight to lift"},"weight_display_unit":{"anyOf":[{"$ref":"#/components/schemas/WeightUnit"},{"type":"null"}]},"exercise_category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Garmin Training API exerciseCategory string (e.g. BENCH_PRESS, SQUAT)"}},"description":"Strength-exercise details for a step"},"WeightUnit":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"kg"},{"type":"string","const":"lbs"}],"description":"Weight display unit for strength exercises"},"SwimStepData":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"stroke_type":{"anyOf":[{"$ref":"#/components/schemas/SwimStrokeType"},{"type":"null"}]},"drill_type":{"anyOf":[{"$ref":"#/components/schemas/DrillType"},{"type":"null"}]},"equipment":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/SwimEquipmentType"}},{"type":"null"}]}},"description":"Swimming details for a step"},"SwimStrokeType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"backstroke"},{"type":"string","const":"breaststroke"},{"type":"string","const":"drill"},{"type":"string","const":"butterfly"},{"type":"string","const":"freestyle"},{"type":"string","const":"mixed"},{"type":"string","const":"im"}],"description":"Swim stroke for a swimming step"},"DrillType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"kick"},{"type":"string","const":"pull"},{"type":"string","const":"drill"}],"description":"Swim drill type"},"SwimEquipmentType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"none"},{"type":"string","const":"swim_fins"},{"type":"string","const":"swim_kickboard"},{"type":"string","const":"swim_paddles"},{"type":"string","const":"swim_pull_buoy"},{"type":"string","const":"swim_snorkel"}],"description":"Swim equipment used during a step"},"WorkoutSport":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"running"},{"type":"string","const":"cycling"},{"type":"string","const":"swimming"},{"type":"string","const":"strength"},{"type":"string","const":"rowing"},{"type":"string","const":"yoga"},{"type":"string","const":"pilates"},{"type":"string","const":"cardio"},{"type":"string","const":"trail_running"},{"type":"string","const":"mountain_biking"},{"type":"string","const":"backcountry_skiing"},{"type":"string","const":"hiking"},{"type":"string","const":"walking"},{"type":"string","const":"elliptical"},{"type":"string","const":"stair_climbing"}],"description":"Sport a workout template targets. Indoor/outdoor is expressed separately via environment."},"UnauthorizedProblem":{"type":"object","description":"A refused credential, always with its code.","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance","code"]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]}},"responses":{"Unauthorized":{"description":"The credential is missing, invalid, expired or revoked (code `unauthorized`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedProblem"}}}},"Forbidden":{"description":"The credential is not authorized (code scope_missing or audience_restricted), the environment is disabled (environment_disabled), or the required product entitlement is missing (entitlement_required).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"A referenced resource does not exist on Terra's end.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"AuthorizationUnavailable":{"description":"The credential or the product access could not be checked (code `authorization_unavailable`). Retry after the service recovers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/workouts/{workout_id}":{"get":{"tags":["PlannedWorkouts"],"summary":"Get a workout template","description":"Returns one stored workout template.","operationId":"Workouts_GetWorkout","parameters":[{"name":"workout_id","in":"path","required":true,"schema":{"type":"integer","format":"int64"},"description":"The workout template's ID, as returned by `POST /workouts`."}],"responses":{"200":{"description":"The stored template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutTemplate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"}}}}}}
```

## Update a workout template

> Replaces the template and re-sends it to every upcoming planned workout made from it, each under its existing provider ID.\
> \
> \- Completed and past planned workouts keep the version they were sent.\
> \- An Apple Health planned workout already on the device is queued to fetch the new version, as on a reschedule.\
> \- Each re-send to a provider is billed like a reschedule.\
> \- The response lists each planned workout's outcome: \`skipped\` ones cannot be re-sent (for example, the user disconnected); repeat the request to re-send \`failed\` ones.

```json
{"openapi":"3.2.0","info":{"title":"Terra API","version":"2026.11.19"},"tags":[{"name":"PlannedWorkouts","summary":"Planned Workouts","description":"Workout templates, and the planned workouts that put them on a user's calendar."}],"servers":[{"url":"https://access.tryterra.co/api/v2"}],"security":[{"ApiKeyAuth":[],"DevID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key for authentication"},"DevID":{"type":"apiKey","in":"header","name":"dev-id","description":"Your developer ID for authentication and tracking"}},"schemas":{"WorkoutTemplate":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","description":"Name of the workout"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description of the workout"},"environment":{"anyOf":[{"$ref":"#/components/schemas/EnvironmentType"},{"type":"null"}]},"pool_length_meters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Pool length in meters, for swim workouts"},"step_blocks":{"type":"array","items":{"$ref":"#/components/schemas/StepBlock"}},"estimated_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated total duration in seconds"},"estimated_distance_meters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated total distance in meters"},"estimated_calories":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated calories burned"},"estimated_tss":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Planned training stress score (0-9999), where the provider or author supplies one. Forwarded to TrainingPeaks, which ignores it when any step target is not RPE and derives it from the structure instead."},"estimated_intensity_factor":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Planned intensity factor (0-5), where the provider or author supplies one. Forwarded to TrainingPeaks, which ignores it when any step target is not RPE and derives it from the structure instead."},"workout_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Terra identifier of the stored template. Set by Terra in responses; ignored on create."},"sport":{"$ref":"#/components/schemas/WorkoutSport"}},"required":["name","step_blocks","sport"],"description":"A reusable workout template, created once and planned onto user calendars"},"EnvironmentType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"indoor"},{"type":"string","const":"outdoor"},{"type":"string","const":"pool"}],"description":"Environment a workout takes place in"},"StepBlock":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"completion_condition":{"$ref":"#/components/schemas/CompletionCondition","description":"When this block completes (e.g. repeat count via reps)"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/WorkoutStep"}}},"required":["completion_condition","steps"],"description":"A block of steps, repeated until its completion condition is met"},"CompletionCondition":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"$ref":"#/components/schemas/CompletionConditionType"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Single value for the condition (e.g. seconds for time, meters for distance)"},"value_low":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lower bound when the condition is a range"},"value_high":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Upper bound when the condition is a range"}},"required":["type"],"description":"Condition that completes a step or repeats a step block"},"CompletionConditionType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"time"},{"type":"string","const":"distance"},{"type":"string","const":"hr"},{"type":"string","const":"calories"},{"type":"string","const":"open"},{"type":"string","const":"power"},{"type":"string","const":"reps"},{"type":"string","const":"hr_percentage"},{"type":"string","const":"power_percentage"},{"type":"string","const":"hr_less_than"},{"type":"string","const":"hr_greater_than"},{"type":"string","const":"hr_percentage_less_than"},{"type":"string","const":"hr_percentage_greater_than"},{"type":"string","const":"power_less_than"},{"type":"string","const":"power_greater_than"},{"type":"string","const":"power_percentage_less_than"},{"type":"string","const":"power_percentage_greater_than"}],"description":"How a step or block is considered complete"},"WorkoutStep":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"completion_condition":{"$ref":"#/components/schemas/CompletionCondition","description":"When this step completes"},"intensity_targets":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/IntensityTarget"}},{"type":"null"}],"description":"Intensity targets to hold during the step"},"intensity_type":{"$ref":"#/components/schemas/WorkoutStepIntensity"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Free-text coaching notes shown to the athlete"},"controls":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/StepControl"}},{"type":"null"}],"description":"Equipment controls applied during the step"},"strength":{"anyOf":[{"$ref":"#/components/schemas/StrengthData"},{"type":"null"}]},"swimming":{"anyOf":[{"$ref":"#/components/schemas/SwimStepData"},{"type":"null"}]}},"required":["completion_condition","intensity_type"],"description":"A single step within a step block"},"IntensityTarget":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"target_type":{"$ref":"#/components/schemas/WorkoutStepTargetType"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Single target value, in the unit for target_type"},"value_low":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lower bound of the target range, in the unit for target_type. For pace, the lower number is the faster pace"},"value_high":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Upper bound of the target range, in the unit for target_type"}},"required":["target_type"],"description":"Target intensity range for a step (e.g. heart-rate or power zone). The unit of value, value_low and value_high depends on target_type: heart_rate in BPM; power in watts; speed in metres per second; pace in seconds per kilometre for every sport, swimming included, so 4:30/km is 270, not 4.5, and 1:30 per 100 m is 900, not 90; cadence in rpm or steps per minute; rpe from 1 to 10; heart_rate_zone (1-5) and power_zone (1-7) as zone numbers; the *_percentage types in percent of the athlete parameter given when planning (max_heart_rate, threshold_heart_rate, ftp or threshold_speed)."},"WorkoutStepTargetType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"speed"},{"type":"string","const":"heart_rate"},{"type":"string","const":"open"},{"type":"string","const":"cadence"},{"type":"string","const":"power"},{"type":"string","const":"swim_stroke"},{"type":"string","const":"speed_lap"},{"type":"string","const":"heart_rate_lap"},{"type":"string","const":"pace"},{"type":"string","const":"heart_rate_threshold_percentage"},{"type":"string","const":"heart_rate_max_percentage"},{"type":"string","const":"speed_percentage"},{"type":"string","const":"power_percentage"},{"type":"string","const":"repetition"},{"type":"string","const":"tss"},{"type":"string","const":"if"},{"type":"string","const":"rpe"},{"type":"string","const":"heart_rate_zone"},{"type":"string","const":"power_zone"}],"description":"Quantity an intensity target constrains"},"WorkoutStepIntensity":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"rest"},{"type":"string","const":"warmup"},{"type":"string","const":"cooldown"},{"type":"string","const":"recovery"},{"type":"string","const":"active"}],"description":"Intensity classification of a workout step"},"StepControl":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"$ref":"#/components/schemas/StepControlType"},"value":{"type":"number","description":"Control value (e.g. 0.02 for a 2% treadmill grade)"}},"required":["type","value"],"description":"Equipment control applied during a step"},"StepControlType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"grade"},{"type":"string","const":"resistance"}],"description":"Equipment control adjusted during a step (e.g. treadmill incline)"},"StrengthData":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"exercise_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display name of the exercise"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Weight to lift"},"weight_display_unit":{"anyOf":[{"$ref":"#/components/schemas/WeightUnit"},{"type":"null"}]},"exercise_category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Garmin Training API exerciseCategory string (e.g. BENCH_PRESS, SQUAT)"}},"description":"Strength-exercise details for a step"},"WeightUnit":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"kg"},{"type":"string","const":"lbs"}],"description":"Weight display unit for strength exercises"},"SwimStepData":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"stroke_type":{"anyOf":[{"$ref":"#/components/schemas/SwimStrokeType"},{"type":"null"}]},"drill_type":{"anyOf":[{"$ref":"#/components/schemas/DrillType"},{"type":"null"}]},"equipment":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/SwimEquipmentType"}},{"type":"null"}]}},"description":"Swimming details for a step"},"SwimStrokeType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"backstroke"},{"type":"string","const":"breaststroke"},{"type":"string","const":"drill"},{"type":"string","const":"butterfly"},{"type":"string","const":"freestyle"},{"type":"string","const":"mixed"},{"type":"string","const":"im"}],"description":"Swim stroke for a swimming step"},"DrillType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"kick"},{"type":"string","const":"pull"},{"type":"string","const":"drill"}],"description":"Swim drill type"},"SwimEquipmentType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"none"},{"type":"string","const":"swim_fins"},{"type":"string","const":"swim_kickboard"},{"type":"string","const":"swim_paddles"},{"type":"string","const":"swim_pull_buoy"},{"type":"string","const":"swim_snorkel"}],"description":"Swim equipment used during a step"},"WorkoutSport":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"running"},{"type":"string","const":"cycling"},{"type":"string","const":"swimming"},{"type":"string","const":"strength"},{"type":"string","const":"rowing"},{"type":"string","const":"yoga"},{"type":"string","const":"pilates"},{"type":"string","const":"cardio"},{"type":"string","const":"trail_running"},{"type":"string","const":"mountain_biking"},{"type":"string","const":"backcountry_skiing"},{"type":"string","const":"hiking"},{"type":"string","const":"walking"},{"type":"string","const":"elliptical"},{"type":"string","const":"stair_climbing"}],"description":"Sport a workout template targets. Indoor/outdoor is expressed separately via environment."},"WorkoutUpdateResponse":{"type":"object","required":["workout_id","planned_workouts"],"properties":{"status":{"type":"string","enum":["success"],"description":"Present when every reachable planned workout was updated (200)."},"message":{"type":"string","description":"Present when some re-sends failed (207). Repeat the request to re-send them."},"workout_id":{"type":"string"},"planned_workouts":{"type":"array","items":{"$ref":"#/components/schemas/PlannedWorkoutUpdateResult"}}}},"PlannedWorkoutUpdateResult":{"type":"object","required":["planned_workout_id","status"],"properties":{"planned_workout_id":{"type":"string"},"provider_workout_id":{"type":"string","description":"The planned workout's id at the provider after the update."},"status":{"type":"string","enum":["updated","failed","skipped"]},"error":{"type":"string","description":"Why the planned workout was not updated."},"warnings":{"type":"array","description":"What the provider could not take from the new template, as when planning.","items":{"$ref":"#/components/schemas/CoercionWarning"}}}},"CoercionWarning":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"path":{"type":"string","description":"JSON path within the workout template of the element that could not be represented exactly"},"message":{"type":"string","description":"What was changed or dropped, and why"}},"required":["path","message"],"description":"A non-fatal adjustment made while converting a workout between Terra's template model and a provider's"},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"UnauthorizedProblem":{"type":"object","description":"A refused credential, always with its code.","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance","code"]}},"responses":{"BadRequest":{"description":"One or more parameters is malformed. The `detail` field describes the specific problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"The credential is missing, invalid, expired or revoked (code `unauthorized`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedProblem"}}}},"Forbidden":{"description":"The credential is not authorized (code scope_missing or audience_restricted), the environment is disabled (environment_disabled), or the required product entitlement is missing (entitlement_required).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"A referenced resource does not exist on Terra's end.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"AuthorizationUnavailable":{"description":"The credential or the product access could not be checked (code `authorization_unavailable`). Retry after the service recovers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/workouts/{workout_id}":{"put":{"tags":["PlannedWorkouts"],"summary":"Update a workout template","description":"Replaces the template and re-sends it to every upcoming planned workout made from it, each under its existing provider ID.\n\n- Completed and past planned workouts keep the version they were sent.\n- An Apple Health planned workout already on the device is queued to fetch the new version, as on a reschedule.\n- Each re-send to a provider is billed like a reschedule.\n- The response lists each planned workout's outcome: `skipped` ones cannot be re-sent (for example, the user disconnected); repeat the request to re-send `failed` ones.","operationId":"Workouts_UpdateWorkout","parameters":[{"name":"workout_id","in":"path","required":true,"schema":{"type":"integer","format":"int64"},"description":"The workout template's ID, as returned by `POST /workouts`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutTemplate"}}}},"responses":{"200":{"description":"Template saved and re-sent to every upcoming planned workout that could be reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutUpdateResponse"}}}},"207":{"description":"Template saved, but some re-sends failed. Repeat the request to re-send them.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutUpdateResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"The workout has more planned workouts than one update can re-send to.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"}}}}}}
```

## Delete a workout template

> Deletes the template and every planned workout created from it, removing each from its connected provider.

```json
{"openapi":"3.2.0","info":{"title":"Terra API","version":"2026.11.19"},"tags":[{"name":"PlannedWorkouts","summary":"Planned Workouts","description":"Workout templates, and the planned workouts that put them on a user's calendar."}],"servers":[{"url":"https://access.tryterra.co/api/v2"}],"security":[{"ApiKeyAuth":[],"DevID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key for authentication"},"DevID":{"type":"apiKey","in":"header","name":"dev-id","description":"Your developer ID for authentication and tracking"}},"responses":{"Unauthorized":{"description":"The credential is missing, invalid, expired or revoked (code `unauthorized`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedProblem"}}}},"NotFound":{"description":"A referenced resource does not exist on Terra's end.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"AuthorizationUnavailable":{"description":"The credential or the product access could not be checked (code `authorization_unavailable`). Retry after the service recovers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"UnauthorizedProblem":{"type":"object","description":"A refused credential, always with its code.","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance","code"]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]}}},"paths":{"/workouts/{workout_id}":{"delete":{"tags":["PlannedWorkouts"],"summary":"Delete a workout template","description":"Deletes the template and every planned workout created from it, removing each from its connected provider.","operationId":"Workouts_DeleteWorkout","parameters":[{"name":"workout_id","in":"path","required":true,"schema":{"type":"integer","format":"int64"},"description":"The workout template's ID, as returned by `POST /workouts`."}],"responses":{"204":{"description":"Template and all planned instances deleted"},"207":{"description":"Some provider-side deletions failed; the template is retained. Retry to complete the cascade.\n","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"424":{"description":"Provider-side deletion could not be performed; retry later.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"}}}}}}
```

## Plan a workout onto a user's calendar

> Schedules the template for a user on \`planned\_date\` and pushes it to the user's connected provider, or queues it for delivery through the SDK.\
> \
> \- Athlete metrics in the body personalise zone-based targets for this planned workout only.

```json
{"openapi":"3.2.0","info":{"title":"Terra API","version":"2026.11.19"},"tags":[{"name":"PlannedWorkouts","summary":"Planned Workouts","description":"Workout templates, and the planned workouts that put them on a user's calendar."}],"servers":[{"url":"https://access.tryterra.co/api/v2"}],"security":[{"ApiKeyAuth":[],"DevID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key for authentication"},"DevID":{"type":"apiKey","in":"header","name":"dev-id","description":"Your developer ID for authentication and tracking"}},"schemas":{"CoercionWarning":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"path":{"type":"string","description":"JSON path within the workout template of the element that could not be represented exactly"},"message":{"type":"string","description":"What was changed or dropped, and why"}},"required":["path","message"],"description":"A non-fatal adjustment made while converting a workout between Terra's template model and a provider's"},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"UnauthorizedProblem":{"type":"object","description":"A refused credential, always with its code.","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance","code"]}},"responses":{"BadRequest":{"description":"One or more parameters is malformed. The `detail` field describes the specific problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"The credential is missing, invalid, expired or revoked (code `unauthorized`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedProblem"}}}},"NotFound":{"description":"A referenced resource does not exist on Terra's end.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"AuthorizationUnavailable":{"description":"The credential or the product access could not be checked (code `authorization_unavailable`). Retry after the service recovers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/workouts/{workout_id}/plan":{"post":{"tags":["PlannedWorkouts"],"summary":"Plan a workout onto a user's calendar","description":"Schedules the template for a user on `planned_date` and pushes it to the user's connected provider, or queues it for delivery through the SDK.\n\n- Athlete metrics in the body personalise zone-based targets for this planned workout only.","operationId":"Workouts_PlanWorkout","parameters":[{"name":"workout_id","in":"path","required":true,"schema":{"type":"integer","format":"int64"},"description":"The ID of the workout template to plan, as returned by `POST /workouts`."},{"name":"user_id","in":"query","required":true,"description":"The Terra user ID of the connection to plan the workout for.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["planned_date"],"properties":{"planned_date":{"type":"string","format":"date","description":"Date to schedule the workout on (YYYY-MM-DD)"},"ftp":{"type":"number","description":"Functional Threshold Power in watts"},"max_heart_rate":{"type":"number","description":"Maximum heart rate in BPM"},"threshold_heart_rate":{"type":"number","description":"Threshold heart rate in BPM"},"threshold_speed":{"type":"number","description":"Threshold speed in m/s"},"pool_length_meters":{"type":"number","description":"Pool length in meters (overrides the template value)"}}}}}},"responses":{"201":{"description":"Planned workout created and pushed (or queued for SDK delivery)","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["success"]},"planned_workout_id":{"type":"string"},"provider_workout_id":{"type":"string","description":"Identifier assigned by the provider. Absent for SDK-delivered plans."},"coercion_warnings":{"type":"string","deprecated":true,"description":"Deprecated; use warnings. Set when the template could not be represented exactly on the provider."},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/CoercionWarning"},"description":"Adjustments made when the template could not be represented exactly on the provider. Empty when the push was exact."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The Planned Workouts add-on is not enabled for this account.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"$ref":"#/components/responses/NotFound"},"424":{"description":"The provider rejected the workout push; retry later.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"}}}}}}
```

## List planned workouts

> Returns the user's planned workouts, including those created on the provider side (\`is\_external\` true) where the provider exposes them.\
> \
> \- Provider-side workouts are read live from the provider, not stored by Terra.\
> \- A workout pushed through Terra and echoed back by the provider is listed once, as the Terra-created one.\
> \- If the provider cannot be read, the response is still 200, with Terra's workouts and \`X-Terra-Provider-Data-Truncated: true\`.\
> \- Providers may limit how far ahead planned workouts are visible.

```json
{"openapi":"3.2.0","info":{"title":"Terra API","version":"2026.11.19"},"tags":[{"name":"PlannedWorkouts","summary":"Planned Workouts","description":"Workout templates, and the planned workouts that put them on a user's calendar."}],"servers":[{"url":"https://access.tryterra.co/api/v2"}],"security":[{"ApiKeyAuth":[],"DevID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key for authentication"},"DevID":{"type":"apiKey","in":"header","name":"dev-id","description":"Your developer ID for authentication and tracking"}},"schemas":{"PlannedWorkout":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"planned_workout_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Terra identifier of the planned workout. Null for workouts created on the provider side."},"workout_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Identifier of the workout template this was planned from. Null for workouts created on the provider side; a non-null value means the workout is managed through Terra and can be rescheduled or deleted."},"planned_date":{"type":"string","description":"Scheduled date (YYYY-MM-DD)"},"provider_workout_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Identifier of the workout on the provider's side, in the form the provider's own API uses for it"},"coercion_warnings":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Deprecated: the stored JSON text of the adjustments made when the template was pushed to the provider; use `warnings`. Null when there were none or the workout was created on the provider side.","deprecated":true},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/CoercionWarning"},"description":"Adjustments made while converting between Terra's template and the provider's format. On Terra-created workouts these come from the push to the provider; on external workouts, from reading the provider's workout into a template. Empty when the conversion was exact."},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Creation time (RFC 3339). Null for external workouts."},"last_updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last update time (RFC 3339). Null for external workouts."},"is_external":{"type":"boolean","description":"True when the workout was created on the provider side rather than through Terra"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Time the session was reported complete by the user's device (RFC 3339, whole seconds, UTC). Null until a device reports it."},"athlete_metrics":{"anyOf":[{"$ref":"#/components/schemas/AthleteMetrics"},{"type":"null"}]},"workout":{"anyOf":[{"$ref":"#/components/schemas/PlannedWorkoutBody"},{"type":"null"}],"description":"The workout body, in the same shape for Terra-created and external workouts. Null when a Terra-created workout's body could not be loaded (a warning at path `workout` says why); for an external workout whose steps could not be fetched from the provider, the header fields are present, `step_blocks` is empty and a warning at path `step_blocks` says why."},"details":{"anyOf":[{"$ref":"#/components/schemas/PlannedWorkoutDetails"},{"type":"null"}],"description":"Deprecated. The provider body of an external workout in its pre-template shape; use `workout`. Null on Terra-created workouts. Removed in the next major SDK release.","deprecated":true}},"required":["planned_workout_id","workout_id","planned_date","provider_workout_id","coercion_warnings","warnings","created_at","last_updated_at","is_external","completed_at","athlete_metrics","workout","details"],"description":"A workout scheduled onto a user's calendar, whether created through Terra or on the provider side"},"CoercionWarning":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"path":{"type":"string","description":"JSON path within the workout template of the element that could not be represented exactly"},"message":{"type":"string","description":"What was changed or dropped, and why"}},"required":["path","message"],"description":"A non-fatal adjustment made while converting a workout between Terra's template model and a provider's"},"AthleteMetrics":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"threshold_heart_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Threshold heart rate in BPM"},"max_heart_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Maximum heart rate in BPM"},"threshold_speed":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Threshold speed in m/s"},"ftp":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Functional Threshold Power in watts"},"pool_length_meters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Pool length in meters (overrides the template value)"}},"description":"Athlete-specific metrics used to personalise workout targets for one planned workout"},"PlannedWorkoutBody":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","description":"Name of the workout"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description of the workout"},"environment":{"anyOf":[{"$ref":"#/components/schemas/EnvironmentType"},{"type":"null"}]},"pool_length_meters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Pool length in meters, for swim workouts"},"step_blocks":{"type":"array","items":{"$ref":"#/components/schemas/StepBlock"}},"estimated_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated total duration in seconds"},"estimated_distance_meters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated total distance in meters"},"estimated_calories":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated calories burned"},"estimated_tss":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Planned training stress score (0-9999), where the provider or author supplies one. Forwarded to TrainingPeaks, which ignores it when any step target is not RPE and derives it from the structure instead."},"estimated_intensity_factor":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Planned intensity factor (0-5), where the provider or author supplies one. Forwarded to TrainingPeaks, which ignores it when any step target is not RPE and derives it from the structure instead."},"workout_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Terra identifier of the stored template. Set by Terra in responses; ignored on create."},"sport":{"$ref":"#/components/schemas/PlannedWorkoutSport"}},"required":["name","step_blocks","sport"],"description":"The body of a planned workout: a WorkoutTemplate whose sport may be `unspecified` when it was created on the provider side"},"EnvironmentType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"indoor"},{"type":"string","const":"outdoor"},{"type":"string","const":"pool"}],"description":"Environment a workout takes place in"},"StepBlock":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"completion_condition":{"$ref":"#/components/schemas/CompletionCondition","description":"When this block completes (e.g. repeat count via reps)"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/WorkoutStep"}}},"required":["completion_condition","steps"],"description":"A block of steps, repeated until its completion condition is met"},"CompletionCondition":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"$ref":"#/components/schemas/CompletionConditionType"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Single value for the condition (e.g. seconds for time, meters for distance)"},"value_low":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lower bound when the condition is a range"},"value_high":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Upper bound when the condition is a range"}},"required":["type"],"description":"Condition that completes a step or repeats a step block"},"CompletionConditionType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"time"},{"type":"string","const":"distance"},{"type":"string","const":"hr"},{"type":"string","const":"calories"},{"type":"string","const":"open"},{"type":"string","const":"power"},{"type":"string","const":"reps"},{"type":"string","const":"hr_percentage"},{"type":"string","const":"power_percentage"},{"type":"string","const":"hr_less_than"},{"type":"string","const":"hr_greater_than"},{"type":"string","const":"hr_percentage_less_than"},{"type":"string","const":"hr_percentage_greater_than"},{"type":"string","const":"power_less_than"},{"type":"string","const":"power_greater_than"},{"type":"string","const":"power_percentage_less_than"},{"type":"string","const":"power_percentage_greater_than"}],"description":"How a step or block is considered complete"},"WorkoutStep":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"completion_condition":{"$ref":"#/components/schemas/CompletionCondition","description":"When this step completes"},"intensity_targets":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/IntensityTarget"}},{"type":"null"}],"description":"Intensity targets to hold during the step"},"intensity_type":{"$ref":"#/components/schemas/WorkoutStepIntensity"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Free-text coaching notes shown to the athlete"},"controls":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/StepControl"}},{"type":"null"}],"description":"Equipment controls applied during the step"},"strength":{"anyOf":[{"$ref":"#/components/schemas/StrengthData"},{"type":"null"}]},"swimming":{"anyOf":[{"$ref":"#/components/schemas/SwimStepData"},{"type":"null"}]}},"required":["completion_condition","intensity_type"],"description":"A single step within a step block"},"IntensityTarget":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"target_type":{"$ref":"#/components/schemas/WorkoutStepTargetType"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Single target value, in the unit for target_type"},"value_low":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lower bound of the target range, in the unit for target_type. For pace, the lower number is the faster pace"},"value_high":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Upper bound of the target range, in the unit for target_type"}},"required":["target_type"],"description":"Target intensity range for a step (e.g. heart-rate or power zone). The unit of value, value_low and value_high depends on target_type: heart_rate in BPM; power in watts; speed in metres per second; pace in seconds per kilometre for every sport, swimming included, so 4:30/km is 270, not 4.5, and 1:30 per 100 m is 900, not 90; cadence in rpm or steps per minute; rpe from 1 to 10; heart_rate_zone (1-5) and power_zone (1-7) as zone numbers; the *_percentage types in percent of the athlete parameter given when planning (max_heart_rate, threshold_heart_rate, ftp or threshold_speed)."},"WorkoutStepTargetType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"speed"},{"type":"string","const":"heart_rate"},{"type":"string","const":"open"},{"type":"string","const":"cadence"},{"type":"string","const":"power"},{"type":"string","const":"swim_stroke"},{"type":"string","const":"speed_lap"},{"type":"string","const":"heart_rate_lap"},{"type":"string","const":"pace"},{"type":"string","const":"heart_rate_threshold_percentage"},{"type":"string","const":"heart_rate_max_percentage"},{"type":"string","const":"speed_percentage"},{"type":"string","const":"power_percentage"},{"type":"string","const":"repetition"},{"type":"string","const":"tss"},{"type":"string","const":"if"},{"type":"string","const":"rpe"},{"type":"string","const":"heart_rate_zone"},{"type":"string","const":"power_zone"}],"description":"Quantity an intensity target constrains"},"WorkoutStepIntensity":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"rest"},{"type":"string","const":"warmup"},{"type":"string","const":"cooldown"},{"type":"string","const":"recovery"},{"type":"string","const":"active"}],"description":"Intensity classification of a workout step"},"StepControl":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"$ref":"#/components/schemas/StepControlType"},"value":{"type":"number","description":"Control value (e.g. 0.02 for a 2% treadmill grade)"}},"required":["type","value"],"description":"Equipment control applied during a step"},"StepControlType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"grade"},{"type":"string","const":"resistance"}],"description":"Equipment control adjusted during a step (e.g. treadmill incline)"},"StrengthData":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"exercise_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display name of the exercise"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Weight to lift"},"weight_display_unit":{"anyOf":[{"$ref":"#/components/schemas/WeightUnit"},{"type":"null"}]},"exercise_category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Garmin Training API exerciseCategory string (e.g. BENCH_PRESS, SQUAT)"}},"description":"Strength-exercise details for a step"},"WeightUnit":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"kg"},{"type":"string","const":"lbs"}],"description":"Weight display unit for strength exercises"},"SwimStepData":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"stroke_type":{"anyOf":[{"$ref":"#/components/schemas/SwimStrokeType"},{"type":"null"}]},"drill_type":{"anyOf":[{"$ref":"#/components/schemas/DrillType"},{"type":"null"}]},"equipment":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/SwimEquipmentType"}},{"type":"null"}]}},"description":"Swimming details for a step"},"SwimStrokeType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"backstroke"},{"type":"string","const":"breaststroke"},{"type":"string","const":"drill"},{"type":"string","const":"butterfly"},{"type":"string","const":"freestyle"},{"type":"string","const":"mixed"},{"type":"string","const":"im"}],"description":"Swim stroke for a swimming step"},"DrillType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"kick"},{"type":"string","const":"pull"},{"type":"string","const":"drill"}],"description":"Swim drill type"},"SwimEquipmentType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"none"},{"type":"string","const":"swim_fins"},{"type":"string","const":"swim_kickboard"},{"type":"string","const":"swim_paddles"},{"type":"string","const":"swim_pull_buoy"},{"type":"string","const":"swim_snorkel"}],"description":"Swim equipment used during a step"},"PlannedWorkoutSport":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"$ref":"#/components/schemas/WorkoutSport"},{"type":"string","const":"unspecified"}],"description":"Sport of a provider-created workout: a WorkoutSport, or `unspecified` when the provider's sport has no Terra equivalent (rejected on create)."},"WorkoutSport":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"running"},{"type":"string","const":"cycling"},{"type":"string","const":"swimming"},{"type":"string","const":"strength"},{"type":"string","const":"rowing"},{"type":"string","const":"yoga"},{"type":"string","const":"pilates"},{"type":"string","const":"cardio"},{"type":"string","const":"trail_running"},{"type":"string","const":"mountain_biking"},{"type":"string","const":"backcountry_skiing"},{"type":"string","const":"hiking"},{"type":"string","const":"walking"},{"type":"string","const":"elliptical"},{"type":"string","const":"stair_climbing"}],"description":"Sport a workout template targets. Indoor/outdoor is expressed separately via environment."},"PlannedWorkoutDetails":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"metadata":{"anyOf":[{"$ref":"#/components/schemas/PlannedWorkoutDetailsMetadata"},{"type":"null"}]},"steps":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/PlannedWorkoutDetailsStep"}},{"type":"null"}],"description":"Structured steps of the workout, when the provider exposes them"}},"description":"Full body of a provider-side planned workout, fetched live from the provider. Present only on external planned workouts (is_external true), which have no Terra workout template."},"PlannedWorkoutDetailsMetadata":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Identifier of the workout on the provider's side"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Provider the workout was fetched from"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Workout title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Workout description, when the provider exposes one"},"type":{"anyOf":[{"type":"integer","minimum":-2147483648,"maximum":2147483647},{"type":"null"}],"description":"Numeric activity type of the workout"},"planned_date":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Scheduled date (YYYY-MM-DD), matching the list item's planned_date"},"created_date":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Creation time on the provider's side (RFC 3339)"},"estimated_tss":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Planned Training Stress Score"},"estimated_if":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Planned Intensity Factor"},"estimated_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"estimated_distance_meters":{"anyOf":[{"type":"number"},{"type":"null"}]},"estimated_calories":{"anyOf":[{"type":"number"},{"type":"null"}]},"estimated_elevation_gain_meters":{"anyOf":[{"type":"number"},{"type":"null"}]},"estimated_energy_kj":{"anyOf":[{"type":"number"},{"type":"null"}]},"estimated_speed_meters_per_second":{"anyOf":[{"type":"number"},{"type":"null"}]},"pool_length_meters":{"anyOf":[{"type":"number"},{"type":"null"}]}},"description":"Summary metadata of a provider-side planned workout"},"PlannedWorkoutDetailsStep":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"order":{"anyOf":[{"type":"integer","minimum":-2147483648,"maximum":2147483647},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"intensity":{"anyOf":[{"type":"integer","minimum":-2147483648,"maximum":2147483647},{"type":"null"}],"description":"Numeric step intensity class"},"type":{"anyOf":[{"type":"integer","minimum":-2147483648,"maximum":2147483647},{"type":"null"}],"description":"0 = step, 1 = repetition block"},"durations":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/PlannedWorkoutDetailsStepDuration"}},{"type":"null"}]},"targets":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/PlannedWorkoutDetailsStepTarget"}},{"type":"null"}]},"stroke_type":{"anyOf":[{"type":"integer","minimum":-2147483648,"maximum":2147483647},{"type":"null"}]},"equipment_type":{"anyOf":[{"type":"array","items":{"type":"integer","minimum":-2147483648,"maximum":2147483647}},{"type":"null"}]},"exercise_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"exercise_category":{"anyOf":[{"type":"integer","minimum":-2147483648,"maximum":2147483647},{"type":"null"}]},"weight_kg":{"anyOf":[{"type":"number"},{"type":"null"}]},"steps":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/PlannedWorkoutDetailsStep"}},{"type":"null"}],"description":"Child steps of a repetition block"}},"description":"A step of a provider-side planned workout"},"PlannedWorkoutDetailsStepDuration":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"duration_type":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"seconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"distance_meters":{"anyOf":[{"type":"number"},{"type":"null"}]},"hr_below_bpm":{"anyOf":[{"type":"number"},{"type":"null"}]},"hr_above_bpm":{"anyOf":[{"type":"number"},{"type":"null"}]},"calories":{"anyOf":[{"type":"number"},{"type":"null"}]},"power_below_watts":{"anyOf":[{"type":"number"},{"type":"null"}]},"power_above_watts":{"anyOf":[{"type":"number"},{"type":"null"}]},"reps":{"anyOf":[{"type":"number"},{"type":"null"}]},"rest_seconds":{"anyOf":[{"type":"number"},{"type":"null"}]},"steps":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["duration_type"],"description":"Completion condition of a provider planned-workout step"},"PlannedWorkoutDetailsStepTarget":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"target_type":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"hr_bpm_high":{"anyOf":[{"type":"number"},{"type":"null"}]},"hr_bpm_low":{"anyOf":[{"type":"number"},{"type":"null"}]},"cadence":{"anyOf":[{"type":"number"},{"type":"null"}]},"cadence_high":{"anyOf":[{"type":"number"},{"type":"null"}]},"cadence_low":{"anyOf":[{"type":"number"},{"type":"null"}]},"power_watt":{"anyOf":[{"type":"number"},{"type":"null"}]},"power_watt_high":{"anyOf":[{"type":"number"},{"type":"null"}]},"power_watt_low":{"anyOf":[{"type":"number"},{"type":"null"}]},"swim_strokes":{"anyOf":[{"type":"number"},{"type":"null"}]},"hr_percentage":{"anyOf":[{"type":"number"},{"type":"null"}]},"hr_percentage_high":{"anyOf":[{"type":"number"},{"type":"null"}]},"hr_percentage_low":{"anyOf":[{"type":"number"},{"type":"null"}]},"speed_percentage":{"anyOf":[{"type":"number"},{"type":"null"}]},"speed_percentage_high":{"anyOf":[{"type":"number"},{"type":"null"}]},"speed_percentage_low":{"anyOf":[{"type":"number"},{"type":"null"}]},"power_percentage":{"anyOf":[{"type":"number"},{"type":"null"}]},"power_percentage_high":{"anyOf":[{"type":"number"},{"type":"null"}]},"power_percentage_low":{"anyOf":[{"type":"number"},{"type":"null"}]},"repetitions":{"anyOf":[{"type":"integer","minimum":-2147483648,"maximum":2147483647},{"type":"null"}]},"speed_meters_per_second":{"anyOf":[{"type":"number"},{"type":"null"}]},"speed_meters_per_second_low":{"anyOf":[{"type":"number"},{"type":"null"}]},"speed_meters_per_second_high":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["target_type"],"description":"Intensity target of a provider planned-workout step"},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"UnauthorizedProblem":{"type":"object","description":"A refused credential, always with its code.","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance","code"]}},"responses":{"BadRequest":{"description":"One or more parameters is malformed. The `detail` field describes the specific problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"The credential is missing, invalid, expired or revoked (code `unauthorized`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedProblem"}}}},"Forbidden":{"description":"The credential is not authorized (code scope_missing or audience_restricted), the environment is disabled (environment_disabled), or the required product entitlement is missing (entitlement_required).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"A referenced resource does not exist on Terra's end.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"AuthorizationUnavailable":{"description":"The credential or the product access could not be checked (code `authorization_unavailable`). Retry after the service recovers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/plannedWorkouts":{"get":{"tags":["PlannedWorkouts"],"summary":"List planned workouts","description":"Returns the user's planned workouts, including those created on the provider side (`is_external` true) where the provider exposes them.\n\n- Provider-side workouts are read live from the provider, not stored by Terra.\n- A workout pushed through Terra and echoed back by the provider is listed once, as the Terra-created one.\n- If the provider cannot be read, the response is still 200, with Terra's workouts and `X-Terra-Provider-Data-Truncated: true`.\n- Providers may limit how far ahead planned workouts are visible.","operationId":"Workouts_ListPlannedWorkouts","parameters":[{"name":"user_id","in":"query","required":true,"schema":{"type":"string"},"description":"The Terra user ID of the connection whose planned workouts to list."},{"name":"start_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"First planned date to include (`YYYY-MM-DD`), inclusive; applies only together with `end_date`. Without both, Terra-created workouts are listed for every date and provider-side workouts for the trailing 30 days, so pass a window to list upcoming workouts."},{"name":"end_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Last planned date to include (`YYYY-MM-DD`), inclusive; applies only together with `start_date`."}],"responses":{"200":{"description":"Planned workouts for the connection","headers":{"X-Terra-Provider-Data-Truncated":{"schema":{"type":"string","enum":["true"]},"description":"Present when provider-side workouts could not be included; X-Terra-Provider-Fetch says why."},"X-Terra-Provider-Fetch":{"schema":{"type":"string","enum":["ok","skipped","rate_limited","unauthorized","unavailable","timeout","failed"]},"description":"Outcome of the live provider read. `skipped` means the provider does not expose planned workouts or the add-on is not enabled."}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PlannedWorkout"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"}}}}}}
```

## Get a planned workout

> Returns a planned workout created through Terra.\
> \
> \- Provider-created (external) workouts are not addressable by ID and return 404 here; \`GET /plannedWorkouts\` lists them with their body under \`workout\`.

```json
{"openapi":"3.2.0","info":{"title":"Terra API","version":"2026.11.19"},"tags":[{"name":"PlannedWorkouts","summary":"Planned Workouts","description":"Workout templates, and the planned workouts that put them on a user's calendar."}],"servers":[{"url":"https://access.tryterra.co/api/v2"}],"security":[{"ApiKeyAuth":[],"DevID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key for authentication"},"DevID":{"type":"apiKey","in":"header","name":"dev-id","description":"Your developer ID for authentication and tracking"}},"schemas":{"PlannedWorkoutSummary":{"type":"object","description":"Summary of a planned workout, returned by the get and reschedule operations.","properties":{"planned_workout_id":{"type":"string"},"planned_date":{"type":"string","format":"date"},"is_external":{"type":"boolean","description":"True when the workout was created on the provider side rather than through Terra."},"workout_id":{"type":"string","description":"Identifier of the source template. Absent for external workouts."},"provider_workout_id":{"type":"string","description":"Identifier assigned by the provider, once pushed."},"coercion_warnings":{"type":"string","deprecated":true,"description":"Deprecated; use warnings. Set when the template could not be represented exactly on the provider."},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Time the session was reported complete by the user's device. Null until a device reports it."},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/CoercionWarning"},"description":"Adjustments made when the template could not be represented exactly on the provider. Empty when the push was exact."},"workout":{"anyOf":[{"$ref":"#/components/schemas/PlannedWorkoutBody"},{"type":"null"}],"description":"The workout body, as on the list. Null when the planned workout has no stored template or it could not be loaded."}}},"CoercionWarning":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"path":{"type":"string","description":"JSON path within the workout template of the element that could not be represented exactly"},"message":{"type":"string","description":"What was changed or dropped, and why"}},"required":["path","message"],"description":"A non-fatal adjustment made while converting a workout between Terra's template model and a provider's"},"PlannedWorkoutBody":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","description":"Name of the workout"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description of the workout"},"environment":{"anyOf":[{"$ref":"#/components/schemas/EnvironmentType"},{"type":"null"}]},"pool_length_meters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Pool length in meters, for swim workouts"},"step_blocks":{"type":"array","items":{"$ref":"#/components/schemas/StepBlock"}},"estimated_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated total duration in seconds"},"estimated_distance_meters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated total distance in meters"},"estimated_calories":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated calories burned"},"estimated_tss":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Planned training stress score (0-9999), where the provider or author supplies one. Forwarded to TrainingPeaks, which ignores it when any step target is not RPE and derives it from the structure instead."},"estimated_intensity_factor":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Planned intensity factor (0-5), where the provider or author supplies one. Forwarded to TrainingPeaks, which ignores it when any step target is not RPE and derives it from the structure instead."},"workout_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Terra identifier of the stored template. Set by Terra in responses; ignored on create."},"sport":{"$ref":"#/components/schemas/PlannedWorkoutSport"}},"required":["name","step_blocks","sport"],"description":"The body of a planned workout: a WorkoutTemplate whose sport may be `unspecified` when it was created on the provider side"},"EnvironmentType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"indoor"},{"type":"string","const":"outdoor"},{"type":"string","const":"pool"}],"description":"Environment a workout takes place in"},"StepBlock":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"completion_condition":{"$ref":"#/components/schemas/CompletionCondition","description":"When this block completes (e.g. repeat count via reps)"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/WorkoutStep"}}},"required":["completion_condition","steps"],"description":"A block of steps, repeated until its completion condition is met"},"CompletionCondition":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"$ref":"#/components/schemas/CompletionConditionType"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Single value for the condition (e.g. seconds for time, meters for distance)"},"value_low":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lower bound when the condition is a range"},"value_high":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Upper bound when the condition is a range"}},"required":["type"],"description":"Condition that completes a step or repeats a step block"},"CompletionConditionType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"time"},{"type":"string","const":"distance"},{"type":"string","const":"hr"},{"type":"string","const":"calories"},{"type":"string","const":"open"},{"type":"string","const":"power"},{"type":"string","const":"reps"},{"type":"string","const":"hr_percentage"},{"type":"string","const":"power_percentage"},{"type":"string","const":"hr_less_than"},{"type":"string","const":"hr_greater_than"},{"type":"string","const":"hr_percentage_less_than"},{"type":"string","const":"hr_percentage_greater_than"},{"type":"string","const":"power_less_than"},{"type":"string","const":"power_greater_than"},{"type":"string","const":"power_percentage_less_than"},{"type":"string","const":"power_percentage_greater_than"}],"description":"How a step or block is considered complete"},"WorkoutStep":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"completion_condition":{"$ref":"#/components/schemas/CompletionCondition","description":"When this step completes"},"intensity_targets":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/IntensityTarget"}},{"type":"null"}],"description":"Intensity targets to hold during the step"},"intensity_type":{"$ref":"#/components/schemas/WorkoutStepIntensity"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Free-text coaching notes shown to the athlete"},"controls":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/StepControl"}},{"type":"null"}],"description":"Equipment controls applied during the step"},"strength":{"anyOf":[{"$ref":"#/components/schemas/StrengthData"},{"type":"null"}]},"swimming":{"anyOf":[{"$ref":"#/components/schemas/SwimStepData"},{"type":"null"}]}},"required":["completion_condition","intensity_type"],"description":"A single step within a step block"},"IntensityTarget":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"target_type":{"$ref":"#/components/schemas/WorkoutStepTargetType"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Single target value, in the unit for target_type"},"value_low":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lower bound of the target range, in the unit for target_type. For pace, the lower number is the faster pace"},"value_high":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Upper bound of the target range, in the unit for target_type"}},"required":["target_type"],"description":"Target intensity range for a step (e.g. heart-rate or power zone). The unit of value, value_low and value_high depends on target_type: heart_rate in BPM; power in watts; speed in metres per second; pace in seconds per kilometre for every sport, swimming included, so 4:30/km is 270, not 4.5, and 1:30 per 100 m is 900, not 90; cadence in rpm or steps per minute; rpe from 1 to 10; heart_rate_zone (1-5) and power_zone (1-7) as zone numbers; the *_percentage types in percent of the athlete parameter given when planning (max_heart_rate, threshold_heart_rate, ftp or threshold_speed)."},"WorkoutStepTargetType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"speed"},{"type":"string","const":"heart_rate"},{"type":"string","const":"open"},{"type":"string","const":"cadence"},{"type":"string","const":"power"},{"type":"string","const":"swim_stroke"},{"type":"string","const":"speed_lap"},{"type":"string","const":"heart_rate_lap"},{"type":"string","const":"pace"},{"type":"string","const":"heart_rate_threshold_percentage"},{"type":"string","const":"heart_rate_max_percentage"},{"type":"string","const":"speed_percentage"},{"type":"string","const":"power_percentage"},{"type":"string","const":"repetition"},{"type":"string","const":"tss"},{"type":"string","const":"if"},{"type":"string","const":"rpe"},{"type":"string","const":"heart_rate_zone"},{"type":"string","const":"power_zone"}],"description":"Quantity an intensity target constrains"},"WorkoutStepIntensity":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"rest"},{"type":"string","const":"warmup"},{"type":"string","const":"cooldown"},{"type":"string","const":"recovery"},{"type":"string","const":"active"}],"description":"Intensity classification of a workout step"},"StepControl":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"$ref":"#/components/schemas/StepControlType"},"value":{"type":"number","description":"Control value (e.g. 0.02 for a 2% treadmill grade)"}},"required":["type","value"],"description":"Equipment control applied during a step"},"StepControlType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"grade"},{"type":"string","const":"resistance"}],"description":"Equipment control adjusted during a step (e.g. treadmill incline)"},"StrengthData":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"exercise_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display name of the exercise"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Weight to lift"},"weight_display_unit":{"anyOf":[{"$ref":"#/components/schemas/WeightUnit"},{"type":"null"}]},"exercise_category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Garmin Training API exerciseCategory string (e.g. BENCH_PRESS, SQUAT)"}},"description":"Strength-exercise details for a step"},"WeightUnit":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"kg"},{"type":"string","const":"lbs"}],"description":"Weight display unit for strength exercises"},"SwimStepData":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"stroke_type":{"anyOf":[{"$ref":"#/components/schemas/SwimStrokeType"},{"type":"null"}]},"drill_type":{"anyOf":[{"$ref":"#/components/schemas/DrillType"},{"type":"null"}]},"equipment":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/SwimEquipmentType"}},{"type":"null"}]}},"description":"Swimming details for a step"},"SwimStrokeType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"backstroke"},{"type":"string","const":"breaststroke"},{"type":"string","const":"drill"},{"type":"string","const":"butterfly"},{"type":"string","const":"freestyle"},{"type":"string","const":"mixed"},{"type":"string","const":"im"}],"description":"Swim stroke for a swimming step"},"DrillType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"kick"},{"type":"string","const":"pull"},{"type":"string","const":"drill"}],"description":"Swim drill type"},"SwimEquipmentType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"none"},{"type":"string","const":"swim_fins"},{"type":"string","const":"swim_kickboard"},{"type":"string","const":"swim_paddles"},{"type":"string","const":"swim_pull_buoy"},{"type":"string","const":"swim_snorkel"}],"description":"Swim equipment used during a step"},"PlannedWorkoutSport":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"$ref":"#/components/schemas/WorkoutSport"},{"type":"string","const":"unspecified"}],"description":"Sport of a provider-created workout: a WorkoutSport, or `unspecified` when the provider's sport has no Terra equivalent (rejected on create)."},"WorkoutSport":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"running"},{"type":"string","const":"cycling"},{"type":"string","const":"swimming"},{"type":"string","const":"strength"},{"type":"string","const":"rowing"},{"type":"string","const":"yoga"},{"type":"string","const":"pilates"},{"type":"string","const":"cardio"},{"type":"string","const":"trail_running"},{"type":"string","const":"mountain_biking"},{"type":"string","const":"backcountry_skiing"},{"type":"string","const":"hiking"},{"type":"string","const":"walking"},{"type":"string","const":"elliptical"},{"type":"string","const":"stair_climbing"}],"description":"Sport a workout template targets. Indoor/outdoor is expressed separately via environment."},"UnauthorizedProblem":{"type":"object","description":"A refused credential, always with its code.","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance","code"]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]}},"responses":{"Unauthorized":{"description":"The credential is missing, invalid, expired or revoked (code `unauthorized`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedProblem"}}}},"Forbidden":{"description":"The credential is not authorized (code scope_missing or audience_restricted), the environment is disabled (environment_disabled), or the required product entitlement is missing (entitlement_required).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"A referenced resource does not exist on Terra's end.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"AuthorizationUnavailable":{"description":"The credential or the product access could not be checked (code `authorization_unavailable`). Retry after the service recovers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/plannedWorkouts/{planned_workout_id}":{"get":{"tags":["PlannedWorkouts"],"summary":"Get a planned workout","description":"Returns a planned workout created through Terra.\n\n- Provider-created (external) workouts are not addressable by ID and return 404 here; `GET /plannedWorkouts` lists them with their body under `workout`.","operationId":"Workouts_GetPlannedWorkout","parameters":[{"name":"planned_workout_id","in":"path","required":true,"schema":{"type":"integer","format":"int64"},"description":"The planned workout's ID, as returned by `POST /workouts/{workout_id}/plan`."},{"name":"user_id","in":"query","required":true,"schema":{"type":"string"},"description":"The Terra user ID of the connection the planned workout belongs to."}],"responses":{"200":{"description":"The planned workout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlannedWorkoutSummary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"}}}}}}
```

## Delete a planned workout

> Deletes a planned workout from the user's calendar and removes it from the connected provider.

```json
{"openapi":"3.2.0","info":{"title":"Terra API","version":"2026.11.19"},"tags":[{"name":"PlannedWorkouts","summary":"Planned Workouts","description":"Workout templates, and the planned workouts that put them on a user's calendar."}],"servers":[{"url":"https://access.tryterra.co/api/v2"}],"security":[{"ApiKeyAuth":[],"DevID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key for authentication"},"DevID":{"type":"apiKey","in":"header","name":"dev-id","description":"Your developer ID for authentication and tracking"}},"responses":{"Unauthorized":{"description":"The credential is missing, invalid, expired or revoked (code `unauthorized`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedProblem"}}}},"NotFound":{"description":"A referenced resource does not exist on Terra's end.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"AuthorizationUnavailable":{"description":"The credential or the product access could not be checked (code `authorization_unavailable`). Retry after the service recovers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"UnauthorizedProblem":{"type":"object","description":"A refused credential, always with its code.","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance","code"]},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]}}},"paths":{"/plannedWorkouts/{planned_workout_id}":{"delete":{"tags":["PlannedWorkouts"],"summary":"Delete a planned workout","description":"Deletes a planned workout from the user's calendar and removes it from the connected provider.","operationId":"Workouts_DeletePlannedWorkout","parameters":[{"name":"planned_workout_id","in":"path","required":true,"schema":{"type":"integer","format":"int64"},"description":"The planned workout's ID, as returned by `POST /workouts/{workout_id}/plan`."},{"name":"user_id","in":"query","required":true,"schema":{"type":"string"},"description":"The Terra user ID of the connection the planned workout belongs to."}],"responses":{"204":{"description":"Planned workout deleted"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"}}}}}}
```

## Reschedule a planned workout

> Moves a planned workout to a new \`planned\_date\` and returns it.\
> \
> \- A workout already pushed to a provider is re-sent there under its existing provider ID, and the re-send is billed.\
> \- An Apple Health planned workout is queued for the device to fetch the new date.

```json
{"openapi":"3.2.0","info":{"title":"Terra API","version":"2026.11.19"},"tags":[{"name":"PlannedWorkouts","summary":"Planned Workouts","description":"Workout templates, and the planned workouts that put them on a user's calendar."}],"servers":[{"url":"https://access.tryterra.co/api/v2"}],"security":[{"ApiKeyAuth":[],"DevID":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key for authentication"},"DevID":{"type":"apiKey","in":"header","name":"dev-id","description":"Your developer ID for authentication and tracking"}},"schemas":{"PlannedWorkoutSummary":{"type":"object","description":"Summary of a planned workout, returned by the get and reschedule operations.","properties":{"planned_workout_id":{"type":"string"},"planned_date":{"type":"string","format":"date"},"is_external":{"type":"boolean","description":"True when the workout was created on the provider side rather than through Terra."},"workout_id":{"type":"string","description":"Identifier of the source template. Absent for external workouts."},"provider_workout_id":{"type":"string","description":"Identifier assigned by the provider, once pushed."},"coercion_warnings":{"type":"string","deprecated":true,"description":"Deprecated; use warnings. Set when the template could not be represented exactly on the provider."},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Time the session was reported complete by the user's device. Null until a device reports it."},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/CoercionWarning"},"description":"Adjustments made when the template could not be represented exactly on the provider. Empty when the push was exact."},"workout":{"anyOf":[{"$ref":"#/components/schemas/PlannedWorkoutBody"},{"type":"null"}],"description":"The workout body, as on the list. Null when the planned workout has no stored template or it could not be loaded."}}},"CoercionWarning":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"path":{"type":"string","description":"JSON path within the workout template of the element that could not be represented exactly"},"message":{"type":"string","description":"What was changed or dropped, and why"}},"required":["path","message"],"description":"A non-fatal adjustment made while converting a workout between Terra's template model and a provider's"},"PlannedWorkoutBody":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","description":"Name of the workout"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Description of the workout"},"environment":{"anyOf":[{"$ref":"#/components/schemas/EnvironmentType"},{"type":"null"}]},"pool_length_meters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Pool length in meters, for swim workouts"},"step_blocks":{"type":"array","items":{"$ref":"#/components/schemas/StepBlock"}},"estimated_duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated total duration in seconds"},"estimated_distance_meters":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated total distance in meters"},"estimated_calories":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Estimated calories burned"},"estimated_tss":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Planned training stress score (0-9999), where the provider or author supplies one. Forwarded to TrainingPeaks, which ignores it when any step target is not RPE and derives it from the structure instead."},"estimated_intensity_factor":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Planned intensity factor (0-5), where the provider or author supplies one. Forwarded to TrainingPeaks, which ignores it when any step target is not RPE and derives it from the structure instead."},"workout_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Terra identifier of the stored template. Set by Terra in responses; ignored on create."},"sport":{"$ref":"#/components/schemas/PlannedWorkoutSport"}},"required":["name","step_blocks","sport"],"description":"The body of a planned workout: a WorkoutTemplate whose sport may be `unspecified` when it was created on the provider side"},"EnvironmentType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"indoor"},{"type":"string","const":"outdoor"},{"type":"string","const":"pool"}],"description":"Environment a workout takes place in"},"StepBlock":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"completion_condition":{"$ref":"#/components/schemas/CompletionCondition","description":"When this block completes (e.g. repeat count via reps)"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/WorkoutStep"}}},"required":["completion_condition","steps"],"description":"A block of steps, repeated until its completion condition is met"},"CompletionCondition":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"$ref":"#/components/schemas/CompletionConditionType"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Single value for the condition (e.g. seconds for time, meters for distance)"},"value_low":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lower bound when the condition is a range"},"value_high":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Upper bound when the condition is a range"}},"required":["type"],"description":"Condition that completes a step or repeats a step block"},"CompletionConditionType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"time"},{"type":"string","const":"distance"},{"type":"string","const":"hr"},{"type":"string","const":"calories"},{"type":"string","const":"open"},{"type":"string","const":"power"},{"type":"string","const":"reps"},{"type":"string","const":"hr_percentage"},{"type":"string","const":"power_percentage"},{"type":"string","const":"hr_less_than"},{"type":"string","const":"hr_greater_than"},{"type":"string","const":"hr_percentage_less_than"},{"type":"string","const":"hr_percentage_greater_than"},{"type":"string","const":"power_less_than"},{"type":"string","const":"power_greater_than"},{"type":"string","const":"power_percentage_less_than"},{"type":"string","const":"power_percentage_greater_than"}],"description":"How a step or block is considered complete"},"WorkoutStep":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"completion_condition":{"$ref":"#/components/schemas/CompletionCondition","description":"When this step completes"},"intensity_targets":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/IntensityTarget"}},{"type":"null"}],"description":"Intensity targets to hold during the step"},"intensity_type":{"$ref":"#/components/schemas/WorkoutStepIntensity"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Free-text coaching notes shown to the athlete"},"controls":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/StepControl"}},{"type":"null"}],"description":"Equipment controls applied during the step"},"strength":{"anyOf":[{"$ref":"#/components/schemas/StrengthData"},{"type":"null"}]},"swimming":{"anyOf":[{"$ref":"#/components/schemas/SwimStepData"},{"type":"null"}]}},"required":["completion_condition","intensity_type"],"description":"A single step within a step block"},"IntensityTarget":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"target_type":{"$ref":"#/components/schemas/WorkoutStepTargetType"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Single target value, in the unit for target_type"},"value_low":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Lower bound of the target range, in the unit for target_type. For pace, the lower number is the faster pace"},"value_high":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Upper bound of the target range, in the unit for target_type"}},"required":["target_type"],"description":"Target intensity range for a step (e.g. heart-rate or power zone). The unit of value, value_low and value_high depends on target_type: heart_rate in BPM; power in watts; speed in metres per second; pace in seconds per kilometre for every sport, swimming included, so 4:30/km is 270, not 4.5, and 1:30 per 100 m is 900, not 90; cadence in rpm or steps per minute; rpe from 1 to 10; heart_rate_zone (1-5) and power_zone (1-7) as zone numbers; the *_percentage types in percent of the athlete parameter given when planning (max_heart_rate, threshold_heart_rate, ftp or threshold_speed)."},"WorkoutStepTargetType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"speed"},{"type":"string","const":"heart_rate"},{"type":"string","const":"open"},{"type":"string","const":"cadence"},{"type":"string","const":"power"},{"type":"string","const":"swim_stroke"},{"type":"string","const":"speed_lap"},{"type":"string","const":"heart_rate_lap"},{"type":"string","const":"pace"},{"type":"string","const":"heart_rate_threshold_percentage"},{"type":"string","const":"heart_rate_max_percentage"},{"type":"string","const":"speed_percentage"},{"type":"string","const":"power_percentage"},{"type":"string","const":"repetition"},{"type":"string","const":"tss"},{"type":"string","const":"if"},{"type":"string","const":"rpe"},{"type":"string","const":"heart_rate_zone"},{"type":"string","const":"power_zone"}],"description":"Quantity an intensity target constrains"},"WorkoutStepIntensity":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"rest"},{"type":"string","const":"warmup"},{"type":"string","const":"cooldown"},{"type":"string","const":"recovery"},{"type":"string","const":"active"}],"description":"Intensity classification of a workout step"},"StepControl":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"type":{"$ref":"#/components/schemas/StepControlType"},"value":{"type":"number","description":"Control value (e.g. 0.02 for a 2% treadmill grade)"}},"required":["type","value"],"description":"Equipment control applied during a step"},"StepControlType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"grade"},{"type":"string","const":"resistance"}],"description":"Equipment control adjusted during a step (e.g. treadmill incline)"},"StrengthData":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"exercise_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Display name of the exercise"},"weight":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Weight to lift"},"weight_display_unit":{"anyOf":[{"$ref":"#/components/schemas/WeightUnit"},{"type":"null"}]},"exercise_category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Garmin Training API exerciseCategory string (e.g. BENCH_PRESS, SQUAT)"}},"description":"Strength-exercise details for a step"},"WeightUnit":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"kg"},{"type":"string","const":"lbs"}],"description":"Weight display unit for strength exercises"},"SwimStepData":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"stroke_type":{"anyOf":[{"$ref":"#/components/schemas/SwimStrokeType"},{"type":"null"}]},"drill_type":{"anyOf":[{"$ref":"#/components/schemas/DrillType"},{"type":"null"}]},"equipment":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/SwimEquipmentType"}},{"type":"null"}]}},"description":"Swimming details for a step"},"SwimStrokeType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"backstroke"},{"type":"string","const":"breaststroke"},{"type":"string","const":"drill"},{"type":"string","const":"butterfly"},{"type":"string","const":"freestyle"},{"type":"string","const":"mixed"},{"type":"string","const":"im"}],"description":"Swim stroke for a swimming step"},"DrillType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"kick"},{"type":"string","const":"pull"},{"type":"string","const":"drill"}],"description":"Swim drill type"},"SwimEquipmentType":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"none"},{"type":"string","const":"swim_fins"},{"type":"string","const":"swim_kickboard"},{"type":"string","const":"swim_paddles"},{"type":"string","const":"swim_pull_buoy"},{"type":"string","const":"swim_snorkel"}],"description":"Swim equipment used during a step"},"PlannedWorkoutSport":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"$ref":"#/components/schemas/WorkoutSport"},{"type":"string","const":"unspecified"}],"description":"Sport of a provider-created workout: a WorkoutSport, or `unspecified` when the provider's sport has no Terra equivalent (rejected on create)."},"WorkoutSport":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"string","const":"running"},{"type":"string","const":"cycling"},{"type":"string","const":"swimming"},{"type":"string","const":"strength"},{"type":"string","const":"rowing"},{"type":"string","const":"yoga"},{"type":"string","const":"pilates"},{"type":"string","const":"cardio"},{"type":"string","const":"trail_running"},{"type":"string","const":"mountain_biking"},{"type":"string","const":"backcountry_skiing"},{"type":"string","const":"hiking"},{"type":"string","const":"walking"},{"type":"string","const":"elliptical"},{"type":"string","const":"stair_climbing"}],"description":"Sport a workout template targets. Indoor/outdoor is expressed separately via environment."},"Problem":{"type":"object","description":"An error response, following RFC 9457 (Problem Details for HTTP APIs, which obsoletes RFC 7807). Returned with `Content-Type: application/problem+json` on every 4xx/5xx response. The HTTP status line carries the status code; it is intentionally not repeated in the body. `type`, `title` and `instance` are always present; `detail` is included when a specific explanation is available.\n","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance"]},"UnauthorizedProblem":{"type":"object","description":"A refused credential, always with its code.","properties":{"type":{"type":"string","description":"A URI reference identifying the problem type. Defaults to `about:blank`."},"title":{"type":"string","description":"A short, human-readable summary of the problem type (the lowercased HTTP status text)."},"instance":{"type":"string","description":"The request path, including any query string, that produced this problem."},"code":{"type":"string","description":"Stable error classification: branch on this, not on `detail`. A refused credential returns unauthorized (401: missing, invalid, expired or revoked), scope_missing (403: the credential lacks the scope the operation requires) or audience_restricted (403: the credential is not granted for this dev-id). authorization_unavailable (503) means the credential or the product access could not be checked; retry later. Product gates return entitlement_required (403) or environment_disabled (403). service_unavailable (503) means the request never reached the service; dependency_failed (502 or 504) means the service did not complete it, though it may already have acted on it. Report uploads return validation_failed, unsupported_file_type or too_many_files (400), payload_too_large (413) and rate_limited (429)."},"product":{"type":"string","description":"The product checked by the authorization gate, when classified."},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem."}},"required":["type","title","instance","code"]}},"responses":{"BadRequest":{"description":"One or more parameters is malformed. The `detail` field describes the specific problem.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"The credential is missing, invalid, expired or revoked (code `unauthorized`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/UnauthorizedProblem"}}}},"NotFound":{"description":"A referenced resource does not exist on Terra's end.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"AuthorizationUnavailable":{"description":"The credential or the product access could not be checked (code `authorization_unavailable`). Retry after the service recovers.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/plannedWorkouts/{planned_workout_id}":{"patch":{"tags":["PlannedWorkouts"],"summary":"Reschedule a planned workout","description":"Moves a planned workout to a new `planned_date` and returns it.\n\n- A workout already pushed to a provider is re-sent there under its existing provider ID, and the re-send is billed.\n- An Apple Health planned workout is queued for the device to fetch the new date.","operationId":"Workouts_UpdatePlannedWorkout","parameters":[{"name":"planned_workout_id","in":"path","required":true,"schema":{"type":"integer","format":"int64"},"description":"The planned workout's ID, as returned by `POST /workouts/{workout_id}/plan`."},{"name":"user_id","in":"query","required":true,"schema":{"type":"string"},"description":"The Terra user ID of the connection the planned workout belongs to."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["planned_date"],"properties":{"planned_date":{"type":"string","format":"date","description":"New scheduled date (YYYY-MM-DD)"}}}}}},"responses":{"200":{"description":"Updated planned workout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlannedWorkoutSummary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The Planned Workouts add-on is not enabled for this account.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"$ref":"#/components/responses/NotFound"},"503":{"$ref":"#/components/responses/AuthorizationUnavailable"}}}}}}
```
