wahoo-api

name	wahoo-api
description	Authenticate with and call the Wahoo Cloud API. Use when working with Wahoo fitness data: users, plans, workouts, routes, power zones, workout summaries, or webhooks. Triggers on "wahoo", "wahooligan", "ELEMNT", "KICKR", or fitness device API integration.

Wahoo API

Overview

Apply this skill whenever you must talk to Wahoo’s Cloud API: onboarding, fetching user/workout data, creating structured workout plans, scheduling workouts on devices, uploading workout result files, or wiring up offline webhooks. The API is OAuth2-based and expects base64-encoded JSON/FIT payloads for plans and routes.

Quick Start

1. Register the application at https://developers.wahooligan.com. Capture the client_id, client_secret, configured redirect URI, and note whether the app is Sandbox or Production.
2. Confirm the scopes you need (user_read, workouts_write, plans_write, offline_data, etc.). Sandbox apps are rate limited to 25 requests / 5 minutes, 100 / hour, 250 / day.
3. Build the authorize URL:
   https://api.wahooligan.com/oauth/authorize?client_id=<ID>&redirect_uri=<REDIRECT>&scope=<space-separated-scopes>&response_type=code.
4. Exchange the returned code for tokens:
   POST https://api.wahooligan.com/oauth/token with client_id, client_secret (or PKCE code_verifier), grant_type=authorization_code, redirect_uri, code.
5. Persist the access_token, refresh_token, and expires_in. Refresh tokens expire whenever you refresh again; replace stored values immediately.
6. Call resource endpoints under https://api.wahooligan.com/v1/* with Authorization: Bearer <access_token> and Content-Type: application/json.
7. For structured workouts, upload a plan first, then attach it to workouts. Ensure external_id values stay stable to avoid duplicates.
8. Local helper: the wahoolib package is installed in this environment. Use uv run wahoolib ... to drive OAuth flows, manage plans/routes/workouts, or deauthorize tokens without re-implementing requests manually.

Local Tooling

• Python library: wahoolib (bundled with this plugin at src/wahoolib/). Import wahoolib.WahooAPIClient or wahoolib.WahooOAuthClient inside scripts to work with typed models. Install with uv pip install -e <plugin-root> if not already available.
• CLI entry point: run uv run wahoolib <command> from anywhere. Common patterns:
  • uv run wahoolib auth url – build authorization URLs.
  • uv run wahoolib plans create --plan-file plan.json --external-id plan_123 --provider-updated-at 2024-10-20T12:00:00 – upload a structured workout plan.
  • uv run wahoolib workouts upload --fit-file ride.fit --token-file token.json – upload FIT results.
• Environment variables: the CLI automatically reads WAHOO_CLIENT_ID, WAHOO_CLIENT_SECRET, and WAHOO_REDIRECT_URI if set. Export them once to avoid repeating --client-id, etc.
• Tokens: store access/refresh tokens in JSON (the CLI auth exchange --output token.json writes a ready-to-use file). Pass via --token-file token.json on subsequent commands.

Authentication and Scopes

• OAuth2 flows: Standard authorization code or PKCE. PKCE requires code_challenge/code_verifier and setting the app’s “Confidential?” flag to “No”.
• Token refresh:

  curl -X POST https://api.wahooligan.com/oauth/token \
    -d client_id="$WAHOO_CLIENT_ID" \
    -d client_secret="$WAHOO_CLIENT_SECRET" \
    -d grant_type=refresh_token \
    -d refresh_token="$WAHOO_REFRESH_TOKEN"
  

  PKCE refresh requests omit the secret but include code_verifier.
• Key scopes:
  • user_read, user_write, email
  • workouts_read, workouts_write
  • plans_read, plans_write
  • routes_read, routes_write
  • power_zones_read, power_zones_write
  • offline_data (required for webhooks)
• Wahoo limits active tokens per user. Always replace stored tokens after refresh to avoid hitting the “10 unrevoked tokens per user” policy (effective Jan 2026).

Rate Limiting and Environment

• Sandbox: 25 requests / 5 min, 100 / hr, 250 / day.
• Production: 200 / 5 min, 1000 / hr, 5000 / day.
• Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
• Always inspect response headers and throttle proactively; the API returns HTTP 429 on excess.

Core Workflows

1. Manage Plans (structured workout templates)

