> 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/overview.md).

# Overview

Push structured workouts to your users' fitness devices and read their training calendar back.

The Planned Workouts API pushes structured training sessions to your users' fitness devices, so they don't have to build workouts by hand 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 the device**: the workout appears on the user's Garmin, COROS, Wahoo and other devices.
4. **Read the calendar back**: list a user's planned workouts, including ones a coach created on the provider's side.

Planned Workouts is a paid add-on to your Terra plan. See [Pricing](/planned-workouts-api/pricing.md).

## How it works

You create a template once, then schedule it to each athlete.

```
┌─────────────────────────────────────────────────────────────────┐
│  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                            │
└─────────────────────────────────────────────────────────────────┘
```

## Supported providers

Terra pushes workouts to these providers:

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

Intervals.icu is read only: Terra lists the workouts an athlete has planned there, but cannot push to it. Users connect it with their Intervals.icu API key on Terra's login screen.

Not all providers support all operations (update, retrieve, delete). See [Provider compatibility](/planned-workouts-api/provider-compatibility.md) for feature and operations support, including the **Retrieve** row for reading workouts back.

## Authentication

All requests require two headers:

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

## Quickstart

{% prompt description="Create a workout template and schedule it to a device" icon="terminal" openInAIProviders="true" defaultExpanded="full" %}

```markdown
Create a 5x1km interval workout template and schedule it onto user 8f2a1c's Garmin for tomorrow.

Use the Terra CLI: brew install tryterra/tap/terra, or npm install -g @tryterra/cli, then terra login. Run terra docs ask --question "<question>" for anything you need from the Terra docs, and terra <command> --help for usage.
```

{% endprompt %}

### 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"
}
```

### Schedule it 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",
  "warnings": []
}
```

The workout now appears on the user's device. Providers that accept percentage targets, such as Garmin, receive 85-90% unchanged. Providers that need absolute values, such as Suunto and Zepp, receive 157-167 BPM, resolved from the max heart rate of 185 you passed. See [Athlete parameters](/planned-workouts-api/athlete-parameters.md).

### List the user's planned workouts

```bash
curl -X GET "https://access.tryterra.co/api/v2/plannedWorkouts?user_id=USER_ID&start_date=2026-02-05&end_date=2026-02-12" \
  -H "dev-id: YOUR_DEV_ID" \
  -H "x-api-key: YOUR_API_KEY"
```

Response (abbreviated):

```json
[
  {
    "planned_workout_id": "67890",
    "workout_id": "12345",
    "planned_date": "2026-02-05",
    "provider_workout_id": "abc123",
    "is_external": false,
    "warnings": [],
    "workout": {
      "name": "20min Interval Run",
      "sport": "running",
      "step_blocks": [
        {
          "steps": [
            {
              "completion_condition": { "type": "time", "value": 300 },
              "intensity_type": "warmup"
            }
          ]
        }
      ]
    }
  }
]
```

The list also holds workouts created on the provider's side. See [Read scheduled workouts](#read-scheduled-workouts) for the response shape, the date window and the provider read headers.

## API endpoints

| Method | Endpoint                          | Description                                                       |
| ------ | --------------------------------- | ----------------------------------------------------------------- |
| POST   | `/workouts`                       | Create workout template                                           |
| GET    | `/workouts`                       | List all templates                                                |
| GET    | `/workouts/{id}`                  | Get template details                                              |
| PUT    | `/workouts/{id}`                  | Update template and re-send it to upcoming planned workouts       |
| DELETE | `/workouts/{id}`                  | Delete template                                                   |
| POST   | `/workouts/{id}/plan?user_id=X`   | Schedule workout to user                                          |
| GET    | `/plannedWorkouts/{id}`           | Get a planned workout created through Terra                       |
| GET    | `/plannedWorkouts?user_id=X`      | List Terra-created and provider-created workouts (dates optional) |
| PATCH  | `/plannedWorkouts/{id}?user_id=X` | Update scheduled date (only `planned_date`, not athlete params)   |
| DELETE | `/plannedWorkouts/{id}?user_id=X` | Remove scheduled workout                                          |

