Intervals.icu API Skill

Comprehensive guide for interacting with the intervals.icu API to manage athlete training data, activities, workouts, and calendar events.

Authentication

API Key Method

Get your Athlete ID and API Key from [intervals.icu settings page]().

# Using API Key header
curl -H "Authorization: ApiKey API_KEY:YOUR_API_KEY" \

Bearer Token Method (OAuth)

# Using Bearer token
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \

Base URL: **Date Format:** ISO-8601 (e.g., 2024-01-15 or 2024-01-15T10:30:00) --- ## Core Concepts ### Athlete ID Your unique identifier in Intervals.icu. Used in all API endpoints as {id} path parameter. ### Activities vs Events - **Activities**: Completed workouts with actual data (GPS, power, HR). Retrieved from /athlete/{id}/activities - **Events**: Planned workouts on your calendar. Retrieved from /athlete/{id}/events ### Data Fields Activities and events can return different fields. Use the fields query parameter to include/exclude specific data points for more efficient queries. --- ## Getting Activities (Completed Workouts) ### List Activities for Date Range Retrieve all activities between two dates, sorted newest to oldest. __CODE_BLOCK_2__ ### Combine Activities with External Data Use fields parameter to combine activity data with contextual information: __CODE_BLOCK_3__ ### Get Single Activity with Full Details __CODE_BLOCK_4__ ### Export Activity Streams (CSV or JSON) __CODE_BLOCK_5__ --- ## Calendar & Planned Workouts ### List Calendar Events (Planned Workouts) Retrieve planned workouts, notes, and training targets from your calendar. __CODE_BLOCK_6__ ### Get Single Event Details __CODE_BLOCK_7__ ### Download Planned Workout File Export planned workouts in various formats for your training device. __CODE_BLOCK_8__ --- ## Creating & Writing Data ### Create Manual Activity Add a manually-logged activity to your training history. __CODE_BLOCK_9__ ### Create Multiple Activities (Bulk) __CODE_BLOCK_10__ ### Create Planned Workout (Event on Calendar) Add a scheduled workout to your calendar for future training. __CODE_BLOCK_11__ ### Create Multiple Events (Bulk) __CODE_BLOCK_12__ ### Create Training Target (Goal for Date) Set a specific training target for a date. __CODE_BLOCK_13__ --- ## Updating Data ### Update Activity Modify an existing completed activity. __CODE_BLOCK_14__ ### Update Planned Workout (Event) Modify a scheduled event on your calendar. __CODE_BLOCK_15__ ### Update Multiple Events (Date Range) __CODE_BLOCK_16__ --- ## Wellness & Recovery Data ### Get Wellness Records Track sleep, fatigue, resting HR, and other wellness metrics. __CODE_BLOCK_17__ ### Update Wellness Record Log wellness data for a specific date. __CODE_BLOCK_18__ ### Bulk Update Wellness Records __CODE_BLOCK_19__ --- ## Sport Settings & Zones ### Get Sport Settings Retrieve power zones, HR zones, and FTP settings for a sport. __CODE_BLOCK_20__ ### Update Sport Settings Modify power zones, FTP, or HR zones. __CODE_BLOCK_21__ --- ## Common Use Cases ### Workflow: Sync Training Data with External System __CODE_BLOCK_22__ ### Workflow: Create Weekly Training Plan __CODE_BLOCK_23__ ### Workflow: Analyze Week Data __CODE_BLOCK_24__ --- ## Important Notes ### Rate Limiting Be respectful with API calls. Don't hammer the API with rapid successive requests. ### Field Selection Use the fields parameter to request only the data you need. This improves performance and reduces payload size. ### Date Formats Always use ISO-8601 format: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS ### Upsert Parameter When creating events, use upsertOnUid=true to update existing events with matching UIDs instead of creating duplicates. ### External IDs Use external_id` when syncing data from other systems to avoid duplicates on re-sync.

Forum Discussion

For more detailed API information, see: [API Access Forum Post]()

---

Response Status Codes

• 200: Success
• 201: Created successfully (activities, events)
• 400: Bad request (invalid parameters)
• 401: Unauthorized (invalid API key or token)
• 404: Not found (invalid IDs)
• 429: Rate limited (too many requests)
• 500: Server error

Check response headers for error details and rate limit information.