1. Build a plan JSON file (header + intervals). Follow Wahoo’s format (https://cloud-api.wahooligan.com/docs/plan-json-format.pdf).
   Example interval fields: type, duration, targets (power, HR), cadence.
2. Base64-encode the JSON:

   encoded_plan=$(base64 -w0 plan.json)
   

3. Create or update the plan:

   curl -X POST https://api.wahooligan.com/v1/plans \
     -H "Authorization: Bearer $WAHOO_ACCESS_TOKEN" \
     -d "plan[file]=data:application/json;base64,$encoded_plan" \
     -d "plan[filename]=plan.json" \
     -d "plan[external_id]=fitness-plan-123" \
     -d "plan[provider_updated_at]=2025-10-19T18:00:00Z"
   

4. Store the returned id. Reuse the same external_id when updating.
5. Retrieve with GET /v1/plans/:id or list with GET /v1/plans?external_id=....

2. Schedule Workouts on Devices

1. Ensure the user’s power zones and routes (if required) already exist.
2. Create (or update) a workout:

   curl -X POST https://api.wahooligan.com/v1/workouts \
     -H "Authorization: Bearer $WAHOO_ACCESS_TOKEN" \
     -d "workout[name]=Trainer Ride" \
     -d "workout[workout_token]=ride-2025-10-20" \
     -d "workout[workout_type_id]=61" \
     -d "workout[starts]=2025-10-20T12:00:00Z" \
     -d "workout[minutes]=75" \
     -d "workout[plan_id]=$PLAN_ID"
   

3. Wahoo devices sync only “today + 6 days ahead” workouts, so schedule within that window.
4. If multiple variants exist (e.g., indoor/outdoor), set plan_ids to the array of plan IDs.

3. Upload Workout Results

1. Base64-encode the FIT results:

   encoded_fit=$(base64 -w0 results.fit)
   

2. POST to /v1/workout_file_uploads with optional target_workout_id to map the summary back.
3. Poll /v1/workout_file_uploads/:token until status is complete. Then read workout_id / workout_summary_id.
4. Fetch the workout summary via GET /v1/workouts/:id/workout_summary.

4. Manage Routes and Power Zones

• Routes:

  • Create: POST /v1/routes with base64 FIT data, metadata (distance, ascent, start_lat/lng).
  • Update: PUT /v1/routes/:id.
  • Fetch list: GET /v1/routes optionally filtering by external_id.
  • Note: API routes sync to Wahoo App and head units, but not to the legacy ELEMNT app.

• Power Zones:

  • Create/update via POST/PUT /v1/power_zones.
  • Supply thresholds (zone_1 ... zone_7, ftp, critical_power) plus classification IDs.
  • Read single zone: GET /v1/power_zones/:id; list all: GET /v1/power_zones.

5. User Profile and Deauthorization

• GET /v1/user requires user_read; email scope adds email.
• Update profile data with PUT /v1/user (height, weight, name, gender).
• Revoke access: DELETE /v1/permissions. Optionally configure the developer portal flags to auto-delete plans/workouts on deauth.

6. Webhooks (Offline Data)

1. Enable webhooks in the developer portal; set webhook_enabled, URL, and verification token.
2. Ensure users authorize with offline_data.
3. Receive POST payloads like:

   {
     "event_type": "workout_summary",
     "webhook_token": "...",
     "user": {"id": 12345},
     "workout_summary": {...}
   }
   

4. Acknowledge with HTTP 200 quickly; retries occur at 30 minutes, 4 hours, 24 hours, 72 hours.
5. Fetch additional detail using the IDs in the payload (e.g., GET /v1/workouts/:id).

Implementation Guidelines

• Always set Content-Type: application/json except when sending form-encoded or multipart data (plans, routes, uploads).
• Use external_id everywhere possible to enforce idempotency and make subsequent updates easier.
• For recurring uploads, throttle to avoid hitting sandbox rate limits; prefer batching operations.
• When deleting or replacing plans/workouts on deauth, follow the flags in the portal (“Delete Upcoming Workouts”, “Delete Owned Plans”).
• Sandbox throughput is extremely limited; stage repetitive sync jobs in Production once approved.
• Log the fitness_app_id values in workout summaries—IDs < 1000 indicate Wahoo-owned workouts (uneditable).

Troubleshooting

• 401 Unauthorized: Token expired or revoked. Refresh once; if still failing, re-run the OAuth flow.
• 403 Forbidden: Missing scope or entitlement (e.g., Wahoo Plans). Request additional access via developer support.
• 404 Not Found: The resource belongs to a different user or the external_id never created it.
• 429 Too Many Requests: Wait until X-RateLimit-Reset seconds elapse; exponential backoff unnecessary if you obey the schedule.
• Plan file rejected: Validate JSON against the Wahoo blueprint; ensure only the first target per interval is power when syncing to bike computers.
• Workout not appearing on device: Confirm starts is within 6 days, the plan exists, and the device synced after creation.
• Webhook duplicates: Deduplicate by workout_summary.id and event_type; Wahoo may resend on retries.

References

• Wahoo Cloud API Reference: https://cloud-api.wahooligan.com
• Developer Portal: https://developers.wahooligan.com
• Plan JSON Format PDF: https://cloud-api.wahooligan.com/docs/plan-json-format.pdf
• Rate Limits: see “Registration → Rate Limiting” section in the reference
• Support: [e-mail] (for entitlements) / [e-mail]