Google

Google Calendar API

List calendars and events, create meetings with guests, reminders and Google Meet links, recurring events, free/busy and push.

Productivity & workspaceGuided#calendar#scheduling#google-workspace#google-meet#oauth2

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

The Google Calendar API reads and manages a user's Google Calendar: their calendars, events with guests and reminders, recurring series, free/busy availability, and Google Meet links on events. Apps use it for booking and scheduling, syncing appointments into their own system, or showing a user's agenda. This guided collection covers the calls most apps need first; the generated Calendar listing on the Google page lists every endpoint (ACLs, calendar creation, imports and more).

Get credentials, step by step

  1. Create or pick a project in the Google Cloud console.
  2. Enable the Google Calendar API.
  3. Configure the OAuth consent screen in Google Auth Platform: External, publishing status Testing, and add your own Google account as a test user.
  4. Create an OAuth client under Clients (Desktop app or Web application) and copy the ID and secret into the collection variables.
  5. Get a token with the OAuth 2.0 Playground (quickest) or with the sign-in URL and code exchange in folder 1.

Authentication and scopes

Every call sends Authorization: Bearer <access token>; tokens last about an hour and the refresh token renews them. The calendar scope covers this whole collection; calendar.events is enough for creating and changing events, and calendar.readonly for reading. Calendar data scopes are sensitive: a public app needs Google's OAuth verification, while in Testing mode your test users can use them right away (refresh tokens then expire after 7 days). Prefer the narrowest scope; see Choose Google Calendar API scopes.

Base URL

https://www.googleapis.com/calendar/v3 ({{baseUrl}}). Calendar IDs go in the path; primary is the signed-in user's main calendar. Times are RFC 3339 with an offset; time zones are IANA names (Europe/London).

How to use this collection

Fill the OAuth variables, get a token, set attendeeEmail, then run the folders in order. IDs flow between requests through test scripts; the time window and random request IDs are filled by pre-request scripts. Creating events with sendUpdates=all really emails the guests, so invite yourself while testing.

Limits

Usage is metered per project and per user per minute, and the API has a daily per-project threshold; exceeding a limit returns 403 or 429 with reason usageLimits / rateLimitExceeded. Retry with exponential backoff and jitter, and prefer push notifications to polling. Current numbers: Manage quotas.

Common errors

StatusTypical reasonWhat to do
401Invalid Credentials / UNAUTHENTICATED: token missing, expired (about an hour) or revokedRun Refresh the access token; if that returns invalid_grant, sign in again
403insufficientPermissions / ACCESS_TOKEN_SCOPE_INSUFFICIENT: the token lacks the scope this request needsSign in again with the scope listed on the request; check with tokeninfo
403accessNotConfigured / SERVICE_DISABLED: the API is not enabled in this Cloud projectEnable it in the API Library, wait a few minutes
403 / 429rateLimitExceeded, userRateLimitExceeded, RESOURCE_EXHAUSTED: per-user or per-project quotaBack off exponentially and retry; spread work over time
404notFound: wrong ID, or the item belongs to another user / was deletedRe-run the list request that stores the ID
400invalid / badRequest / INVALID_ARGUMENT: malformed body or parameterRead error.message; it names the field
409duplicate: an event with that id already existsLet Google generate IDs, or pick a new one
410fullSyncRequired / deleted: sync token expired or event already deletedRun a full sync without syncToken

Links

Endpoints 22

1. Get an access token

  • POSTExchange the authorization code for tokenshttps://oauth2.googleapis.com/tokenSwaps the one-time code from the browser redirect for an access token (about an hour) and a refresh token (long-lived; 7 days while the app is in Testing).…
  • POSTRefresh the access tokenhttps://oauth2.googleapis.com/tokenGets a fresh access token from the stored refresh token, without the user signing in again. When: whenever a call returns 401 (access tokens last about an…
  • GETCheck which scopes the token has (tokeninfo)https://oauth2.googleapis.com/tokeninfoAsks Google what the current access token is good for: the granted scope list, the client it belongs to (aud/azp) and the seconds left (expires_in). When: a…

2. Calendars and settings

  • GETList the user's calendars (calendarList)/users/me/calendarListLists the calendars in the user's calendar list: their primary calendar, secondary calendars they created, and calendars of others they subscribed to. When:…
  • GETGet the primary calendar/calendars/primaryReturns the calendar resource itself: title, description, time zone and conferencing it allows. When: to learn the time zone to use when you create events, or…
  • GETGet the color palette/colorsReturns the fixed palettes for calendars and events: a map from colorId to background and foreground hex colors. When: you show or let users choose colors.…
  • GETList the user's settings/users/me/settingsLists the user's Calendar settings as id/value pairs. When: to respect the user's preferences in your UI: timezone, locale, weekStart (0 = Sunday),…
  • GETGet one setting (time zone)/users/me/settings/timezoneReads a single setting by its ID; here timezone, the user's Calendar time zone. When: you only need one value, for example the time zone to show times in.…