A template's `estimated_tss`, `estimated_intensity_factor`, `estimated_distance_meters` and `estimated_calories` are forwarded to TrainingPeaks when you plan or reschedule the workout. TrainingPeaks ignores TSS, intensity factor and duration whenever any step target is something other than RPE: it derives them from the athlete's own thresholds instead, and Terra returns warnings on `workout.estimated_tss`, `workout.estimated_intensity_factor` and `workout.estimated_duration_seconds`. `POST /workouts` rejects an `estimated_tss` outside 0 to 9999 and an `estimated_intensity_factor` outside 0 to 5.

## Update a workout template

`PUT /workouts/{id}` takes the same body as `POST /workouts` and replaces the whole template. Fields you leave out are cleared, so send the full template even to change one field.

Terra then re-sends the new version to every upcoming planned workout made from this template. Each keeps its `planned_date` and athlete parameters. The response lists every planned workout:

```json
{
  "status": "success",
  "workout_id": "1024",
  "planned_workouts": [
    {
      "planned_workout_id": "2048",
      "provider_workout_id": "981230",
      "status": "updated"
    }
  ]
}
```

| Status    | Meaning                                                                                                                                                             |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `updated` | The provider has the new version. `warnings` lists anything it could not take, as when planning. `provider_workout_id` changes if the provider assigned a new one.  |
| `failed`  | The provider rejected it, and `error` has the reason. Repeat the request to re-send.                                                                                |
| `skipped` | Nothing was sent: the planned workout is completed or in the past, it isn't on a device yet, or the user's connection no longer allows it (they need to reconnect). |

If any planned workout failed, the response is `207 Multi-Status`, with a `message` in place of `status`. The template is already saved.

* **Upcoming** means a `planned_date` of today or later (UTC) that isn't completed. Past and completed planned workouts keep the version they were sent.
* **Apple Health:** a planned workout already on the device is told to fetch the new version. One not synced yet picks it up when it syncs.
* **Pricing:** each planned workout re-sent costs 10 credits, like a reschedule. Skipped and failed ones are free. See [Pricing](/planned-workouts-api/pricing.md).
* **Limit:** a template with more than 50 planned workouts, counting past and completed ones, returns `422 Unprocessable Entity` and nothing changes. Create a new template instead.
* **Concurrent changes:** while one request is changing a template, other requests that update, delete or plan it, or reschedule or delete its planned workouts, return `409 Conflict`. Retry after a short wait.

{% hint style="warning" %}
Deleting a workout template also deletes every workout scheduled from it. When you call `DELETE /workouts/{id}`, Terra removes all planned workouts linked to that template from every connected provider (e.g. Garmin, Suunto, Wahoo) before deleting the template itself. This cannot be undone. To unschedule a workout for one user, use `DELETE /plannedWorkouts/{id}` instead.
{% endhint %}

## Read scheduled workouts

`GET /plannedWorkouts?user_id=X` returns everything on the user's calendar, from both origins, in one shape. Every item carries the workout body under `workout` (name, sport, `step_blocks`, estimates), plus `planned_date`, `provider_workout_id` and `warnings`:

* **Workouts you scheduled through Terra**: identified by a `planned_workout_id`. Use it with the `GET`/`PATCH`/`DELETE /plannedWorkouts/{id}` endpoints. The workout body is inline under `workout` and `workout_id` names the template it was planned from.
* **Workouts created on the provider's side** (e.g. by a coach on TrainingPeaks): marked `is_external: true`. These are read live from the provider and are read-only. `planned_workout_id` and `workout_id` are null, so they cannot be addressed by id or updated or deleted through Terra. The body arrives under `workout` like every other item: title, sport, structured steps with targets, and planned estimates such as `estimated_duration_seconds`, `estimated_tss` and `estimated_intensity_factor`. Use `provider_workout_id` as their stable identifier; a completed workout's activity carries the same id in `summary_id`.

