> ## Documentation Index
> Fetch the complete documentation index at: https://lava.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Calendar

> Google Calendar REST API access for reading and managing events on a connected user's calendars.

Google Calendar REST API access for reading and managing events on a connected user's calendars. Use when an agent needs to check availability, list upcoming events, or create, update, and delete events — including attendee invitations and recurring events. Routes through Pipedream Connect — the user sees one Google consent screen on connect that says "Pipedream wants access" (Pipedream owns the verified OAuth client). Connects separately from Gmail: Pipedream has no combined Google app, so each Google product is its own connection.

10 example endpoints available through Lava's AI Gateway. See the [Google Calendar API docs](https://developers.google.com/workspace/calendar/api/v3/reference) for full documentation.

<Warning>This provider requires your own credentials — connect your API key or OAuth account before use.</Warning>

<Info>This is a **catch-all provider** — any valid URL under `https://www.googleapis.com` is supported. Google Calendar REST API endpoints. Construct URLs as [https://www.googleapis.com/calendar/v3/\&#123;path\&#125](https://www.googleapis.com/calendar/v3/\&#123;path\&#125); — common roots: calendars/primary/events, calendars/\{calendarId}/events/\{eventId}, users/me/calendarList, users/me/settings/timezone, freeBusy. Authentication is brokered through Pipedream Connect — the end-user sees a single "Pipedream wants to access your Google Account" consent screen on connect. Rules that prevent 400s and silent failures: timed events need start/end dateTime as RFC3339 WITH a UTC offset (e.g. 2026-06-11T09:00:00-04:00) or a timeZone field alongside; recurring events REQUIRE timeZone, and recurrence is an array of RFC5545 RRULE/RDATE/EXDATE lines with NO DTSTART or DTEND; timeMin/timeMax query params also need RFC3339 with offset. Prefer PATCH over PUT to update events — PUT replaces the whole resource and WIPES any field you omit. Listing in chronological order needs orderBy=startTime with singleEvents=true (Lava auto-adds singleEvents when you forget). Creating a Meet link via conferenceData.createRequest needs conferenceDataVersion=1 in the query (Lava auto-adds it). Attendee email notifications are controlled by the sendUpdates query param (all, externalOnly, none — default none, so invitations are NOT emailed unless you ask). The Lava gateway requires a JSON body on every non-GET call — for endpoints that take no body (quickAdd, delete), send an empty object as body\_json. See [https://developers.google.com/workspace/calendar/api/v3/reference](https://developers.google.com/workspace/calendar/api/v3/reference) for the full reference. The endpoints below are curated examples.</Info>

## Endpoints

### Get the connected user's default time zone. Use this as a cheap auth probe after connect, and to schedule events in the user's local time without guessing.

**GET** `https://www.googleapis.com/calendar/v3/users/me/settings/timezone` — Free

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://www.googleapis.com/calendar/v3/users/me/settings/timezone', { method: 'GET' });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fwww.googleapis.com%2Fcalendar%2Fv3%2Fusers%2Fme%2Fsettings%2Ftimezone" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY"
    ```
  </Tab>
</Tabs>

### List the calendars on the user's calendar list with their IDs and access roles. Use calendar IDs from here in place of 'primary' to read or write other calendars.

**GET** `https://www.googleapis.com/calendar/v3/users/me/calendarList` — Free

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://www.googleapis.com/calendar/v3/users/me/calendarList', { method: 'GET' });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fwww.googleapis.com%2Fcalendar%2Fv3%2Fusers%2Fme%2FcalendarList" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY"
    ```
  </Tab>
</Tabs>

### List events on a calendar. For upcoming events in chronological order, pass timeMin (RFC3339 with offset), singleEvents=true, and orderBy=startTime. Responses are projected to scheduling essentials — pass filter \{"mode": "full"} for raw event resources.

**GET** `https://www.googleapis.com/calendar/v3/calendars/primary/events?timeMin=2026-06-11T00:00:00Z&singleEvents=true&orderBy=startTime&maxResults=25` — Free

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://www.googleapis.com/calendar/v3/calendars/primary/events?timeMin=2026-06-11T00:00:00Z&singleEvents=true&orderBy=startTime&maxResults=25', { method: 'GET' });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fwww.googleapis.com%2Fcalendar%2Fv3%2Fcalendars%2Fprimary%2Fevents%3FtimeMin%3D2026-06-11T00%3A00%3A00Z%26singleEvents%3Dtrue%26orderBy%3DstartTime%26maxResults%3D25" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY"
    ```
  </Tab>
</Tabs>

### Get a single event by ID, including full attendee and conference detail.

**GET** `https://www.googleapis.com/calendar/v3/calendars/primary/events/{eventId}` — Free

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://www.googleapis.com/calendar/v3/calendars/primary/events/{eventId}', { method: 'GET' });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.lava.so/v1/forward?u=https%3A%2F%2Fwww.googleapis.com%2Fcalendar%2Fv3%2Fcalendars%2Fprimary%2Fevents%2F%7BeventId%7D" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY"
    ```
  </Tab>
</Tabs>

### Create an event. Timed events need start/end dateTime in RFC3339 with an offset or a timeZone field; recurring events require timeZone and RFC5545 recurrence lines. Add sendUpdates=all to email invitations to attendees (default sends none).

**POST** `https://www.googleapis.com/calendar/v3/calendars/primary/events?sendUpdates=all` — Free

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://www.googleapis.com/calendar/v3/calendars/primary/events?sendUpdates=all', {
      body: {
    "summary": "Team standup",
    "start": {
      "dateTime": "2026-06-15T09:00:00",
      "timeZone": "America/New_York"
    },
    "end": {
      "dateTime": "2026-06-15T09:30:00",
      "timeZone": "America/New_York"
    },
    "attendees": [
      {
        "email": "teammate@example.com"
      }
    ]
    },
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fwww.googleapis.com%2Fcalendar%2Fv3%2Fcalendars%2Fprimary%2Fevents%3FsendUpdates%3Dall" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{"summary":"Team standup","start":{"dateTime":"2026-06-15T09:00:00","timeZone":"America/New_York"},"end":{"dateTime":"2026-06-15T09:30:00","timeZone":"America/New_York"},"attendees":[{"email":"teammate@example.com"}]}'
    ```
  </Tab>
</Tabs>

### Create an event from a natural-language sentence in the text query param (URL-encoded), e.g. "Lunch with Sam tomorrow at noon". Google parses the time and title. Takes no body fields — send an empty JSON object as the body.

**POST** `https://www.googleapis.com/calendar/v3/calendars/primary/events/quickAdd?text=Lunch%20with%20Sam%20tomorrow%20at%20noon` — Free

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://www.googleapis.com/calendar/v3/calendars/primary/events/quickAdd?text=Lunch%20with%20Sam%20tomorrow%20at%20noon', { body: {} });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fwww.googleapis.com%2Fcalendar%2Fv3%2Fcalendars%2Fprimary%2Fevents%2FquickAdd%3Ftext%3DLunch%2520with%2520Sam%2520tomorrow%2520at%2520noon" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```
  </Tab>
</Tabs>

### Query busy intervals across one or more calendars for a time window — the availability check before proposing a meeting time. timeMin/timeMax are RFC3339 with offset; items lists calendar IDs.

**POST** `https://www.googleapis.com/calendar/v3/freeBusy` — Free

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://www.googleapis.com/calendar/v3/freeBusy', {
      body: {
    "timeMin": "2026-06-15T00:00:00Z",
    "timeMax": "2026-06-16T00:00:00Z",
    "items": [
      {
        "id": "primary"
      }
    ]
    },
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api.lava.so/v1/forward?u=https%3A%2F%2Fwww.googleapis.com%2Fcalendar%2Fv3%2FfreeBusy" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{"timeMin":"2026-06-15T00:00:00Z","timeMax":"2026-06-16T00:00:00Z","items":[{"id":"primary"}]}'
    ```
  </Tab>
</Tabs>

### Partially update an event — only the fields in the body change. This is the recommended way to update; use PUT only when replacing the whole event.

**PATCH** `https://www.googleapis.com/calendar/v3/calendars/primary/events/{eventId}` — Free

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://www.googleapis.com/calendar/v3/calendars/primary/events/{eventId}', { method: 'PATCH', body: {"summary":"Renamed event"} });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X PATCH "https://api.lava.so/v1/forward?u=https%3A%2F%2Fwww.googleapis.com%2Fcalendar%2Fv3%2Fcalendars%2Fprimary%2Fevents%2F%7BeventId%7D" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{"summary":"Renamed event"}'
    ```
  </Tab>
</Tabs>

### Replace an event entirely. PUT has no patch semantics — any field omitted from the body is wiped, and start/end are required. GET the event first, modify, then PUT it back; prefer PATCH for partial changes.

**PUT** `https://www.googleapis.com/calendar/v3/calendars/primary/events/{eventId}` — Free

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://www.googleapis.com/calendar/v3/calendars/primary/events/{eventId}', {
      method: 'PUT',
      body: {
    "summary": "Updated meeting",
    "start": {
      "dateTime": "2026-06-15T10:00:00",
      "timeZone": "America/New_York"
    },
    "end": {
      "dateTime": "2026-06-15T11:00:00",
      "timeZone": "America/New_York"
    }
    },
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X PUT "https://api.lava.so/v1/forward?u=https%3A%2F%2Fwww.googleapis.com%2Fcalendar%2Fv3%2Fcalendars%2Fprimary%2Fevents%2F%7BeventId%7D" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{"summary":"Updated meeting","start":{"dateTime":"2026-06-15T10:00:00","timeZone":"America/New_York"},"end":{"dateTime":"2026-06-15T11:00:00","timeZone":"America/New_York"}}'
    ```
  </Tab>
</Tabs>

### Delete an event. Returns an empty 204 response on success. Add sendUpdates=all to email cancellations to attendees. Takes no body fields — send an empty JSON object as the body.

**DELETE** `https://www.googleapis.com/calendar/v3/calendars/primary/events/{eventId}?sendUpdates=all` — Free

<Tabs>
  <Tab title="SDK">
    ```typescript theme={null}
    const data = await lava.gateway('https://www.googleapis.com/calendar/v3/calendars/primary/events/{eventId}?sendUpdates=all', { method: 'DELETE', body: {} });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X DELETE "https://api.lava.so/v1/forward?u=https%3A%2F%2Fwww.googleapis.com%2Fcalendar%2Fv3%2Fcalendars%2Fprimary%2Fevents%2F%7BeventId%7D%3FsendUpdates%3Dall" \
      -H "Authorization: Bearer $LAVA_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="All Providers" icon="grid" href="/gateway/supported-providers">
    Browse all supported AI providers
  </Card>

  <Card title="Forward Proxy" icon="route" href="/gateway/forward-proxy">
    Learn how to construct proxy URLs and authenticate requests
  </Card>
</CardGroup>