Calendars
A calendar /ˈkalɪndə/ is a collection of events. Each of your connected accounts may expose multiple calendars so for example, you might have a primary "Default Calendar" in Google Calendar but also various secondary calendars for work, national holidays or sports fixtures.
The calendar model
The calendar model contains metadata about the calendar. It does not include the events themselves.
Properties
- Name
id
- Type
- string
- Description
Unique identifier for the calendar in the Calapi API.
- Name
title
- Type
- string
- Description
Title of the calendar
- Name
description
- Type
- string?
- Description
Description of the calendar
- Name
time_zone
- Type
- string?
- Description
The default time zone for events in the calendar. (Formatted as an IANA Time Zone Database name, e.g. "Europe/London").
- Name
color
- Type
- string
- Description
The color of the calendar as a hex string
- Name
provider
- Type
- string
- Description
The provider of this calendar. Either
google
,zoho
,ics
,caldav
oricloud
.
- Name
provider_id
- Type
- string
- Description
The internal id used by the provider to refer to this calendar
- Name
access_role
- Type
- string
- Description
The access role that you have for this calendar. It will either be
writer
orreader
.
- Name
canonical_url
- Type
- string
- Description
The calendar's URL in the Calapi API. You can use this to update or delete the Calendar.
The Calendar Model
{
"id": "cal_p0L6j8LRO2",
"title": "Wimbledon Fixtures",
"description": null,
"time_zone": "Europe/London",
"color": "#9fc6e7",
"provider": "google",
"provider_id": "683ba11dd0461455dfee555e4@group.calendar.google.com",
"account_id": "aco_F3zci1umme",
"access_role": "writer",
"canonical_url": "https://api.calapi.io/calendars/cal_p0L6j8LRO2"
}
List all calendars
This endpoint allows you to retrieve a list of all your calendars from all your providers.
Optional query parameters
- Name
access_role
- Type
- string
- Description
Filter calendars by their access role (either
reader
orwriter
)
- Name
provider
- Type
- string
- Description
Limit calendars to those supplied by a specific provider. Either
google
,zoho
,icloud
oroutlook
.
Request
curl --location 'https://api.calapi.io/calendars' \
-H 'Authorization: Bearer {token}'
Response
{
"data": [
{
"id": "cal_p0L6j8LRO2",
"title": "Default Calendar",
"description": null,
"time_zone": "Europe/London",
"color": "#9fc6e7",
"provider": "google",
"provider_id": "jonathan@calapi.io",
"account_id": "aco_F3zci1umme",
"access_role": "writer",
"canonical_url": "https://api.calapi.io/calendars/cal_p0L6j8LRO2"
},
{
"id": "cal_28tYRZq9WE",
"title": "Tottenham Games",
"description": "Tottenham Hotspur Fixtures 2024",
"time_zone": "Europe/London",
"color": "#fad165",
"provider": "google",
"provider_id": "683ba11dd0461455dfee555e4@group.calendar.google.com",
"account_id": "aco_F3zci1umme",
"access_role": "reader",
"canonical_url": "https://api.calapi.io/calendars/cal_28tYRZq9WE"
}
]
}
Create a calendar
This endpoint allows you to create a new calendar on one of your providers. It will return a 201
status code on success.
Required body parameters
- Name
account_id
- Type
- string
- Description
The id of the account you want to create a calendar for. You can find the id of an account by clicking on the account name in the accounts section of the dashboard.
- Name
title
- Type
- string
- Description
The title of the new calendar
Optional body parameters
- Name
description
- Type
- string
- Description
The description of the calendar
- Name
time_zone
- Type
- string
- Description
The default time zone for the calendar. (Formatted as an IANA Time Zone Database name, e.g. "Europe/London").
Request
curl --location 'https://api.calapi.io/calendars' \
--header 'Authorization: Bearer {token}' \
--data '{
"title": "Roland Garos Fixtures",
"description": "All fixtures for Roland Garos 2024",
"time_zone": "Europe/Paris",
"account_id": "aco_F3zci1umme"
}'
Response
{
"data": {
"id": "cal_0vR36ILzVL",
"title": "Roland Garos Fixtures",
"description": "All fixtures for Roland Garos 2024",
"time_zone": "Europe/Paris",
"color": "#cd74e6",
"provider": "google",
"provider_id": "378fd4e1e6553f890e6d64414589cd21bd17d2497d341e1741533adfc6fb59e4@group.calendar.google.com",
"account_id": "aco_F3zci1umme",
"access_role": "writer",
"canonical_url": "https://api.calapi.io/calendars/cal_0vR36ILzVL"
}
}
Retrieve a calendar
This endpoint allows you to retrieve a calendar by providing the calendar id.
Request
curl --location 'https://api.calapi.io/calendars/cal_0vR36ILzVL' \
-H 'Authorization: Bearer {token}'
Response
{
"data": {
"id": "cal_0vR36ILzVL",
"title": "Roland Garos Fixtures",
"description": "All fixtures for Roland Garos 2024",
"time_zone": "Europe/Paris",
"color": "#cd74e6",
"provider": "google",
"provider_id": "378fd4e1e6553f890e6d64414589cd21bd17d2497d341e1741533adfc6fb59e4@group.calendar.google.com",
"account_id": "aco_F3zci1umme",
"access_role": "writer",
"canonical_url": "https://api.calapi.io/calendars/cal_0vR36ILzVL"
}
}
Update a calendar
This endpoint allows you to perform an update on a calendar. Examples of updates are adding a reaction, editing the calendar, or adding an attachment.
Optional body parameters
- Name
title
- Type
- string
- Description
The updated title of the calendar
- Name
description
- Type
- string
- Description
The updated description of the calendar
- Name
time_zone
- Type
- string
- Description
The updated time zone for the calendar. (Formatted as an IANA Time Zone Database name, e.g. "Europe/Paris").
Request
curl --location 'https://api.calapi.io/calendars/cal_0vR36ILzVL' \
--header 'Authorization: Bearer {token}' \
--data '{
"title": "Roland Garos Fixtures 2025",
"description": "New Roland Garos 2025 schedule"
}'
Response
{
"data": {
"id": "cal_0vR36ILzVL",
"title": "Roland Garos Fixtures 2025",
"description": "New Roland Garos 2025 schedule",
"time_zone": "Europe/Paris",
"color": "#cd74e6",
"provider": "google",
"provider_id": "378fd4e1e6553f890e6d64414589cd21bd17d2497d341e1741533adfc6fb59e4@group.calendar.google.com",
"account_id": "aco_F3zci1umme",
"access_role": "writer",
"canonical_url": "https://api.calapi.io/calendars/cal_0vR36ILzVL"
}
}
Delete a calendar
This endpoint allows you to delete calendars. Note: The calendar will be permanently deleted.
On success a 204
status code will be returned with an empty response.
Request
curl --location --request DELETE 'https://api.calapi.io/calendars/cal_3NsbrDnK4p' \
-H 'Authorization: Bearer {token}'