terra-planned-workouts

Terra API 计划训练

将结构化训练直接推送到用户的健身设备。只需定义一次训练模板，Terra API 就会将其同步到用户已连接的设备：Garmin、COROS、Wahoo、Suunto、TrainingPeaks、Huawei、Zepp、Hevy 或 Apple。这是一款向设备写入数据的产品，与以读取为主的 Terra API 健康与健身数据流正好相反。

预发布。 此产品尚处于预发布阶段。正式发布前，端点、字段和服务提供方的行为可能会发生变化。此处的信息取自 Terra API 文档；在发布前，请对照 docs.tryterra.co/planned-workouts-api 进行核实。

账户工具：CLI 或 MCP

在编写发送请求的代码之前，可以先手动完成整个“创建后计划”流程：

terra data-api /workouts -X POST --body-file workout.json            # returns workout_id
terra data-api /workouts/<workout_id>/plan -X POST -q user_id=<uuid> -d planned_date=2026-09-08
terra data-api /plannedWorkouts -q user_id=<uuid>
terra workouts metadata list --env <dev-id>

计划调用值得手动运行：它会返回计划训练 ID 以及任何强制转换警告，这样你就能知道在用户看到训练之前，目标或间歇是否被改写以适配设备。使用 terra admin-api list --data-api /workouts --format json 查看端点需要哪些参数。这些调用会在已连接的设备上创建并安排真实训练，因此请对测试用户运行。

terra workouts metadata 保存的是 Terra API 自身的训练元数据（其 pace_units 和数据行的创建时间），而不是训练数据本身。

前三条命令属于 terra data-api，只有 CLI 提供此功能；通过 MCP 使用时，管理工具仅涵盖训练元数据。

在编码 Agent（Claude Code、Codex、Cursor 等，运行于用户的设备或云端）中使用 CLI；如果尚未安装，请提供安装方式：在 macOS 和 Linux 上运行 curl -fsSL https://cli.tryterra.co/install.sh | sh，在 Windows PowerShell 中运行 irm "https://cli.tryterra.co/install.ps1" | iex，或者使用用户已经在使用的 Homebrew 或 npm。在聊天助手（claude.ai、Claude Desktop、ChatGPT）中使用 Terra API 管理 MCP 服务，即使它能够运行代码也是如此：其沙盒无法安装 CLI 或登录。每条管理命令都是一个工具，其名称和 method 会明确说明对应关系（terra users list 对应 users_read，method: "list"）。只有 CLI 提供 terra data-api、terra admin-api 和 terra examples；--select 和 --jq 没有对应的 MCP 功能。terra-cli 和 terra-mcp 技能包含安全防护措施（确认更改，避免凭据出现在对话记录中）、错误说明，以及各项任务的操作指南。它们用于管理集成，不能替代本技能所述的 API 调用。

两阶段工作流

基础 URL 为 https://access.tryterra.co/api/v2。每个请求都需要两个标头：dev-id（你的 Terra API 开发者 ID）和 x-api-key（你的 Terra API 密钥）。

阶段 1 – 创建模板（一次）。 使用训练结构调用 POST /workouts，会返回可重复使用的 workout_id。模板是通用的：它包含训练结构；如果需要个性化，还可以包含基于百分比的目标。

阶段 2 – 为用户安排训练（每位运动员一次）。 调用 POST /workouts/{workout_id}/plan?user_id=X，会在安排训练时应用该运动员的参数（最大心率、FTP 等），将百分比目标转换为绝对值，并推送到已连接的设备。返回 planned_workout_id（Terra API 的 ID）和 provider_workout_id（设备的 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" }

所有 Terra API ID（workout_id、planned_workout_id）都序列化为 JSON 字符串，因为对于大于 2^53 的数字，JavaScript 客户端会丢失精度。plan 调用成功时返回 HTTP 201。

端点

方法	端点	描述
POST	/workouts	创建训练模板，返回 workout_id
GET	/workouts	列出所有模板
GET	/workouts/{id}	获取模板详情
DELETE	/workouts/{id}	删除模板。会级联删除 – 请参阅注意事项
POST	/workouts/{id}/plan?user_id=X	将模板安排给用户，并应用运动员参数
GET	/plannedWorkouts/{id}	获取一项已安排的训练
GET	/plannedWorkouts?user_id=X	列出用户已安排的训练（可选的 start_date 和 end_date 筛选条件——必须同时提供；单独提供其中一个会被忽略）
PATCH	/plannedWorkouts/{id}?user_id=X	更新安排日期。只能更新 planned_date，不能更新运动员参数
DELETE	/plannedWorkouts/{id}?user_id=X	取消为单个用户安排的训练

