Intervals.icu API Skill

Skill Relationship

┌─────────────────┐     fetch data      ┌───────────────────┐
│  intervals-icu  │ ──────────────────► │ cycling-training  │
│   (DATA API)    │                     │    (ANALYSIS)     │
│                 │ ◄────────────────── │                   │
│ • wellness      │   interpret results │ • zone calc       │
│ • activities    │                     │ • periodization   │
│ • power curves  │                     │ • workout design  │
│ • fitness       │                     │ • load management │
└─────────────────┘                     └───────────────────┘

Usage pattern:

1. Use intervals-icu to fetch data from API
2. Use cycling-training to analyze and interpret
3. Use intervals-icu to update wellness/events

API wrapper for intervals.icu cycling training platform. Designed to work alongside the cycling-training skill.

Quick Start

# Set credentials (one-time)
export INTERVALS_API_KEY="your_api_key"
export INTERVALS_ATHLETE_ID="iXXXXX"

# Set skill directory for local installs
SKILLS_DIR="<path-to-your-skills-dir>"

# Use the API helper
"$SKILLS_DIR/intervals-icu/scripts/api.sh" wellness today
"$SKILLS_DIR/intervals-icu/scripts/api.sh" activities 2024-01-01 2024-01-31

Authentication

Get your API key from https://intervals.icu/settings → Developer Settings → API Key.

Find athlete ID in the URL when logged in: intervals.icu/athlete/iXXXXX/...

Rate Limiting

Intervals.icu API has rate limits. The script handles this with:

• Automatic retry with exponential backoff (default: 3 attempts)
• Configurable via INTERVALSMAXRETRIES environment variable

# Increase retries for bulk operations
export INTERVALS_MAX_RETRIES=5

If you hit rate limits frequently:

• Add delays between bulk requests: sleep 1
• Use date ranges instead of individual requests
• Cache responses locally for analysis

Prerequisites

• curl - Pre-installed on most systems
• jq - brew install jq (macOS) / apt install jq (Linux)
• bats-core - Optional, for tests: brew install bats-core

API Helper Script

Use scripts/api.sh to handle authentication and common operations:

Examples

# Get today's wellness
"$SKILLS_DIR/intervals-icu/scripts/api.sh" wellness

# Get wellness for specific date
"$SKILLS_DIR/intervals-icu/scripts/api.sh" wellness 2024-01-15

# Update wellness (weight and sleep)
"$SKILLS_DIR/intervals-icu/scripts/api.sh" wellness-update 2024-01-15 '{"weight": 72.5, "sleepSecs": 28800}'

# Get last month's activities
"$SKILLS_DIR/intervals-icu/scripts/api.sh" activities 2024-01-01 2024-01-31

# Export activities as CSV
"$SKILLS_DIR/intervals-icu/scripts/api.sh" activities 2024-01-01 2024-01-31 csv > activities.csv

Direct curl Examples

For custom operations not covered by the helper:

# Base URL
BASE="https://intervals.icu/api/v1"

# Auth header
AUTH="Authorization: Basic $(echo -n "API_KEY:$INTERVALS_API_KEY" | base64)"

# Get power curve
curl -s -H "$AUTH" "$BASE/athlete/$INTERVALS_ATHLETE_ID/power-curves?oldest=2024-01-01&newest=2024-12-31"

# Get streams for activity
curl -s -H "$AUTH" "$BASE/activity/iXXXX/streams?types=watts,heartrate,cadence"

# Upload activity
curl -s -H "$AUTH" -F "[email protected]" "$BASE/athlete/$INTERVALS_ATHLETE_ID/activities"

Key Endpoints Reference

Wellness Fields

| rampRate | float | -10 to +10 | CTL weekly change rate

Integrate with cycling-training

Use both skills together:

1. Fetch data with intervals-icu skill:

``bash "$SKILLSDIR/intervals-icu/scripts/api.sh" wellness-range 2024-01-01 2024-01-31 > wellness.json "$SKILLSDIR/intervals-icu/scripts/api.sh" activities 2024-01-01 2024-01-31 > activities.json ``

1. Analyze with cycling-training skill:

- Calculate training load distribution - Check polarization index - Evaluate recovery status based on HRV trends - Plan next mesocycle based on CTL/ATL/TSB

1. Update wellness after morning check-in:

``bash "$SKILLS_DIR/intervals-icu/scripts/api.sh" wellness-update today '{"weight": 72.5, "sleepSecs": 28800, "readiness": 4}' ``

End-to-End Workflow Example

Complete example: Morning HRV-based workout adjustment using both skills.

Scenario

