Calendars API

List Calendars

Retrieves all calendar lists from all connected providers (Google Calendar, Microsoft Outlook, Apple Calendar, CalDAV) for the authenticated user.

Fetches the list of calendars from all connected calendar providers and returns a unified array of calendars across all providers with provider-specific metadata including timezone, color, and access role information.

Endpoint: GET /calendars

Response

calendarsArray<Calendar>

Array of calendar objects from all connected providers. Each Calendar object contains:

providerstring

Provider name: 'google', 'microsoft', 'apple', or 'caldav'

idstring

Unique calendar identifier from the provider

titlestring

Display name of the calendar

timeZonestring

Calendar timezone (e.g., "America/New_York")

colorstring

Calendar color code

descriptionstring

Calendar description

originalobject

Original calendar object from the provider

Error Responses

• 401 - Unauthorized. Invalid or missing bearer token
• 500 - Internal Server Error. Provider error or unexpected failure

Examples

REST

Fetch all calendars for authenticated user

GET /calendars

Node.js SDK

const calendars = await client.calendars.list();

Python SDK

calendars = client.calendars.list()

PHP SDK

$calendars = $client->calendars()->list();

.NET SDK

var calendars = await client.Calendars.ListAsync();

Java SDK

List<Calendar> calendars = client.calendars().list();

Go SDK

calendars, err := client.Calendars().List(ctx)

Ruby SDK

calendars = client.calendars.list

Response

[
  {
    "id": "work@company.com",
    "title": "My Calendar",
    "provider": "google",
    "timeZone": "America/Los_Angeles",
    "color": "#9fc6e7",
    "description": "Work calendar"
  },
  {
    "id": "AAMkAGI2T...",
    "title": "Work Calendar",
    "provider": "microsoft",
    "timeZone": "UTC",
    "description": ""
  },
  {
    "id": "E2857962-EE43-4E90-829C-A826D534C0D9",
    "title": "Personal",
    "provider": "apple",
    "timeZone": "America/New_York",
    "description": "Personal events"
  },
  {
    "id": "https://nextcloud.example.com/remote.php/dav/calendars/user/personal/",
    "title": "CalDAV Personal",
    "provider": "caldav",
    "timeZone": "UTC",
    "description": "CalDAV calendar"
  }
]

info

• No query parameters are required for this endpoint
• The endpoint returns calendars from all connected providers in a single response
• Each calendar includes provider-specific metadata where available
• The projectId is automatically retrieved from the user's session cookies