API Reference (pre-release)
⚠️ Pre-Release / Under Construction
This page is currently under active development and is provided in a pre-release state.
Content may be incomplete, outdated, or inaccurate, and details may change without notice as the implementation evolves.
Please use this documentation for early reference only, and avoid relying on it for production-critical decisions until the page is marked as stable.
Workout Templates
Create Workout Template
POST https://api.tryterra.co/v2/workouts
Creates a reusable workout template that can be pushed to multiple users.
Headers
dev-id
string
Yes
Your development ID
x-api-key
string
Yes
Your API key
Content-Type
string
Yes
Must be application/json
Request Body
Base structure (all workouts):
{
"workout_template": {
"name": "string",
"sport": "string",
"description": "string",
"environment": "string",
"step_blocks": [
{
"completion_condition": {
"type": "string",
"value": "float"
},
"steps": [
{
"order": "integer",
"duration_type": "string",
"duration_value": "float",
"intensity_type": "string",
"intensity_targets": [
{
"target_type": "string",
"value": "float",
"value_low": "float",
"value_high": "float"
}
],
"notes": "string"
}
]
}
]
}
}Additional fields for swimming workouts:
Additional fields for strength workouts:
Field Specifications
WorkoutTemplate Object
name
string
Yes
Workout name
sport
string
Yes
See table in Accepted Enum Strings
description
string
No
Workout description
environment
string
No
outdoor / indoor / pool
pool_length_meters
float
No
Only for swimming
step_blocks
array
Yes
Array of workout segments
StepBlock Object
completion_condition
object
Yes
How the block completes
completion_condition.type
string
Yes
Completion condition type (see table in Accepted Enum Strings)
completion_condition.value
float
Conditional
Required for most types, optional for OPEN
steps
array
Yes
Array of workout steps
WorkoutStep Object
order
integer
Yes
Step order (1-based)
duration_type
string
Yes
Duration type (see table in Accepted Enum Strings)
duration_value
float
Conditional
Required when duration_type needs a value
intensity_type
string
Yes
Intensity type (see table in Accepted Enum Strings)
intensity_targets
array
No
Target zones for effort
notes
string
No
Step description
swimming
object
No
Only for swimming workouts
strength
object
No
Only for strength workouts
IntensityTarget Object
Use either value or value_low and value_high , not both
target_type
string
Yes
Target type (see table in Accepted Enum Strings)
value
float
No
Single target value
value_low
float
No
Lower bound for range targets
value_high
float
No
Upper bound for range targets
SwimmingData Object
stroke_type
string
No
Stroke type (see table in Accepted Enum Strings)
drill_type
string
No
Drill type (see table in Accepted Enum Strings)
equipment
string
No
Equipment type (see table in Accepted Enum Strings)
StrengthData Object
exercise_category
string
Yes
Exercise category (see table in Accepted Enum Strings)
exercise_name
string
No
Specific exercise name
weight_kg
float
No
Weight in kilograms
weight_display_unit
string
No
Display unit
Response Codes
Success Response (200)
200
OK
Workout template created successfully
400
Bad Request
Invalid request data
500
Internal Server Error
Server error occurred
Get Workout Template
GET https://api.tryterra.co/v2/workouts/{workout_id}
Retrieves a specific workout template by ID.
Headers
dev-id
string
Yes
Your development ID
x-api-key
string
Yes
Your API key
Path Parameters
workout_id
integer
Yes
Workout template ID
Response Codes
200
OK
Workout found
404
Not Found
Workout doesn't exist
Success Response (200)
List Workout Templates
GET https://api.tryterra.co/v2/workouts
Lists all workout templates for your account.
Headers
dev-id
string
Yes
Your development ID
x-api-key
string
Yes
Your API key
Success Response (200)
Delete Workout Template
DELETE https://api.tryterra.co/v2/workouts/{workout_id}
Deletes a workout template
Headers
dev-id
string
Yes
Your development ID
x-api-key
string
Yes
Your API key
Path Parameters
workout_id
integer
Yes
Workout template ID
Success Response (200)
Planned Workouts
Create Planned Workout
Creates a planned workout and pushes it to the user's device
POST https://api.tryterra.co/v2/plannedWorkouts
Headers
dev-id
string
Yes
Your development ID
x-api-key
string
Yes
Your API key
Content-Type
string
Yes
Must be application/json
Query Parameters
user_id
string
Yes
User's UUID
Request Body
Field Specifications
workout_id
integer
Yes
Workout template ID
planned_date
string
Yes
Date in YYYY-MM-DD format
Response Codes
200
OK
Workout pushed successfully
404
Not Found
Workout template doesn't exist
408
Request Timeout
Push operation timed out
501
Not Implemented
Provider doesn't support planned workouts
502
Bad Gateway
Provider returned an error
Success Response (200)
Get Planned Workouts by Connection
GET https://api.tryterra.co/v2/plannedWorkouts
Alternative: GET https://api.tryterra.co/v2/plannedWorkouts/connection/{connection_id}
Fetches all planned workouts for a user, including both Terra-created and provider-native workouts.
Headers
dev-id
string
Yes
Your development ID
x-api-key
string
Yes
Your API key
Query Parameters
user_id
string
Yes
–
User's UUID
start_date
string
No
30 days ago
Start date (YYYY-MM-DD)
end_date
string
No
Today
End date (YYYY-MM-DD)
Success Response (200)
PlannedWorkout Object
planned_workout_id
integer
Terra's planned workout ID (0 for external workouts)
workout_id
integer / null
Workout template ID (null for external workouts)
connection_id
integer
User's connection ID
planned_date
string
Scheduled date (YYYY-MM-DD)
provider_workout_id
string
Provider's workout ID
provider_name
string
Provider name (e.g., garmin)
provider_workout_name
string
Workout name on provider platform
synced_at
integer / null
Unix timestamp when synced to device
coercion_applied
boolean
Whether the workout was modified
coercion_warnings
array / null
Array of modifications
external_only
boolean
true if created on provider platform
created_date
integer
Unix timestamp of creation
updated_date
integer
Unix timestamp of last update
Get Planned Workout by ID
GET https://api.tryterra.co/v2/plannedWorkouts/{planned_workout_id}
Retrieves a specific planned workout by Terra ID.
Headers
dev-id
string
Yes
Your development ID
x-api-key
string
Yes
Your API key
Path Parameters
planned_workout_id
integer
Yes
Terra's planned workout ID
Success Response (200)
Update Planned Workout Date
PATCH https://api.tryterra.co/v2/plannedWorkouts/{planned_workout_id}
Updates the scheduled date for a planned workout
Headers
dev-id
string
Yes
Your development ID
x-api-key
string
Yes
Your API key
Content-Type
string
Yes
Must be application/json
Path Parameters
planned_workout_id
integer
Yes
Terra's planned workout ID
Request Body
Success Response (200)
Delete Planned Workout
DELETE https://api.tryterra.co/v2/plannedWorkouts/{planned_workout_id}
Deletes a planned workout by Terra ID. Removes from Terra database but may not immediately remove from device.
Headers
dev-id
string
Yes
Your development ID
x-api-key
string
Yes
Your API key
Path Parameters
planned_workout_id
integer
Yes
Terra's planned workout ID
Success Response (200)
Accepted Enum Strings
The tables below show the accepted lowercase strings for various fields in the Workout API.
Sport Types
"running"
Running
"treadmill_running"
Treadmill Running
"indoor_running"
Indoor Running
"biking"
General Cycling
"mountain_biking"
Mountain Biking
"road_biking"
Road Biking
"stationary_biking"
Stationary/Indoor Biking
"swimming"
General Swimming
"swimming_swimming_pool"
Pool Swimming (requires pool_length_meters)
"swimming_open_water"
Open Water Swimming
"strength_training"
Strength Training
"weightlifting"
Weightlifting
"yoga"
Yoga
"pilates"
Pilates
"hiit"
High Intensity Interval Training
"cardio_training"
General Cardio
Note: Unsupported types get converted to
"GENERIC"on Garmin.
Completion Condition Types
"fixed_repetition"
Repeat block N times
Count
"distance_threshold"
Complete after distance
Meters
"time_threshold"
Complete after duration
Seconds
"calories_threshold"
Complete after calories
Calories
"hr_below"
Complete when HR drops below
BPM
"hr_above"
Complete when HR rises above
BPM
"power_below"
Complete when power drops below
Watts
"power_above"
Complete when power rises above
Watts
"open"
User controlled (press lap button)
N/A
Duration Types
"time"
Time-based duration
Seconds
"distance_meters"
Distance-based duration
Meters
"hr_less_than"
Until heart rate drops below
BPM
"hr_greater_than"
Until heart rate rises above
BPM
"calories"
Calorie-based duration
Calories
"open"
User controlled (lap button)
N/A
"power_less_than"
Until power drops below
Watts
"power_greater_than"
Until power rises above
Watts
"reps"
Repetition count (strength)
Count
"fixed_rest"
Fixed rest period
Seconds
"steps"
Step count
Count
Intensity Types
"rest"
Complete rest periods
"warmup"
Beginning of workout
"cooldown"
End of workout
"recovery"
Easy efforts between intervals
"interval"
High-intensity intervals
"active"
Main workout efforts
Intensity Target Types
"speed"
Speed target (m/s or zones)
"heart_rate"
Heart rate zones (1-5) or BPM
"open"
No specific target
"cadence"
Cadence zones or RPM
"power"
Power zones (1-5) or Watts
"swim_stroke"
Swimming stroke type
"speed_lap"
Speed per lap
"heart_rate_lap"
Heart rate per lap
"pace"
Pace zones (1-5) or seconds/km
"heart_rate_threshold_percentage"
Percentage of threshold HR
"heart_rate_max_percentage"
Percentage of max HR
"speed_percentage"
Percentage of max speed
"power_percentage"
Percentage of FTP
"repetition"
Repetition-based target
"tss"
Training Stress Score
"if"
Intensity Factor
"rpe"
Rate of Perceived Exertion (1-10)
Environment Types
"indoor"
Indoor activity
"outdoor"
Outdoor activity
"pool"
Pool swimming
Stroke Types
"backstroke"
Backstroke
"breaststroke"
Breaststroke
"drill"
Drill (generic)
"butterfly"
Butterfly
"freestyle"
Freestyle/Front crawl
"mixed"
Mixed strokes
"im"
Individual Medley (butterfly, backstroke, breaststroke, freestyle)
Drill Types
"kick"
Kick drill
"pull"
Pull drill
"drill"
Generic drill
Equipment Types
"none"
No equipment
"swim_fins"
Swim fins
"swim_kickboard"
Kickboard
"swim_paddles"
Hand paddles
"swim_pull_buoy"
Pull buoy
"swim_snorkel"
Snorkel
Exercise Categories
For strength training workouts, use these exercise categories:
"bench_press"
Bench press variations
"calf_raise"
Calf raise exercises
"cardio"
Cardio exercises
"carry"
Carry exercises
"chop"
Chop exercises
"core"
Core exercises
"crunch"
Crunch variations
"curl"
Curl exercises
"deadlift"
Deadlift variations
"fly"
Fly exercises
"hip_raise"
Hip raise exercises
"hip_stability"
Hip stability
"hip_swing"
Hip swing exercises
"hyperextension"
Hyperextension
"lateral_raise"
Lateral raise
"leg_curl"
Leg curl variations
"leg_raise"
Leg raise exercises
"lunge"
Lunge variations
"olympic_lift"
Olympic lifts
"plank"
Plank variations
"plyo"
Plyometric exercises
"pull_up"
Pull-up variations
"push_up"
Push-up variations
"row"
Row exercises
"shoulder_press"
Shoulder press
"shoulder_stability"
Shoulder stability
"shrug"
Shrug exercises
"sit_up"
Sit-up variations
"squat"
Squat variations
"total_body"
Total body exercises
"triceps_extension"
Triceps extension
"warm_up"
Warm-up exercises
"run"
Running exercises
"bike"
Biking exercises
"cardio_sensors"
Cardio with sensors
"battle_rope"
Battle rope
"sandbag"
Sandbag exercises
"sled"
Sled exercises
"sledge_hammer"
Sledgehammer
"suspension"
Suspension training
"tire"
Tire exercises
"elliptical"
Elliptical
"stair_stepper"
Stair stepper
"ladder"
Ladder drills
Weight Units
"kilogram"
Kilograms
"pound"
Pounds
Provider Coercion
When a provider modifies your workout to fit device constraints, coercion warnings are stored with the planned workout. These warnings can be retrieved via the GET endpoints.
CoercionWarning Structure
CoercionWarning Fields
field
string
JSON path to the field that was modified (e.g. step_blocks[1].steps[0].duration_value)
original_value
any
The original value you sent
coerced_value
any
The value after provider coercion
reason
string
Human-readable explanation of why the value was changed
Example Coercion Warnings
Swimming distance rounded to complete laps
Target type not supported by provider
Step count reduced
Last updated
Was this helpful?