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 or icloud.

  • 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 or reader.

  • 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"
}
GET/calendars

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 or writer)

  • Name
    provider
    Type
    string
    Description

    Limit calendars to those supplied by a specific provider. Either google, zoho, icloud or outlook.

Request

GET
/calendars
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"
    }
  ]
}
POST/calendars

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

POST
/calendars
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"
  }
}
GET/calendars/:id

Retrieve a calendar

This endpoint allows you to retrieve a calendar by providing the calendar id.

Request

GET
/calendars/cal_0vR36ILzVL
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"
  }
}
PATCH/calendars/:id

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

PATCH
/calendars/cal_0vR36ILzVL
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/calendars/:id

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

DELETE
/calendars/cal_3NsbrDnK4p
curl --location --request DELETE 'https://api.calapi.io/calendars/cal_3NsbrDnK4p' \
  -H 'Authorization: Bearer {token}'

Was this page helpful?