数据模型

模板是一个层级结构：WorkoutTemplate → step_blocks[] → steps[] → intensity_targets[]。

WorkoutTemplate – name（必填）、sport（必填）、可选的 description、environment（indoor / outdoor / pool）和 pool_length_meters（仅游泳适用）。至少需要一个区块。

step_blocks[] – 一组一起执行的步骤。区块的 completion_condition 控制重复方式：

区块条件	行为
{"type":"reps","value":4}	重复所有步骤 4 次
{"type":"time","value":1200}	重复执行，直到总时长达到 20 分钟
{"type":"distance","value":5000}	重复执行，直到总距离达到 5 km
{"type":"open"} 或省略	执行一次（不重复）

steps[] – 每个步骤都需要一个 completion_condition（省略时默认为 open）和一个 intensity_type（必填：warmup、active、rest、recovery、cooldown）。可选项：intensity_targets[]、notes、strength（练习详情）、swimming（泳姿和装备）。

完成条件类型：time（秒）、distance（米）、reps、calories、open（手动计圈）、hr_less_than / hr_greater_than（BPM）、power_less_than / power_greater_than（瓦）。

intensity_targets[] – 步骤的目标指标。分为三类：

• 绝对值 – heart_rate（BPM）、power（瓦）、speed（m/s）、pace（秒/km）、cadence（rpm 或 spm）、rpe（1-10）。无需运动员参数。
• 百分比（排期时需要运动员参数）– heart_rate_max_percentage（需要 max_heart_rate）、heart_rate_threshold_percentage（需要 threshold_heart_rate）、power_percentage（需要 ftp）、speed_percentage（需要 threshold_speed）。
• 区间 – heart_rate_zone（1-5）、power_zone（1-7）。服务提供商会转换为其原生格式。

目标值规则：

• 绝对值目标接受单个 value，或 value_low/value_high 范围。单个 value 会在大多数服务提供商处自动扩展为 ±5% 的范围，但 rpe 除外，它会保持为单点值。
• 百分比目标（power_percentage、heart_rate_max_percentage、heart_rate_threshold_percentage、speed_percentage）在创建模板时不接受单个 value，并会返回 400 错误。请提供 value_low 和/或 value_high；如果只提供一个边界值，则会扩展为 ±5% 的范围。
• 同一目标中不得同时发送 value 和 value_low/value_high。
• 对于范围，value_low 必须严格小于 value_high。
• pool_length_meters 仅适用于游泳；在其他情况下设置该值无效。
• 运动员指标（ftp、max_heart_rate、threshold_heart_rate、threshold_speed、pool_length_meters）必须为正数。
• 合理性范围不只是警告，而是会在 POST /workouts 时直接返回 400 错误：心率 30-250 BPM、功率 1-2000 W、速度 0-15 m/s、配速 1-7200 秒/km、步频 1-300、RPE 1-10、百分比目标 0-200%。

运动员参数

模板是通用的；个性化在安排时进行。请在 plan 请求正文中提供以下参数：

参数	单位	用途
max_heart_rate	BPM	heart_rate_max_percentage 目标
threshold_heart_rate	BPM	heart_rate_threshold_percentage 目标
ftp	瓦特	power_percentage 目标
threshold_speed	m/s	speed_percentage 目标
pool_length_meters	米	游泳（覆盖模板值）

换算是线性的：Absolute = Percentage × param / 100。如果 ftp: 280，power_percentage 为 95-100，则设备上的数值为 266-280 W；使用同一模板安排训练，但 ftp: 200 时，数值为 190-200 W。如果缺少百分比目标所需的参数，Terra API 会发出强制转换警告，并回退到提供方默认值，而不会失败。

强制转换模型

不同提供方支持表达的内容各不相同。当提供方无法精确表达某项功能时，Terra API 会调整负载，仍然创建训练，并返回 coercion_warnings[] 数组。每条警告的格式为 { "path": "...", "message": "..." }，指出被更改的字段及原因。

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

