Skip to main content

​
Overview

The Google Calendar API lets you manage calendars, create and modify events, and query for free/busy information. API Name: calendar
Version: v3
Official Documentation: Calendar API Reference

​
Common Resources

​
Events

Create, update, and manage calendar events.
​
calendarId
string
required
Calendar identifier or primary for the user’s primary calendar
​
eventId
string
The event ID
​
timeMin
string
Start time for event query (RFC3339 timestamp)
​
timeMax
string
End time for event query (RFC3339 timestamp)
​
maxResults
integer
Maximum number of events to return (default: 250, max: 2500)

​
Calendars

Manage calendar metadata.
​
calendarId
string
required
Calendar identifier
​
summary
string
The calendar title

​
Common Methods

​
List Events

gws calendar events list --params '{
  "calendarId": "primary",
  "timeMin": "2026-03-05T00:00:00Z",
  "maxResults": 10
}'
​
items
array
Array of event objects
​
id
string
The event ID
​
summary
string
The event title
​
start
object
The start time
​
dateTime
string
Start time (RFC3339)
​
end
object
The end time

​
Create Event

gws calendar events insert \
  --params '{"calendarId": "primary"}' \
  --json '{
    "summary": "Team Meeting",
    "start": {"dateTime": "2026-03-10T14:00:00-08:00"},
    "end": {"dateTime": "2026-03-10T15:00:00-08:00"},
    "attendees": [
      {"email": "colleague@example.com"}
    ]
  }'

​
Get Event

gws calendar events get --params '{
  "calendarId": "primary",
  "eventId": "abc123def456"
}'

​
Update Event

gws calendar events patch \
  --params '{"calendarId": "primary", "eventId": "abc123def456"}' \
  --json '{"summary": "Updated Meeting Title"}'

​
Delete Event

gws calendar events delete --params '{
  "calendarId": "primary",
  "eventId": "abc123def456"
}'

​
Quick Add Event

gws calendar events quickAdd --params '{
  "calendarId": "primary",
  "text": "Lunch with Sarah tomorrow at noon"
}'

​
Query Free/Busy

gws calendar freebusy query --json '{
  "timeMin": "2026-03-10T00:00:00Z",
  "timeMax": "2026-03-10T23:59:59Z",
  "items": [{"id": "primary"}]
}'

​
Event Examples

gws calendar events insert \
  --params '{"calendarId": "primary"}' \
  --json '{
    "summary": "Vacation Day",
    "start": {"date": "2026-03-15"},
    "end": {"date": "2026-03-16"}
  }'

​
Response Format

{
  "kind": "calendar#events",
  "items": [
    {
      "id": "abc123def456",
      "summary": "Team Meeting",
      "start": {
        "dateTime": "2026-03-10T14:00:00-08:00",
        "timeZone": "America/Los_Angeles"
      },
      "end": {
        "dateTime": "2026-03-10T15:00:00-08:00",
        "timeZone": "America/Los_Angeles"
      },
      "attendees": [
        {"email": "colleague@example.com", "responseStatus": "needsAction"}
      ]
    }
  ]
}
  • +insert - Create a new event
  • +agenda - Show upcoming events across all calendars

​
Key Resources

  • events - Create, read, update, delete events
  • calendars - Manage calendar metadata
  • calendarList - Manage user’s calendar list
  • acl - Manage calendar access control
  • freebusy - Query free/busy information

​
Learn More

​
Schema Inspection

Before calling any method, inspect its schema: 
gws schema calendar.events.list
gws schema calendar.events.insert