Intervals Icu

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=""

# 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 INTERVALS_MAX_RETRIES 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:

| Command | Description | |---------|-------------| | api.sh wellness [date] | Get wellness for date (default: today) | | api.sh wellness-range | Get wellness for date range | | api.sh wellness-update | Update wellness fields | | api.sh activities [format] [--all] | List activities (--all for pagination) | | api.sh activity | Get single activity details | | api.sh activity-streams [types] | Get activity data streams | | api.sh activity-upload | Upload activity (.fit, .gpx, .tcx) | | api.sh athlete | Get athlete profile | | api.sh fitness | Get current CTL/ATL/TSB | | api.sh zones | Get power/HR zone settings | | api.sh events | Get planned events/workouts | | api.sh event-create | Create planned workout/event | | api.sh power-curves [format] | Power curves (json/summary/seconds) |

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 "file=@ride.fit" "$BASE/athlete/$INTERVALS_ATHLETE_ID/activities"

Key Endpoints Reference

| Endpoint | Method | Purpose | |----------|--------|---------| | /athlete/{id} | GET | Athlete profile | | /athlete/{id}/wellness/{date} | GET/PUT | Wellness data | | /athlete/{id}/wellness | GET | Wellness range (add ?oldest=&newest=) | | /athlete/{id}/activities | GET | Activities list | | /activity/{id} | GET | Activity details | | /activity/{id}/streams | GET | Activity data streams | | /athlete/{id}/events | GET | Planned workouts/events | | /athlete/{id}/power-curves | GET | Power duration curves |

Wellness Fields

| Field | Type | Range | Description | |-------|------|-------|-------------| | weight | float | 30-200 kg | Body weight | | restingHR | int | 30-100 bpm | Resting heart rate | | hrv | float | 10-150 ms | HRV RMSSD (typical: 20-80) | | hrvSDNN | float | 10-200 ms | HRV SDNN | | sleepSecs | int | 0-43200 | Sleep duration (0-12h in seconds) | | sleepScore | float | 0-100 | Sleep quality percentage | | sleepQuality | int | 1-5 | 1=poor, 5=excellent | | fatigue | int | 1-5 | 1=fresh, 5=exhausted | | mood | int | 1-5 | 1=bad, 5=great | | motivation | int | 1-5 | Training motivation | | readiness | int | 1-5 | Training readiness | | stress | int | 1-5 | Stress level | | soreness | int | 1-5 | Muscle soreness | | ctl | float | 0-200 | Chronic Training Load (fitness) | | atl | float | 0-300 | Acute Training Load (fatigue) | | 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 "$SKILLS_DIR/intervals-icu/scripts/api.sh" wellness-range 2024-01-01 2024-01-31 > wellness.json "$SKILLS_DIR/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

| HRV vs Baseline | TSB | Recommendation | |-----------------|-----|----------------| | >+10% | >0 | Execute as planned or add intensity | | ±10% | >0 | Execute as planned | | ±10% | 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: disco-trooper
• Source: disco-trooper/skills
• License: MIT

Install and usage instructions live in the source repository linked above.