canonical: https://jentic.com/apis/googleapis.com/google-calendar

# Google Calendar API

Create, modify, and query calendar events with attendee management, recurring event rules, and free/busy availability lookups across Google Calendar accounts. Access 37 endpoints covering event creation, calendar sharing, access control lists, real-time change notifications, and cross-calendar availability checks. Supports recurring events with RRULE syntax, timezone-aware scheduling, and video conferencing link generation.

## For AI agents

Create and manage calendar events, check attendee availability, and set up recurring schedules across Google Calendar accounts. Supports 37 operations covering events, ACLs, and real-time change watches.

## Scope

Does not handle email delivery, file storage, or video call infrastructure - use for calendar event scheduling and availability queries only.

## Capabilities

- Create calendar events with attendees, locations, video conferencing links, and reminders
- Query free/busy availability across multiple calendars for meeting scheduling
- Set up recurring events using RRULE syntax with exceptions and modifications
- Watch for calendar changes in real time via push notifications to webhook endpoints
- Share calendars with configurable access levels from free/busy-only to full owner control
- Import and export events in iCalendar format for cross-platform synchronization
- Retrieve event lists with time range, search query, and single-event expansion filters

## Use cases

### AI Agent Meeting Scheduling

AI agents use the Calendar API through Jentic to find available time slots, create meetings with attendees, and handle rescheduling requests. An agent searches Jentic for 'check calendar availability,' receives the freebusy.query schema, and executes the lookup across multiple calendars - no OAuth configuration needed. Handles timezone conversions, attendee conflict detection, and Google Meet link generation automatically.

Example prompt: Query free/busy availability for three attendees over next week using POST /freeBusy, find the first shared 1-hour slot, then create an event at that time with a Google Meet link

### Event Management and Recurring Schedules

Create and manage complex recurring event schedules using RRULE syntax with support for exceptions, modifications to individual instances, and timezone-aware start/end times. The events.insert endpoint accepts full RFC 5545 recurrence rules and generates individual event instances that can be independently modified or cancelled. Supports all-day events, multi-day spans, and events with attachments.

Example prompt: Create a recurring weekly team standup event every Monday at 9:00 AM for 30 minutes with 5 attendees using POST /calendars/{calendarId}/events with recurrence rule RRULE:FREQ=WEEKLY;BYDAY=MO

### Calendar Sharing and Access Control

Manage calendar visibility and access permissions programmatically through the ACL endpoints. Grant users specific access levels from freebusy-only to full owner control, share calendars with groups or domains, and audit current permissions. Supports delegation scenarios where assistants manage executive calendars with appropriate access boundaries.

Example prompt: Grant writer access to a secondary calendar for user assistant@company.com using POST /calendars/{calendarId}/acl with role='writer' and scope type='user'

### Real-Time Calendar Sync

Subscribe to push notifications for calendar changes using the events.watch endpoint, enabling real-time synchronization between Google Calendar and external systems. Receive notifications when events are created, modified, or deleted without polling. Combined with incremental sync tokens, this enables efficient one-way or bidirectional calendar synchronization with external scheduling tools.

Example prompt: Set up a watch on a calendar's events using POST /calendars/{calendarId}/events/watch with a webhook URL, then poll for changes since the last sync token using GET /calendars/{calendarId}/events with syncToken

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /calendars/{calendarId}/events | Create a new calendar event |
| GET | /calendars/{calendarId}/events | List events with time range and query filters |
| GET | /calendars/{calendarId}/events/{eventId} | Get a specific event by ID |
| PATCH | /calendars/{calendarId}/events/{eventId} | Update event details |
| DELETE | /calendars/{calendarId}/events/{eventId} | Delete an event |
| POST | /freeBusy | Query free/busy availability for calendars |
| POST | /calendars/{calendarId}/events/watch | Subscribe to event change notifications |
| POST | /calendars/{calendarId}/acl | Create an access control rule |

## Key resources

