This guide explains how to upload calendar events (e.g. workouts) from an external application to an athlete’s Intervals.icu calendar using the API. For more information about the API including OAuth support please see this post.
You need to request CALENDAR:WRITE scope to make changes to an athlete’s calendar. All the calendar related endpoints are documented here.
Intervals.icu calendar events have an id (primary key) and optional external_id (your primary key). You do not need to use external_id but if you do, you might be able to avoid having to store an Intervals.icu event id in your system. This guide uses external_id.
To create and/or update calendar events (upsert) call this endpoint with an array of events (workouts):
POST https://intervals.icu/api/v1/athlete/{id}/events/bulk?upsert=true
[{
"category": "WORKOUT",
"start_date_local": "2024-03-30T00:00:00",
"filename": "Woddle_Toddle.fit",
"file_contents_base64": "DiCNCG8AAAAuRklUKz9AAAEAAAMBAoQAAQAIDgcAAP8FSW50ZXJ2YWxzLmljdQBAAAEAGgMEAQAIDgcGAoQAAVdvZGRsZSBUb2RkbGUAAAFAAAEAGwcBAQACBIYDAQAFBIYGBIYHAQD+AoQAAAA27oABAAAA+AAAAQAEAAAe/A==",
"external_id": "1234"
},
{
"category": "WORKOUT",
"start_date_local": "2024-04-01T00:00:00",
"filename": "Woddle_Toddle2.fit",
"file_contents_base64": "DiCNCG8AAAAuRklUKz9AAAEAAAMBAoQAAQAIDgcAAP8FSW50ZXJ2YWxzLmljdQBAAAEAGgMEAQAIDgcGAoQAAVdvZGRsZSBUb2RkbGUAAAFAAAEAGwcBAQACBIYDAQAFBIYGBIYHAQD+AoQAAAA27oABAAAA+AAAAQAEAAAe/A==",
"external_id": "1235"
},
{
"category": "NOTE",
"start_date_local": "2024-04-01T00:00:00",
"name": "Build",
"description": "Start of build phase",
"color": "green",
"external_id": "1236"
}]
The athlete {id} in the path can be zero to use athlete associated with the bearer token or API key.
POST https://intervals.icu/api/v1/athlete/0/events/bulk?upsert=true
Use your primary key in the external_id field. Events that do not exist will be created. Those that already exist are updated. The external_id is only matched against events created by your application.
For planned workouts you can supply a filename and base 64 encode the file in file_contents_base64 (zwo, fit, mrc and erg are accepted) or you can use “description” and supply native Intervals.icu workout text. ZWO workouts are also accepted in “file_contents” as is with no base 64 encoding.
A full representation of each updated or created event is returned:
[{
"id": 33375903,
"start_date_local": "2024-03-30T00:00:00",
...
"type": "Run",
"calendar_id": 1,
"uid": "e2597b1c-9ca8-4156-8737-4251e6bbb313",
"athlete_id": "2049151",
"category": "WORKOUT",
...
To delete calendar events call this endpoint with an array of objects each with external_id or id of an event to delete:
PUT https://intervals.icu/api/v1/athlete/{id}/events/bulk-delete
[
{"external_id": "1234"},
{"id": 33375896}
]
Events that do not exist are ignored. The number of events actually deleted is returned.
You can list all events on an athlete’s calendar for a date range using the list endpoint. This returns all events, not just the ones created by your application. You can filter for your client id using the oauth_client_id field.
