terra-planned-workouts

Terra API 計画ワークアウト

構造化されたワークアウトをユーザーのフィットネスデバイスに直接送信できます。ワークアウトテンプレートを一度定義すると、Terra API がユーザーの接続済みデバイス（Garmin、COROS、Wahoo、Suunto、TrainingPeaks、Huawei、Zepp、Hevy、Apple）のいずれかに同期します。これはデバイスへの書き込みを行う製品であり、読み取りを中心とする Terra API の Health & Fitness データフローとは逆のものです。

プレリリース。 この製品はプレリリースです。一般提供の開始前に、エンドポイント、フィールド、プロバイダーの動作が変更される可能性があります。ここに記載されている情報は 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と行の作成日時）が格納されます。

最初の3つのコマンドはterra data-apiです。これはCLIでのみ使用できます。MCPでは、管理ツールでワークアウトのメタデータのみを扱えます。

コーディングエージェント（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はmethod: "list"を持つusers_readです）。terra data-api、terra admin-api、terra examplesを使用できるのはCLIのみで、--selectと--jqにはMCPでの同等機能はありません。terra-cliとterra-mcpのスキルには、変更の確認や認証情報をトランスクリプトに残さないためのガードレール、エラー、タスクごとの手順が含まれています。これらは連携を管理するものであり、このスキルで説明するAPI呼び出しに取って代わるものではありません。

2段階のワークフロー

ベース URL はhttps://access.tryterra.co/api/v2です。すべてのリクエストに2つのヘッダーが必要です。dev-id（Terra API の開発者 ID）とx-api-key（Terra API キー）です。

フェーズ1 – テンプレートを作成する（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 では文字列としてシリアライズされます。JavaScript クライアントでは、2^53を超える数値の精度が失われるためです。成功時、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}	予定済みワークアウトを1件取得します
GET	/plannedWorkouts?user_id=X	ユーザーのスケジュール済みワークアウトを一覧表示します（start_date と end_date のフィルターは任意ですが、両方を同時に指定する必要があります。片方のみの場合は無視されます）
PATCH	/plannedWorkouts/{id}?user_id=X	スケジュール日を更新します。planned_date のみで、アスリートのパラメーターは更新できません
DELETE	/plannedWorkouts/{id}?user_id=X	1人のユーザーのワークアウトのスケジュールを解除します

データモデル

テンプレートは階層構造です：WorkoutTemplate → step_blocks[] → steps[] → intensity_targets[]。

WorkoutTemplate – name（必須）、sport（必須）、任意の description、environment（indoor / outdoor / pool）、および pool_length_meters（水泳のみ）。ブロックが少なくとも1つ必要です。

step_blocks[] – まとめて実行するステップのグループです。ブロックの completion_condition によって繰り返しが制御されます。

ブロックの条件	動作
{"type":"reps","value":4}	すべてのステップを4回繰り返す
{"type":"time","value":1200}	合計20分になるまで繰り返す
{"type":"distance","value":5000}	合計5 kmになるまで繰り返す
{"type":"open"} または省略	1回実行する（繰り返しなし）

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[] – ステップの目標指標です。3つのグループがあります。

• 絶対値 – 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}は連鎖的に削除し、元に戻せません。 まず、そのテンプレートにリンクされているすべての予定ワークアウトを、すべてのプロバイダーを通じて、すべてのユーザーのデバイスから削除し、その後テンプレートを削除します。他のユーザーに影響を与えずに1人のユーザーの予定を解除するには、代わりに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ターゲットは警告とともに通知なしで破棄され、ブロックの繰り返しには対応していません（1つのブロックが1つのエクササイズに、1つのステップが1セットに対応します）。スケジュール機能とプロバイダー側での削除機能もありません。更新には対応しており、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に合わせて大容量かつ頻繁に変更されるため、このスキルではなくドキュメントに掲載されている情報が2つあります。

• 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形式で取得できます。