Skip to main content

Calendar API

All endpoints require authentication.

Google Integration​

Initiate Google Connection​

Generates a Google OAuth authorization URL wrapped by WorkOS. The frontend should redirect the user to the returned redirectUrl to begin the consent flow.

Endpoint: POST /api/v1/calendar/google/connect

Request Body:

{
  "state": "random_string_xyz",
  "codeChallenge": "pkce_challenge_string"
}

Parameters:

  • state (required): A random string generated by the client to prevent CSRF attacks.
  • codeChallenge (required): The PKCE code challenge generated by the client.

Success Response: 200 OK


{
  "authData": {
    "redirectUrl": "https://api.workos.com/oauth/authorize?response_type=code&client_id=...&provider=Google..."
  }
}

Finalize Connection​

Completes the OAuth flow by exchanging the authorization code for access and refresh tokens. This endpoint is called after the user is redirected back from Google/WorkOS.

Endpoint: POST /api/v1/calendar/google/finalize-connection

Request Body:

{
  "code": "0192e...",
  "codeVerifier": "pkce_verifier_string..."
}

Parameters:

  • code (required): The authorization code received in the query parameters from the WorkOS redirect.
  • codeVerifier (required): The original PKCE verifier used to generate the codeChallenge in the initiate step.

Success Response: 200 OK

List Calendars​

Retrieves the list of all calendars associated with the user's Google account (e.g., Primary, Birthdays, Shared Calendars).

Endpoint: GET /api/v1/calendar/google/calendars

Request Body: None

Success Response: 200 OK

[
  {
    "id": "primary",
    "name": "john.doe@example.com",
    "color": "#123456"
  },
  {
    "id": "addressbook#contacts@group.v.calendar.google.com",
    "name": "Birthdays",
    "color": "#92e1c0"
  }
]

Batch List Events​

Retrieves events for multiple calendars or time ranges in a single request. This endpoint is optimized to reduce payload size by returning instances for recurring events (expanded) but stripping unused metadata.

Endpoint: POST /api/v1/calendar/google/events

Request Body:

{
  "calendars": [
    {
      "calendarId": "primary",
      "timeMin": "2025-12-01T00:00:00Z",
      "timeMax": "2026-01-31T23:59:59Z"
    },
    {
      "calendarId": "team@example.com",
      "timeMin": "2025-12-01T00:00:00Z",
      "timeMax": "2026-01-31T23:59:59Z"
    }
  ]
}

Parameters:

  • calendarId (required): The ID of the calendar to fetch (use "primary" for the main calendar).
  • timeMin (required): Start of the time range (RFC3339 format).
  • timeMax (required): End of the time range (RFC3339 format).

Success Response: 200 OK

Returns an array of objects, each representing a calendar's result

[
  {
    "calendarId": "primary",
    "events": [
      {
        "id": "73qusdveu121_20260119T110000Z",
        "calendarId": "primary",
        "title": "Weekly Standup",
        "start": "2026-01-19T12:00:00+01:00",
        "startTimezone": "Europe/Rome",
        "end": "2026-01-19T12:30:00+01:00",
        "endTimezone": "Europe/Rome",
        "recurringEventId": "73qusdveu121", 
        "organizer": { 
          "email": "boss@example.com" 
          },
        "attendees": [
          { 
            "email": "me@example.com", 
            "status": "accepted"
          }
        ]
      }
    ]
  },
  {
    "calendarId": "anothercalendar@example.com",
    "events": [
      {
        "id": "73qusdv42dd121_20260319T110000Z",
        "calendarId": "anotherone",
        "title": "Hello World",
        "start": "2026-01-19T12:00:00+01:00",
        "startTimezone": "Europe/Rome",
        "end": "2026-01-19T12:30:00+01:00",
        "endTimezone": "Europe/Rome",
        "recurringEventId": "3qusdv42dd121", 
        "organizer": { 
          "email": "team@example.com"
          },
        "attendees": [
          { 
            "email": "me@example.com", 
            "status": "pending" 
            }
        ]
      }
    ],
  }
]

Batch Get Event Details​

Retrieves full details for specific events given a list of IDs.

Primary Use Case: Fetching the "Master" event for a recurring series to obtain the recurrence rule (RRULE), which is usually missing from the expanded instances returned by the List endpoint.

Endpoint: POST /api/v1/calendar/google/events/details

Request Body:

{
  "events": [
    {
      "calendarId": "primary",
      "eventId": "73qusdveu121" 
    }
  ]
}

Parameters:

  • events (required): An array of objects containing:
    • calendarId: The ID of the calendar where the event exists.
    • eventId: The ID of the event to fetch.

Tip: Pass the recurringEventId (e.g., "73qusdveu121") found in the List endpoint response, not the instance ID (e.g., "73qusdveu121_2026..."), if you want to get the recurrence rules.

Success Response: 200 OK

Returns a flat array of the requested events.

[
  {
    "id": "73qusdveu121",
    "calendarId": "primary",
    "title": "Weekly Standup",
    "description": "Full agenda in the doc...",
    "start": "2026-01-19T12:00:00+01:00",
    "startTimezone": "Europe/Rome",
    "end": "2026-01-19T12:30:00+01:00",
    "endTimezone": "Europe/Rome",
    "recurrence": "RRULE:FREQ=WEEKLY;BYDAY=MO", 
    "organizer": {
      "email": "boss@example.com",
      "name": "The Boss"
    },
    "attendees": [
        { 
        "email": "me@example.com", 
        "status": "accepted" 
        }
    ]
  }
]