You wake up, check HRV, and want to adjust today's planned workout based on recovery status.

Step 1: Fetch morning wellness data

# Get today's wellness (HRV from device sync)
WELLNESS=$("$SKILLS_DIR/intervals-icu/scripts/api.sh" wellness today)
echo "$WELLNESS" | jq '{hrv, restingHR, sleepSecs, ctl, atl}'

Output:

{
  "hrv": 42.5,
  "restingHR": 54,
  "sleepSecs": 25200,
  "ctl": 65.3,
  "atl": 72.1
}

Step 2: Analyze with cycling-training skill

Based on the data:

• HRV: 42.5 ms (below your baseline of 50 ms = -15%)
• TSB: 65.3 - 72.1 = -6.8 (slightly fatigued)
• Sleep: 7 hours (adequate but not optimal)

cycling-training recommendation: Reduce intensity. Convert threshold workout to endurance/recovery.

Step 3: Update today's planned event

# Find today's planned workout
TODAY=$(date +%Y-%m-%d)
EVENTS=$("$SKILLS_DIR/intervals-icu/scripts/api.sh" events $TODAY $TODAY)
EVENT_ID=$(echo "$EVENTS" | jq -r '.[0].id')

# Update to easier workout
"$SKILLS_DIR/intervals-icu/scripts/api.sh" event-update "$EVENT_ID" '{
  "name": "Recovery Ride (HRV adjusted)",
  "description": "Original: Threshold intervals. Adjusted due to low HRV (-15% from baseline).",
  "icu_training_load": 40
}'

Step 4: Log subjective wellness

"$SKILLS_DIR/intervals-icu/scripts/api.sh" wellness-update today '{
  "readiness": 3,
  "fatigue": 3,
  "mood": 4,
  "soreness": 2
}'

Decision Matrix

Testing

Run the test suite:

# Requires: bats-core
# Install: brew install bats-core (macOS) or apt install bats (Linux)

"$SKILLS_DIR/intervals-icu/tests/run_tests.sh"

Tests verify:

• Help and argument validation
• Environment variable checks
• Date parsing (cross-platform)
• JSON parsing with mock fixtures
• Power curve calculations

Troubleshooting

Common Errors

Debug Mode

Enable verbose output for debugging:

# Show curl commands
export INTERVALS_DEBUG=1
"$SKILLS_DIR/intervals-icu/scripts/api.sh" wellness today

Common Issues

Issue: Activities not syncing from Garmin/Wahoo

• Check device sync in intervals.icu settings
• Verify connection status with fitness platform
• Manual upload: api.sh activity-upload ride.fit

Issue: HRV not appearing in wellness

• HRV requires compatible device (Garmin, Wahoo, Oura, etc.)
• Check device sync completed before fetching
• Some devices sync HRV with delay (up to 2 hours)

Issue: Power curves show 0 for some durations

• Need activity with sustained effort at that duration
• Indoor trainers may have gaps in data
• Check activity streams: api.sh activity-streams <id> watts

Issue: CSV export has wrong encoding

• Intervals.icu returns UTF-8
• If Excel shows garbled text: Import as UTF-8, not auto-detect

Undocumented Endpoints

For endpoints not covered by api.sh, inspect the current Intervals.icu API documentation before adding a helper command. Prefer extending scripts/api.sh with a tested command over embedding one-off curl snippets in the skill body.

Common Workflows

Morning Wellness Check-in

# Get HRV device data (if synced)
"$SKILLS_DIR/intervals-icu/scripts/api.sh" wellness today

# Update subjective metrics
"$SKILLS_DIR/intervals-icu/scripts/api.sh" wellness-update today '{"readiness": 4, "mood": 4, "soreness": 2}'

Weekly Training Review

# Get last 7 days
END=$(date +%Y-%m-%d)
START=$(date -v-7d +%Y-%m-%d 2>/dev/null || date -d "7 days ago" +%Y-%m-%d)

"$SKILLS_DIR/intervals-icu/scripts/api.sh" activities $START $END
"$SKILLS_DIR/intervals-icu/scripts/api.sh" wellness-range $START $END
"$SKILLS_DIR/intervals-icu/scripts/api.sh" fitness  # Current CTL/ATL/TSB

Export for Analysis

# CSV export for spreadsheet analysis
"$SKILLS_DIR/intervals-icu/scripts/api.sh" activities 2024-01-01 2024-12-31 csv > yearly_activities.csv
"$SKILLS_DIR/intervals-icu/scripts/api.sh" wellness-range 2024-01-01 2024-12-31 csv > yearly_wellness.csv