Provider-created workouts are listed for Garmin, Wahoo, Suunto, TrainingPeaks and Intervals.icu. Garmin returns only the workouts your app created. Intervals.icu is read-only for planned workouts: you can list what the athlete has planned there, but you cannot push to it. COROS, Zepp, Huawei and Apple have no way to read a calendar back, and Hevy has no calendar (a workout pushed to Hevy becomes a library routine and carries no date), so for those providers the list contains only the workouts you scheduled through Terra. A workout you pushed through Terra that the provider echoes back is listed once, as the Terra row.

```json
{
  "planned_workout_id": null,
  "workout_id": null,
  "planned_date": "2026-07-15",
  "provider_workout_id": "3841172642",
  "is_external": true,
  "created_at": null,
  "last_updated_at": null,
  "athlete_metrics": null,
  "warnings": [],
  "workout": {
    "name": "threshold",
    "sport": "cycling",
    "estimated_duration_seconds": 3816,
    "estimated_tss": 65.4,
    "estimated_intensity_factor": 0.75,
    "step_blocks": [
      {
        "completion_condition": null,
        "steps": [
          {
            "intensity_type": "warmup",
            "completion_condition": { "type": "time", "value": 900 },
            "intensity_targets": [
              { "target_type": "heart_rate_max_percentage", "value_low": 40, "value_high": 50 }
            ],
            "notes": "Warm up"
          }
        ]
      }
    ]
  }
}
```

Items also carry `coercion_warnings` and `details`, the older forms of `warnings` and `workout`. Both are deprecated: read `warnings` and `workout`, which use the same field names and values as `GET /workouts/{workout_id}`.

Two response headers report the live provider read:

| Header                            | Values                                                                              |
| --------------------------------- | ----------------------------------------------------------------------------------- |
| `X-Terra-Provider-Fetch`          | `ok`, `skipped`, `rate_limited`, `unauthorized`, `unavailable`, `timeout`, `failed` |
| `X-Terra-Provider-Data-Truncated` | `true` when provider-side workouts could not be included                            |

`skipped` means the provider does not expose planned workouts. Anything other than `ok` also sets `X-Terra-Provider-Data-Truncated: true`. The call still returns `200` with the workouts Terra has stored, so check the headers before treating a short list as an empty calendar.

`warnings` is an array of `{path, message}` entries describing what had to change between your template and the provider's format: on workouts you pushed, what the push adjusted; on provider-created workouts, what reading them back adjusted. See [Coercion warnings](/planned-workouts-api/coercion-warnings.md).

{% hint style="info" %}
Pass a date window to see upcoming workouts. Without `start_date`/`end_date`, provider-side workouts default to the **trailing 30 days**, so upcoming ones will not appear. Workouts you scheduled through Terra are not windowed when the dates are omitted. Pass an explicit window (e.g. today through next week) to list what is ahead: both bounds are planned dates and both are inclusive. Some providers also limit how far ahead they expose planned workouts.

A planned workout the user has **completed** leaves this list and is delivered as a completed activity instead.
{% endhint %}

## Next steps

* [Pricing](/planned-workouts-api/pricing.md): add-on cost, credits, and what works without it
* [Core concepts](/planned-workouts-api/core-concepts.md): workout structure, blocks, steps and targets
* [Sport-specific examples](/planned-workouts-api/sport-specific-examples.md): running, cycling, swimming and strength
* [Athlete parameters](/planned-workouts-api/athlete-parameters.md): personalize workouts per user
* [Provider compatibility](/planned-workouts-api/provider-compatibility.md): what works where
* [Coercion warnings](/planned-workouts-api/coercion-warnings.md): handle feature limitations
* [Exercise reference](/planned-workouts-api/exercise-reference.md): exercise names and how they map across providers
* [Garmin and Hevy exercise reference](/planned-workouts-api/garmin-exercise-reference.md): provider exercise catalogs
