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.

CODEBLOCK0

Bearer Token Method (OAuth)

CODEBLOCK1

Base URL: INLINECODE0

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 INLINECODE4
• Events: Planned workouts on your calendar. Retrieved from INLINECODE5

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.

CODEBLOCK2

Combine Activities with External Data

Use fields parameter to combine activity data with contextual information:

CODEBLOCK3

Get Single Activity with Full Details

CODEBLOCK4

Export Activity Streams (CSV or JSON)

CODEBLOCK5

Calendar & Planned Workouts

List Calendar Events (Planned Workouts)

Retrieve planned workouts, notes, and training targets from your calendar.

CODEBLOCK6

Get Single Event Details

CODEBLOCK7

Download Planned Workout File

Export planned workouts in various formats for your training device.

CODEBLOCK8

Creating & Writing Data

Create Manual Activity

Add a manually-logged activity to your training history.

CODEBLOCK9

Create Multiple Activities (Bulk)

CODEBLOCK10

Create Planned Workout (Event on Calendar)

Add a scheduled workout to your calendar for future training.

CODEBLOCK11

Create Multiple Events (Bulk)

CODEBLOCK12

Create Training Target (Goal for Date)

Set a specific training target for a date.

CODEBLOCK13

Updating Data

Update Activity

Modify an existing completed activity.

CODEBLOCK14

Update Planned Workout (Event)

Modify a scheduled event on your calendar.

CODEBLOCK15

Update Multiple Events (Date Range)

CODEBLOCK16

Wellness & Recovery Data

Get Wellness Records

Track sleep, fatigue, resting HR, and other wellness metrics.

CODEBLOCK17

Update Wellness Record

Log wellness data for a specific date.

CODEBLOCK18

Bulk Update Wellness Records

CODEBLOCK19

Sport Settings & Zones

Get Sport Settings

Retrieve power zones, HR zones, and FTP settings for a sport.

CODEBLOCK20

Update Sport Settings

Modify power zones, FTP, or HR zones.

CODEBLOCK21

Common Use Cases

Workflow: Sync Training Data with External System

CODEBLOCK22

Workflow: Create Weekly Training Plan

CODEBLOCK23

Workflow: Analyze Week Data

CODEBLOCK24

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 INLINECODE10

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.