Calendar API
The Calendar API provides comprehensive Google Calendar integration for managing events, calendars, and preferences.
Authentication
Calendar endpoints require Google Calendar integration. Users must connect their Google account before using these endpoints.
Endpoints
List Calendars
Get all calendars for the authenticated user.
GET /api/v1/calendar/list
{
"calendars": [
{
"id": "primary",
"summary": "John Doe",
"description": "Primary calendar",
"timeZone": "America/New_York",
"colorId": "1",
"backgroundColor": "#9fe1e7",
"foregroundColor": "#000000",
"selected": true,
"accessRole": "owner",
"primary": true
}
]
}
Query Events
Query events from selected calendars (POST to avoid URL length limits).
POST /api/v1/calendar/events/query
Array of calendar IDs to query
Start date in YYYY-MM-DD format
End date in YYYY-MM-DD format
Maximum results per calendar (1-250)
Fetch all events in date range (recommended for calendar views)
{
"selected_calendars": ["primary", "[email protected]"],
"start_date": "2026-02-19",
"end_date": "2026-02-26",
"fetch_all": true
}
{
"events": [
{
"id": "event_123",
"summary": "Team Meeting",
"description": "Weekly sync",
"start": {
"dateTime": "2026-02-20T10:00:00-05:00",
"timeZone": "America/New_York"
},
"end": {
"dateTime": "2026-02-20T11:00:00-05:00",
"timeZone": "America/New_York"
},
"attendees": [
{
"email": "[email protected]",
"displayName": "Jane Smith",
"responseStatus": "accepted"
}
],
"calendarId": "primary",
"location": "Conference Room A",
"conferenceData": {
"entryPoints": [
{
"entryPointType": "video",
"uri": "https://meet.google.com/abc-defg-hij"
}
]
}
}
],
"has_more": false,
"calendars_truncated": []
}
Get Events (Simple GET)
Get calendar events using GET (for simple queries).
GET /api/v1/calendar/events
Calendar IDs (comma-separated)
Fetch all events in range
Create Event
Create a new calendar event.
POST /api/v1/calendar/event
{
"calendar_id": "primary",
"summary": "Product Launch",
"description": "Launch new feature",
"start": {
"dateTime": "2026-02-25T14:00:00",
"timeZone": "America/New_York"
},
"end": {
"dateTime": "2026-02-25T15:00:00",
"timeZone": "America/New_York"
},
"attendees": [
{"email": "[email protected]"}
],
"location": "Office",
"conferenceDataVersion": 1
}
Update Event
Update an existing event.
PUT /api/v1/calendar/event
{
"event_id": "event_123",
"calendar_id": "primary",
"summary": "Updated Title",
"start": {
"dateTime": "2026-02-25T15:00:00",
"timeZone": "America/New_York"
},
"end": {
"dateTime": "2026-02-25T16:00:00",
"timeZone": "America/New_York"
}
}
Delete Event
Delete a calendar event.
DELETE /api/v1/calendar/event
{
"event_id": "event_123",
"calendar_id": "primary"
}
Batch Operations
Batch Create Events
Create multiple events in one request.
POST /api/v1/calendar/events/batch
{
"events": [
{
"calendar_id": "primary",
"summary": "Event 1",
"start": {...},
"end": {...}
},
{
"calendar_id": "primary",
"summary": "Event 2",
"start": {...},
"end": {...}
}
]
}
{
"successful": [
{"id": "event_123", "summary": "Event 1"}
],
"failed": [
{
"event": "Event 2",
"error": "Invalid time zone"
}
]
}
Batch Update Events
Update multiple events.
PUT /api/v1/calendar/events/batch
Batch Delete Events
Delete multiple events.
DELETE /api/v1/calendar/events/batch
Calendar Preferences
Get Preferences
Get user’s selected calendars.
GET /api/v1/calendar/preferences
Update Preferences
Update selected calendars.
PUT /api/v1/calendar/preferences
Next Steps
Email API
Manage Gmail messages
Integrations
Connect services