- **Events** — Create, read, update, delete, move, and watch calendar events with recurrence and attendees
- **Calendars** — Create, read, update, delete, and clear calendars
- **ACL** — Manage access control rules for calendar sharing permissions
- **FreeBusy** — Query availability across multiple calendars and groups
- **CalendarList** — Manage the list of calendars shown in a user's calendar UI
- **Settings** — Read and watch user calendar settings and preferences

## Why Jentic

- **Setup:** Wiring the Calendar API by hand means standing up its Google OAuth 2.0 flow across the calendar, calendar.events, and calendar.readonly scopes, refreshing scoped access tokens, and handling recurrence rules and freeBusy queries yourself. Through Jentic you install once, import the Calendar API from the API Directory, store the OAuth credentials once, and your agent calls it.
- **Permission scoping:** The API puts the calendar and event in the URL path (/calendars/{calendarId}/events/{eventId}), so a rule can pin your agent to one calendar: it can create events and read availability there and nowhere else. You choose the operations it may call, so deleting an event or editing the calendar ACL is not included unless you add it.
- **Credential handling:** Your Google Calendar OAuth credentials and refresh token are stored once, encrypted, by your own Jentic One instance and injected at execution time. The agent receives only short-lived scoped access tokens and never sees the raw OAuth credentials in its prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'schedule a meeting' or 'check calendar availability', and Jentic returns the matching Calendar operation with its input schema and recurrence rule format so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Calendly API** — Scheduling platform with booking pages, availability rules, and appointment types
- **Zoom Meetings API** — Video conferencing with meeting creation, recording, and participant management
- **Gmail API** — Email invitations and notifications for calendar events
- **Slack API** — Team messaging for calendar event reminders and scheduling notifications

## FAQ

### What authentication does the Google Calendar API use?

The Calendar API uses OAuth 2.0 with scopes including calendar.readonly for read-only access, calendar.events for event management, and calendar for full calendar control. Through Jentic, OAuth tokens are stored in your Jentic One instance. The API supports both implicit and authorization code OAuth flows.

### Can I check meeting availability across multiple people with the Calendar API?

Yes, the POST /freeBusy endpoint accepts a list of calendar IDs and a time range, returning busy intervals for each calendar. You can query up to 50 calendars in a single request with a time window up to 2 months. The response shows exactly which time slots are free across all participants.

### What are the rate limits for the Google Calendar API?

The Calendar API allows 1,000,000 queries per day per project and enforces per-user rate limits of approximately 10 queries per second. Event creation and modification have stricter per-calendar limits. Batch requests can combine multiple operations to reduce quota consumption.

### How do I create a recurring event with the Calendar API through Jentic?

Search Jentic for 'create recurring calendar event' to get the POST /calendars/{calendarId}/events schema. Set the recurrence field with an RRULE string like 'RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR' for specific days. Install Jentic with pip install jentic, authenticate through Jentic One, the self-hosted execution layer, and execute with the loaded schema.

### Is the Google Calendar API free to use?

Yes, the Calendar API is free with no per-call charges. You need a Google Cloud project with the Calendar API enabled. Usage is governed by daily quota limits (1,000,000 queries/day per project) and per-user rate limits rather than pricing tiers.

### Can I add a Google Meet link when creating an event?

Yes, include conferenceData in your event creation request with createRequest containing a requestId and conferenceSolutionKey of type 'hangoutsMeet'. Set conferenceDataVersion=1 as a query parameter on the POST /calendars/{calendarId}/events call. The response includes the generated Meet link in conferenceData.entryPoints.

### How do I sync calendar changes to an external system?

Use POST /calendars/{calendarId}/events/watch with a webhook URL to receive push notifications on event changes. For initial sync, call GET /calendars/{calendarId}/events and store the nextSyncToken. On subsequent calls, pass syncToken to receive only incremental changes since the last sync.

### Can I limit what my agent is allowed to do with the Google Calendar API?

Yes. Because Jentic One is self-hosted, your own rules decide which Calendar operations and credentials the agent may use. Since the Calendar API puts the calendar and event in the URL path (/calendars/{calendarId}/events/{eventId}), you can pin the agent to a single calendar so it only creates events and reads free/busy availability there and nowhere else. You choose the operations it may call, so deleting events or editing the calendar ACL stays off limits unless you explicitly add them.