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

# Introduction

> ⚠️ **Pre-Release / Under Construction**
>
> This page is currently **under active development** and is provided in a **pre-release state**.
>
> Content may be **incomplete, outdated, or inaccurate**, and details may changewithout notice as the implementation evolves.
>
> Please use this documentation for **early reference only**, and avoid relying on it for production-critical decisions until the page is marked as stable.

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

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

```bash
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:**

```json
{
  "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:

```bash
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:**

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


---

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

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

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

```
GET https://docs.tryterra.co/planned-workouts-api/introduction.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

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