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

# Google Calendar

> Give your agents the Google Calendar API — events, recurring schedules, free/busy availability, and calendar sharing — through agntdata.

## Overview

The Google Calendar connection lets deployed agents manage schedules end to end: list **calendars** and create secondary ones; run the full **event** lifecycle (create, update, move, delete — with attendee notifications); expand **recurring events** into instances; create events from **natural language** with quick-add; answer "when is X free?" with **free/busy** queries; and manage **calendar sharing**.

* **Base URL**: `https://api.agntdata.dev/v1/connections/google-calendar`
* **Google auth**: OAuth 2.0 — connect Google Calendar from the dashboard. Connecting only requests calendar permissions; Google Docs and Google Sheets are separate connections with their own consents, even though they share one Google sign-in. agntdata attaches a fresh access token to every call and refreshes it in the background.
* **MCP tools**: agents call `connection_google_calendar_*` tools, e.g. `connection_google_calendar_list_events`, `connection_google_calendar_create_event`, `connection_google_calendar_query_free_busy`.

<Note>
  **Calendar ids** come from `list_calendars`; the account's main calendar is always addressable as `primary`. **Event times** are objects: `{"dateTime":"2026-07-10T15:00:00-07:00","timeZone":"America/Los_Angeles"}` for timed events or `{"date":"2026-07-10"}` for all-day. For date-range agendas, pass `singleEvents=true` with `orderBy=startTime` so recurring events expand into instances. Set `sendUpdates` (`all` / `externalOnly` / `none`) on event writes to control attendee emails. **Delete tools are irreversible.**
</Note>

## Setup

<Steps>
  <Step title="Connect Google">
    In the agntdata dashboard open **Integrations**, pick **Google Calendar**, and click **Connect**. You'll be redirected to Google to authorize calendar access — only calendar permissions are requested. If you've already connected Google Docs or Sheets, the same Google sign-in is reused and Google just asks you to add calendar access.
  </Step>

  <Step title="Pick Calendar tools">
    In an agent's Tools panel, add the Calendar tools the agent needs — for example `list_events`, `create_event`, `query_free_busy`, and `quick_add_event`. Destructive tools (`delete_event`, `delete_calendar`, `clear_calendar`, `unshare_calendar`) ship too and default to always-ask approval.
  </Step>
</Steps>

## Examples

### Today's agenda

```bash theme={null}
curl "https://api.agntdata.dev/v1/connections/google-calendar/calendars/primary/events?timeMin=2026-07-10T00:00:00Z&timeMax=2026-07-11T00:00:00Z&singleEvents=true&orderBy=startTime" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY"
```

### Create an event with attendees

```bash theme={null}
curl -X POST "https://api.agntdata.dev/v1/connections/google-calendar/calendars/primary/events?sendUpdates=all" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Roadmap review",
    "start": {"dateTime": "2026-07-14T10:00:00-07:00", "timeZone": "America/Los_Angeles"},
    "end":   {"dateTime": "2026-07-14T10:45:00-07:00", "timeZone": "America/Los_Angeles"},
    "attendees": [{"email": "sam@acme.com"}]
  }'
```

### When is the team free?

```bash theme={null}
curl -X POST "https://api.agntdata.dev/v1/connections/google-calendar/freeBusy" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timeMin": "2026-07-14T00:00:00Z",
    "timeMax": "2026-07-15T00:00:00Z",
    "items": [{"id": "primary"}, {"id": "sam@acme.com"}]
  }'
```

## Notable tools

| Tool                                      | What it does                                                   |
| ----------------------------------------- | -------------------------------------------------------------- |
| `list_calendars`                          | All calendars on the account (source of `calendarId`)          |
| `list_events` / `get_event`               | Read events; `q` searches, `timeMin`/`timeMax` bound the range |
| `create_event` / `update_event`           | Full event lifecycle with attendees, recurrence, reminders     |
| `quick_add_event`                         | "Lunch with Sam tomorrow at noon" → event                      |
| `move_event`                              | Move an event to another calendar                              |
| `list_event_instances`                    | Expand a recurring series into instances                       |
| `query_free_busy`                         | Busy intervals across calendars — the scheduling primitive     |
| `share_calendar` / `list_calendar_shares` | Manage who can see or edit a calendar                          |