wahoo-api

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: [email protected] (for entitlements) / [email protected]