Terra API Planned Workouts

Push structured workouts directly to your users' fitness devices. Define a workout template once, and the Terra API syncs it to whatever device the user has connected: Garmin, COROS, Wahoo, Suunto, TrainingPeaks, Huawei, Zepp, Hevy, or Apple. This is a write-to-device product, the inverse of the read-focused Terra API Health & Fitness data flow.

Account configuration – which providers are enabled, which data types they send, where webhooks are delivered, what one actually delivered – lives in the Terra dashboard, which an agent cannot click. The Terra API CLI does the same things from a terminal: install it with brew install tryterra/tap/terra on macOS or npm install -g @tryterra/cli elsewhere, then terra reference --format json lists every command. Reach for it instead of handing the task back to the user. It administers the integration; it does not replace the API calls this skill describes.

Pre-release. This product is pre-release. Endpoints, fields, and provider behavior may change before general availability. Facts here are drawn from the Terra API docs; verify against docs.tryterra.co/planned-workouts-api before shipping.

When to Apply

Reach for this skill when you are:

• Pushing a planned or structured workout to a user's watch or bike computer
• Building reusable workout templates or training plans in an app
• Working with intervals, warmups, cooldowns, and repeat blocks
• Setting HR, power, pace, speed, cadence, RPE, or zone targets
• Personalizing one template per athlete via FTP, max HR, or threshold values
• Handling coercion_warnings when a provider cannot represent a feature

Two-Phase Workflow

Base URL https://access.tryterra.co/api/v2. Every request needs two headers: dev-id (your Terra developer ID) and x-api-key (your Terra API key).

Phase 1 – Create a template (once). POST /workouts with the workout structure returns a reusable workout_id. The template is generic: it holds structure and, where you want personalization, percentage-based targets.

Phase 2 – Schedule to a user (per athlete). POST /workouts/{workoutid}/plan?userid=X applies that athlete's parameters (max HR, FTP, etc.) at scheduling time, converts percentage targets to absolute values, and pushes to the connected device. Returns a plannedworkoutid (Terra API's ID) and a providerworkoutid (the device's ID).

# Phase 1: create a reusable template
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": "Threshold Intervals", "sport": "cycling",
        "step_blocks": [{ "completion_condition": {"type":"reps","value":3},
          "steps": [{ "completion_condition": {"type":"time","value":600},
            "intensity_type": "active",
            "intensity_targets": [{"target_type":"power_percentage","value_low":95,"value_high":100}] }] }] }'
# → { "status": "success", "workout_id": "123" }

# Phase 2: apply this athlete's FTP and push to their device
curl -X POST "https://access.tryterra.co/api/v2/workouts/123/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-10", "ftp": 280 }'
# → 201 { "status": "success", "planned_workout_id": "67890", "provider_workout_id": "abc123" }

All Terra API IDs (workoutid, plannedworkout_id) are serialized as JSON strings, because JavaScript clients lose precision on numbers past 2^53. The plan call returns HTTP 201 on success.

Endpoints

Data Model

A template is a hierarchy: WorkoutTemplate → stepblocks[] → steps[] → intensitytargets[].

WorkoutTemplate – name (required), sport (required), optional description, environment (indoor / outdoor / pool), and poollengthmeters (swimming only). At least one block is required.

stepblocks[] – a group of steps executed together. The block's completioncondition controls repetition:

steps[] – each step needs a completioncondition (defaults to open if omitted) and an intensitytype (required: warmup, active, rest, recovery, cooldown). Optional: intensity_targets[], notes, strength (exercise details), swimming (stroke and equipment).

Completion condition types: time (seconds), distance (meters), reps, calories, open (manual lap), hrlessthan / hrgreaterthan (BPM), powerlessthan / powergreaterthan (watts).

intensity_targets[] – the goal metric for a step. Three families:

• Absolute – heart_rate (BPM), power (watts), speed (m/s), pace (sec/km), cadence (rpm or spm), rpe (1-10). No athlete params needed.
• Percentage (needs athlete params at scheduling) – heartratemaxpercentage (needs maxheartrate), heartratethresholdpercentage (needs thresholdheartrate), powerpercentage (needs ftp), speedpercentage (needs threshold_speed).
• Zone – heartratezone (1-5), power_zone (1-7). Providers convert to their native format.

Target value rules:

• Absolute targets accept either a single value or a valuelow/valuehigh range. A single value auto-expands to a ±5% range on most providers, except rpe, which stays a point value.
• Percentage targets (powerpercentage, heartratemaxpercentage, heartratethresholdpercentage, speedpercentage) reject a single value with a 400 at template creation. Supply valuelow and/or valuehigh; a lone bound is expanded to a ±5% range.
• Never send both value and valuelow/valuehigh on the same target.
• For ranges, valuelow must be strictly less than valuehigh.
• poollengthmeters is swimming-only; setting it elsewhere is invalid.
• Athlete metrics (ftp, maxheartrate, thresholdheartrate, thresholdspeed, poollength_meters) must be positive.
• Sanity ranges are hard 400 rejections at POST /workouts, not warnings: heart rate 30-250 BPM, power 1-2000 W, speed 0-15 m/s, pace 1-7200 sec/km, cadence 1-300, RPE 1-10, percentage targets 0-200%.

