For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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

terminalCreate a workout template and schedule it to a device

Create a workout template

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

Response:

Schedule it to a user

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

Response:

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.

List the user's planned workouts

Response (abbreviated):

The list also holds workouts created on the provider's side. See 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:

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.

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

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.

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.

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.

Next steps

Last updated

Was this helpful?