Introduction

Introduction & Quick Start

What Are Planned Workouts?

Planned workouts let you push structured training sessions directly to your users' fitness devices. Instead of users manually creating workouts on their watch or bike computer, your app can:

1. Create reusable workout templates - Define the structure once

2. Schedule to any user - Apply athlete-specific parameters at scheduling time

3. Sync to device - Workout appears on user's Garmin, COROS, Wahoo, etc.

Planned Workouts is a paid add-on to your Terra plan — see Pricing & Access.

Two-Phase Workflow

┌─────────────────────────────────────────────────────────────────┐
│  Phase 1: Create Template (once)                                │
│  POST /workouts                                                 │
│  → Returns workout_id                                           │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  Phase 2: Schedule to User (per athlete)                        │
│  POST /workouts/{workout_id}/plan?user_id=X                     │
│  → Applies athlete's max HR, FTP, etc.                          │
│  → Pushes to user's connected device                            │
└─────────────────────────────────────────────────────────────────┘

Quick Start Example

Step 1: Create a Workout Template

Create a simple 20-minute interval run: 5min warmup → 3x(3min fast, 2min easy) → 5min cooldown

curl -X POST "https://access.tryterra.co/api/v2/workouts" \
  -H "Content-Type: application/json" \
  -H "dev-id: YOUR_DEV_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "20min Interval Run",
    "sport": "running",
    "description": "Warmup, 3x intervals, cooldown",
    "step_blocks": [
      {
        "steps": [{
          "completion_condition": { "type": "time", "value": 300 },
          "intensity_type": "warmup"
        }]
      },
      {
        "completion_condition": { "type": "reps", "value": 3 },
        "steps": [
          {
            "completion_condition": { "type": "time", "value": 180 },
            "intensity_type": "active",
            "intensity_targets": [{
              "target_type": "heart_rate_max_percentage",
              "value_low": 85,
              "value_high": 90
            }]
          },
          {
            "completion_condition": { "type": "time", "value": 120 },
            "intensity_type": "rest"
          }
        ]
      },
      {
        "steps": [{
          "completion_condition": { "type": "time", "value": 300 },
          "intensity_type": "cooldown"
        }]
      }
    ]
  }'

Response:

{
  "status": "success",
  "workout_id": "12345"
}

Step 2: Schedule to a User

Push the workout to a specific user for tomorrow, with their max heart rate:

curl -X POST "https://access.tryterra.co/api/v2/workouts/12345/plan?user_id=USER_ID" \
  -H "Content-Type: application/json" \
  -H "dev-id: YOUR_DEV_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "planned_date": "2026-02-05",
    "max_heart_rate": 185
  }'

Response:

{
  "status": "success",
  "planned_workout_id": 67890,
  "provider_workout_id": "abc123"
}

The workout now appears on the user's device, with the 85-90% HR targets converted to 157-167 BPM based on their max HR of 185.

Authentication

All requests require two headers:

Header	Description
dev-id	Your Terra developer ID
x-api-key	Your Terra API key

Supported Providers

Provider	Running	Cycling	Swimming	Strength
Garmin	✓	✓	✓	✓
COROS	✓	✓	✓	✓
Wahoo	✓	✓	—	—
Suunto	✓	✓	✓	✓
TrainingPeaks	✓	✓	✓	✓
Huawei	✓	—	—	—
Zepp	✓	✓	✓	—
Hevy	—	—	—	✓
Apple	✓	✓	✓	✓

Not all providers support all operations (update, retrieve, delete). See Provider Compatibility for detailed feature and operations support.

Next Steps

• Core Concepts - Understand workout structure

• Athlete Parameters - Personalize for each user

• Sport-Specific Examples - Copy-paste examples