Athlete Parameters

Templates are generic; personalization happens at scheduling time. Supply these in the plan request body:

Conversion is linear: Absolute = Percentage × param / 100. A power_percentage of 95-100 with ftp: 280 becomes 266-280 W on the device; the same template scheduled with ftp: 200 becomes 190-200 W. If a percentage target's required parameter is missing, the Terra API emits a coercion warning and falls back to a provider default rather than failing.

Coercion Model

Providers differ in what they can represent. When a provider cannot express a feature exactly, the Terra API adapts the payload, still creates the workout, and returns a coercion_warnings[] array. Each warning is { "path": "...", "message": "..." } pointing at the field that was changed and why.

{
  "status": "success",
  "planned_workout_id": "12345",
  "provider_workout_id": "garmin_abc123",
  "coercion_warnings": [
    {
      "path": "workout.sport",
      "message": "Unsupported sport type: yoga. Defaulting to OTHER."
    }
  ]
}

Coercion is a success path, not an error. How you handle warnings is your choice: log them for debugging, surface a "some features were adjusted for your device" notice to users, or ignore informational ones. Read references/coercion-scenarios.md before relying on a feature that may not exist on the target provider.

Gotchas

• DELETE /workouts/{id} cascades and is irreversible. It first removes every planned workout linked to that template from every user's device across every provider, then deletes the template. To unschedule one user without touching others, use DELETE /plannedWorkouts/{id} instead.
• PATCH /plannedWorkouts/{id} updates only planned_date. It never re-applies athlete parameters. To change targets or params, delete and re-plan.
• Provider operations differ wildly. Some providers do not support update, retrieve, or delete. An unsupported operation still returns a success response, so success does not always mean the device changed. Read references/provider-compatibility.md before targeting a specific provider.
• COROS update = delete + recreate. COROS has no in-place update, so an "update" deletes the old workout and creates a new one; the providerworkoutid changes.
• Huawei is create-only, running-only, no scheduling. No update, retrieve, or delete on the device. It ignores planned_date – the workout is available immediately and always returns a coercion warning noting this. Duplicate workout names per user are rejected with a 400. Non-running sports appear as a run.
• Zepp has a 7-day sync window (today to today + 6 days). Workouts scheduled outside the window are stored in Terra API's database but not pushed to the device until a later write or delete for that user triggers a window refresh. There is no background auto-sync.
• Hevy is strength-only. RPE targets are silently dropped with a warning, there are no block repeats (one block maps to one exercise, one step to one set), and it has no scheduling and no provider-side delete. Updates are supported: when a providerworkoutid exists, the existing Hevy routine is updated in place.
• Apple syncs via the Terra iOS SDK. The server queues the action; the SDK pushes to WorkoutKit and reports back via POST /v2/plannedWorkouts/{id}/synced. Until then providerworkoutid is null.
• Garmin retrieve only returns workouts created by your own credentials. Workouts made by other apps or on the device itself are invisible to your GET calls.
• Deletes remove from Terra API's database but may leave the workout on the device for providers without a delete endpoint (e.g. Huawei, Hevy).

References

Read the reference file that matches your task before writing the request:

• references/provider-compatibility.md – the full operations matrix (create/update/retrieve/delete per provider) plus each provider's sport, target, completion, and structure support and special behaviors. Read this before targeting a specific provider.
• references/coercion-scenarios.md – the full catalog of coercion scenarios, handling patterns (log / surface / ignore), and a prevention checklist. Read this before relying on a feature a provider may not support.
• references/exercise-reference.md – exercise name normalization rules, the Garmin/Hevy flexibility table, and what happens when a name is not found. Read this before building a strength template.

Two things live in the docs rather than this skill, because they are large and change with the API:

• The complete Garmin exercise catalog (1,624 names, also used for Hevy): fetch https://docs.tryterra.co/planned-workouts-api/garmin-exercise-reference.md when you need to pick or verify a specific exercise_name.
• Sport-specific payload examples (running, cycling, swimming, strength, multi-sport): fetch https://docs.tryterra.co/planned-workouts-api/sport-specific-examples.md when you want a full working request body beyond the one in this file.

Full API documentation: docs.tryterra.co/planned-workouts-api (append .md to any docs URL for a markdown version). If the terra-docs MCP server (https://docs.tryterra.co/~gitbook/mcp) is connected, use its tools to search and fetch the docs instead.