Skip to main content

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

accountstring

The connected account this calendar belongs to.

readOnlyboolean

true when the authenticated connection cannot write to this 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​

Fetch all calendars for authenticated user
GET /calendars
Response
[
  {
    "id": "work@company.com",
    "title": "My Calendar",
    "provider": "google",
    "account": "work@company.com",
    "readOnly": false,
    "timeZone": "America/Los_Angeles",
    "color": "#9fc6e7",
    "description": "Work calendar"
  },
  {
    "id": "team-holidays@group.calendar.google.com",
    "title": "Team Holidays",
    "provider": "google",
    "account": "personal@gmail.com",
    "readOnly": true,
    "timeZone": "America/Los_Angeles",
    "color": "#dbadff",
    "description": "Shared holiday calendar"
  },
  {
    "id": "AAMkAGI2T...",
    "title": "Work Calendar",
    "provider": "microsoft",
    "account": "work@company.com",
    "readOnly": false,
    "timeZone": "UTC",
    "description": ""
  },
  {
    "id": "E2857962-EE43-4E90-829C-A826D534C0D9",
    "title": "Personal",
    "provider": "apple",
    "account": "user@icloud.com",
    "readOnly": false,
    "timeZone": "America/New_York",
    "description": "Personal events"
  },
  {
    "id": "https://nextcloud.example.com/remote.php/dav/calendars/user/personal/",
    "title": "CalDAV Personal",
    "provider": "caldav",
    "account": "user@nextcloud.example.com",
    "readOnly": false,
    "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
  • When a user has connected more than one account on the same provider, account tells you which one owns each calendar — useful before showing a calendar picker or writing to a specific one
  • The projectId is automatically retrieved from the user's session cookies