Intervals.icu

Interact with intervals.icu training platform API for activities, workouts, and wellness data.

Environment

Required env vars:

• INTERVALS_API_KEY - API key from intervals.icu Settings → Developer Settings
• INTERVALS_ATHLETE_ID - athlete ID (e.g., i12345, visible in your intervals.icu URL)

Authentication

Use HTTP Basic Auth with “API_KEY” as username and your API key as password:

curl -sS -u "API_KEY:$INTERVALS_API_KEY" "https://intervals.icu/api/v1/..."

Workout Scheduling: Library-First Approach (IMPORTANT)

When scheduling workouts, ALWAYS prefer using existing library workouts over creating workouts from scratch.

Workflow:

1. List the workout library folders and workouts (see below)
2. Find a matching workout for the requested session type
3. Schedule the library workout to the calendar using its workout_id
4. Only create a workout from scratch if no suitable library workout exists

This keeps a stable, curated set of workouts. Periodically review the library with the user to update/add workouts as training evolves.

List Workout Library (Folders + Workouts)

# List all folders and their workouts
curl -sS -u "API_KEY:$INTERVALS_API_KEY" \
  "https://intervals.icu/api/v1/athlete/$INTERVALS_ATHLETE_ID/folders" | jq

List Workouts in a Specific Folder

curl -sS -u "API_KEY:$INTERVALS_API_KEY" \
  "https://intervals.icu/api/v1/athlete/$INTERVALS_ATHLETE_ID/folders/$FOLDER_ID" | jq

Get a Single Library Workout

curl -sS -u "API_KEY:$INTERVALS_API_KEY" \
  "https://intervals.icu/api/v1/athlete/$INTERVALS_ATHLETE_ID/workouts/$WORKOUT_ID" | jq

Schedule a Library Workout to Calendar

When creating an event from a library workout, include the workout_id field:

curl -sS -X POST -u "API_KEY:$INTERVALS_API_KEY" \
  "https://intervals.icu/api/v1/athlete/$INTERVALS_ATHLETE_ID/events" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "WORKOUT",
    "start_date_local": "2026-01-20",
    "workout_id": 12345
  }'

Create a New Library Workout

Only if no existing workout fits. Add it to the appropriate folder:

curl -sS -X POST -u "API_KEY:$INTERVALS_API_KEY" \
  "https://intervals.icu/api/v1/athlete/$INTERVALS_ATHLETE_ID/workouts" \
  -H "Content-Type: application/json" \
  -d '{
    "folder_id": 12345,
    "name": "Easy Z2 Ride",
    "type": "VirtualRide",
    "description": "- 10m ramp 50%-75% 90rpm\n\n- 30m 75% 90rpm\n\n- 5m 50%-40% 85rpm",
    "moving_time": 2700
  }'

Schedule Workout from Scratch (fallback only)

Create a planned workout on the calendar without a library reference:

curl -sS -X POST -u "API_KEY:$INTERVALS_API_KEY" \
  "https://intervals.icu/api/v1/athlete/$INTERVALS_ATHLETE_ID/events" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "WORKOUT",
    "start_date_local": "2026-01-20",
    "name": "Easy Run",
    "type": "Run",
    "description": "- 30min easy\n  Z2 HR",
    "moving_time": 1800
  }'

List Recent Activities

# Get activities from last 7 days
curl -sS -u "API_KEY:$INTERVALS_API_KEY" \
  "https://intervals.icu/api/v1/athlete/$INTERVALS_ATHLETE_ID/activities?oldest=$(date -d '7 days ago' +%Y-%m-%d)&newest=$(date +%Y-%m-%d)" \
  | jq '.[] | {id, name, start_date_local, type, moving_time, distance, icu_training_load}'

Get Single Activity

curl -sS -u "API_KEY:$INTERVALS_API_KEY" \
  "https://intervals.icu/api/v1/activity/$ACTIVITY_ID" | jq

Event Categories

• WORKOUT - planned workout
• RACE_A, RACE_B, RACE_C - races by priority
• NOTE - calendar note
• HOLIDAY, SICK, INJURED - time off

Workout Types

Common types: Ride, VirtualRide, Run, Swim, WeightTraining, Yoga, Walk, Hike

Workout Description Format (intervals.icu native)

Structured workouts use indented steps:

- 10min warmup
  Z2 HR
- 5x
  - 4min
    Z4 Power
  - 2min
    Z2 Power
- 10min cooldown
  Z2 HR

Power zones: Z1-Z7, or use percentages like 95% FTP HR zones: Z1-Z5 HR

List Planned Workouts

# Get events (planned workouts) for a date range
curl -sS -u "API_KEY:$INTERVALS_API_KEY" \
  "https://intervals.icu/api/v1/athlete/$INTERVALS_ATHLETE_ID/events?oldest=$(date +%Y-%m-%d)&newest=$(date -d '+7 days' +%Y-%m-%d)" \
  | jq '.[] | select(.category == "WORKOUT") | {id, name, start_date_local, type, moving_time}'

Update Event

curl -sS -X PUT -u "API_KEY:$INTERVALS_API_KEY" \
  "https://intervals.icu/api/v1/athlete/$INTERVALS_ATHLETE_ID/events/$EVENT_ID" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name", "description": "New description"}'

Delete Event

curl -sS -X DELETE -u "API_KEY:$INTERVALS_API_KEY" \
  "https://intervals.icu/api/v1/athlete/$INTERVALS_ATHLETE_ID/events/$EVENT_ID"

Mark Workout Done

curl -sS -X PUT -u "API_KEY:$INTERVALS_API_KEY" \
  "https://intervals.icu/api/v1/athlete/$INTERVALS_ATHLETE_ID/events/$EVENT_ID/mark-done"

Get Wellness Data

# Get wellness for a specific date
curl -sS -u "API_KEY:$INTERVALS_API_KEY" \
  "https://intervals.icu/api/v1/athlete/$INTERVALS_ATHLETE_ID/wellness/$(date +%Y-%m-%d)" | jq

Update Wellness

curl -sS -X PUT -u "API_KEY:$INTERVALS_API_KEY" \
  "https://intervals.icu/api/v1/athlete/$INTERVALS_ATHLETE_ID/wellness/$(date +%Y-%m-%d)" \
  -H "Content-Type: application/json" \
  -d '{"weight": 75.5, "restingHR": 52, "hrv": 65, "sleepSecs": 28800, "sleepQuality": 4}'

Wellness Fields

• weight - kg
• restingHR - bpm
• hrv - ms
• sleepSecs - seconds of sleep
• sleepQuality - 1-5 scale
• fatigue, mood, motivation, readiness - 1-5 scale
• ctl, atl - fitness/fatigue (usually calculated)

Get Athlete Info

curl -sS -u "API_KEY:$INTERVALS_API_KEY" \
  "https://intervals.icu/api/v1/athlete/$INTERVALS_ATHLETE_ID" \
  | jq '{icu_ftp, icu_weight, icu_hr_zones, icu_power_zones}'

Tips

• All dates are ISO-8601 local dates (e.g., 2026-01-20)
• Times in seconds (e.g., 1800 = 30 min)
• Distances in meters
• Use jq to filter/format JSON responses
• Check API docs at https://intervals.icu/api/v1/docs for full schema
• ALWAYS check the library first before creating workouts from scratch