强制转换属于成功路径，而非错误。如何处理警告由你决定：可以记录它们以便调试，向用户显示“已为你的设备调整部分功能”的提示，或忽略提示性警告。在依赖目标提供方可能不支持的功能之前，请阅读 references/coercion-scenarios.md。

注意事项

• DELETE /workouts/{id} 会级联删除，且不可恢复。 它会先从所有提供商的所有用户设备中移除与该模板关联的每个计划训练，然后删除该模板。若要只为一个用户取消安排训练且不影响其他用户，请改用 DELETE /plannedWorkouts/{id}。
• PATCH /plannedWorkouts/{id} 只会更新 planned_date。 它不会重新应用运动员参数。若要更改目标或参数，请先删除训练，再重新安排。
• 各提供商的操作差异很大。 有些提供商不支持更新、检索或删除。即使操作不受支持，仍会返回成功响应，因此成功并不总意味着设备已发生变化。针对特定提供商操作前，请先阅读 references/provider-compatibility.md。
• COROS 更新 = 删除 + 重新创建。 COROS 不支持原地更新，因此“更新”会删除旧训练并创建新训练；provider_workout_id 会发生变化。
• Huawei 仅支持创建、仅支持跑步，且不支持安排训练。 不支持在设备上更新、检索或删除训练。它会忽略 planned_date——训练会立即可用，并且总是返回一条指出这一点的强制转换警告。每位用户的重复训练名称会被拒绝并返回 400。非跑步运动会显示为跑步。
• Zepp 的同步窗口为 7 天（从今天到今天 + 6 天）。安排在窗口之外的训练会存储在 Terra API 的数据库中，但不会推送到设备，直到该用户的后续写入或删除操作触发窗口刷新。系统不会在后台自动同步。
• Hevy 仅支持力量训练。 RPE 目标会被静默丢弃并附带警告；不支持区块重复（一个区块映射为一个练习，一个步骤映射为一组）；且不支持安排训练，也不支持在提供商端删除。支持更新：当 provider_workout_id 存在时，会原地更新现有的 Hevy 训练计划。
• Apple 通过 Terra API iOS SDK 同步。 服务端会将操作加入队列；SDK 将其推送到 WorkoutKit，并通过 POST /v2/plannedWorkouts/{id}/synced 报告结果。在此之前，provider_workout_id 为 null。应用端设置说明见 terra-mobile-sdk 技能。
• Garmin 仅能检索由你自己的凭据创建的训练。 通过其他应用创建或直接在设备上创建的训练，对你的 GET 调用不可见。
• 删除操作会从 Terra API 的数据库中移除训练，但对于没有删除端点的提供商（例如 Huawei、Hevy），设备上可能仍会保留该训练。

参考资料

编写请求前，请先阅读与任务相符的参考文件：

• references/provider-compatibility.md – 完整的操作矩阵（各提供商的创建／更新／检索／删除），以及各提供商对运动类型、目标、完成状态和结构的支持情况与特殊行为。针对特定提供商前，请先阅读此文件。
• references/coercion-scenarios.md – 完整的强制转换场景目录、处理模式（记录／呈现／忽略）和预防清单。依赖提供商可能不支持的功能前，请先阅读此文件。
• references/exercise-reference.md – 运动名称规范化规则、Garmin／Hevy 灵活性表，以及未找到名称时的处理方式。构建力量训练模板前，请先阅读此文件。

有两项内容放在文档中，而非此技能中，因为它们篇幅较长，且会随 API 变化：

• 完整的 Garmin 运动目录（1,624 个名称，Hevy 也使用此目录）：需要选择或验证特定的 exercise_name 时，请获取 https://docs.tryterra.co/planned-workouts-api/garmin-exercise-reference.md。
• 特定运动类型的请求示例（跑步、骑行、游泳、力量训练、多项运动）：需要此文件中示例之外的完整可用请求正文时，请获取 https://docs.tryterra.co/planned-workouts-api/sport-specific-examples.md。

完整 API 文档：docs.tryterra.co/planned-workouts-api。获取页面前，请先使用 terra docs ask（或通过 MCP 使用 docs_ask）提问：它会根据文档作答并引用来源。为任何文档 URL 添加 .md 即可获取 Markdown。