3. Read events

  • GETList upcoming events/calendars/primary/eventsLists events of a calendar in a time window. When: agenda views, "what's next", sync. Scope: calendar.events.readonly, calendar.readonly, calendar.events or…
  • GETGet an event/calendars/primary/events/{{eventId}}Fetches one event by ID. When: after List upcoming events or any create request (uses {{eventId}}), for example to check attendee responses. Scope:…

4. Create and change events

  • POSTCreate an event with guests and reminders/calendars/primary/eventsCreates an event on the primary calendar, invites a guest, and sets its own reminders. When: booking a meeting or appointment for the user. Scope:…
  • POSTCreate an event with a Google Meet link/calendars/primary/eventsCreates an event and asks Calendar to attach a new Google Meet conference to it. This is the usual way to get a Meet link for a scheduled meeting (the Meet…
  • POSTQuick add from text/calendars/primary/events/quickAddCreates an event from one line of natural-language text, the way the Google Calendar quick-add box does ("Lunch with John at Example Store tomorrow 1pm").…
  • PATCHUpdate part of an event (patch)/calendars/primary/events/{{eventId}}Changes only the fields you send; everything else stays as it is. When: renaming, rescheduling or adding a guest to an existing event (uses {{eventId}}).…
  • POSTMove an event to another calendar/calendars/primary/events/{{eventId}}/moveMoves an event from one calendar to another, which changes its organizer calendar. When: filing an event under a team or project calendar. Set…
  • DELETEDelete an event/calendars/primary/events/{{eventId}}Deletes (cancels) an event. If the user organizes it, guests get a cancellation when sendUpdates=all. When: cleanup, or the user cancels a meeting. This…

5. Recurring events

  • POSTCreate a recurring event/calendars/primary/eventsCreates a weekly event that repeats ten times. When: standing meetings, classes, shifts. Scope: calendar.events or calendar. What comes back: the parent event…
  • GETList instances of a recurring event/calendars/primary/events/{{recurringEventId}}/instancesLists the single occurrences of a recurring event. When: showing the dates of a series, or finding the instance ID of one occurrence to change or cancel.…
  • PATCHChange one occurrence/calendars/primary/events/{{instanceId}}Changes a single occurrence of a series, leaving the others alone: here it moves one stand-up to 10:00. When: "just this event" edits. To cancel one…

6. Availability and push notifications

  • POSTQuery free/busy/freeBusyReturns busy time ranges for one or more calendars in a window, without event details. When: finding a slot before you create an event, or showing…
  • POSTWatch for event changes/calendars/primary/events/watchOpens a notification channel: Google will POST to webhookUrl whenever events on the primary calendar change. When: keeping your copy in sync without polling.…
  • POSTStop a notification channel/channels/stopStops a channel created by Watch for event changes, so Google stops sending notifications to your endpoint. When: the user disconnects, or before replacing a…

API details

Base URL
https://www.googleapis.com/calendar/v3
https://oauth2.googleapis.com
Authentication
A bearer token in the Authorization header
OAuth 2.0 (authorization code flow)
Operations
22 operations on 22 pathsPOST 10GET 9PATCH 2DELETE 1
Main resources
1. Get an access token 32. Calendars and settings 53. Read events 24. Create and change events 65. Recurring events 36. Availability and push notifications 3
Description format
Swastik Codes guided collection, API version checked against the docs on 2026-11-17

How to test the Google Calendar API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Google Calendar API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Exchange the authorization code for tokens” (POST https://oauth2.googleapis.com/token), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Google Calendar API?

List calendars and events, create meetings with guests, reminders and Google Meet links, recurring events, free/busy and push. It is listed under Productivity & workspace and has 22 endpoints.

Who publishes the Google Calendar API?

It is listed from Google's public API description (an OpenAPI document), not published by Google on Swastik Codes. Anyone who controls googleapis.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Google Calendar API?

Its description lists 2 base URLs: https://www.googleapis.com/calendar/v3, https://oauth2.googleapis.com. The first is the usual one; the others are typically sandbox or regional servers.

How do I authenticate with the Google Calendar API?

It accepts 2 methods: A bearer token in the Authorization header; OAuth 2.0 (authorization code flow).

How many endpoints does the Google Calendar API have?

22 operations on 22 paths (10 POST, 9 GET, 2 PATCH, 1 DELETE). The largest groups are 1. Get an access token, 2. Calendars and settings, 3. Read events, 4. Create and change events.

Is forking the Google Calendar API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.