Calendar API

The Calendar Access API provides read and write access to calendar data through authenticated access tokens.

Base URL

/api/access/calendar

Authentication

Authorization: Bearer <api_key>

Rate Limits

100 requests/minute500 requests/hour

Access Info

Read endpoints (GET requests) include an optional accessInfo field that describes any active access restrictions on the token. This field is omitted when there are no restrictions. AI agents should use this field to understand data limitations.

Write endpoints (POST/PATCH/DELETE) do not include accessInfo — any access violations are returned as errors.

Example accessInfo values:

"Results limited to time window: Last 30 days to next 30 days."
"Read-only access, cannot create or modify events."
"Some contacts or domains are blocked from results."

Tip

Event endpoints also include a currentUserCalendarEmail field that identifies the calendar owner's email. Use this to determine which attendee/organizer represents the current user.

Endpoints Overview

Method	Endpoint	Description
GET	/calendars	List all calendars
GET	/events	List/search events with filters
GET	/events/{eventId}	Get a single event
POST	/events	Create a new event
PATCH	/events/{eventId}	Update an existing event
DELETE	/events/{eventId}	Delete an event
POST	/events/{eventId}/respond	Respond to event invitation
GET	/freebusy	Get free/busy information
GET	/events/by-contact	Get events by contact

GET/api/access/calendar/calendarsBearer Token

List Calendars

Returns all calendars configured for the current operator.

Response 200 OK

{ 
  "data": [ 
    { 
      "id": 123, 
      "externalId": "calendar@example.com", 
      "name": "Team Calendar", 
      "provider": "GOOGLE", 
      "timezone": "America/Chicago", 
      "isPrimary": true, 
      "isOperatorOwner": true, 
      "ownerEmail": "user@example.com", 
      "lastSyncedAt": "2026-02-05T10:30:00Z" 
    } 
  ], 
  "accessInfo": "Results limited to time window: Last 30 days to next 30 days." 
}

Calendar Object Fields

Field	Type	Description
id	long	Internal calendar ID (use this for filtering events)
externalId	string	External calendar identifier (e.g., email for Google Calendar)
name	string	Calendar display name
provider	string	Calendar provider (GOOGLE, M365)
timezone	string?	Calendar timezone (IANA format)
isPrimary	bool	Whether this is the primary calendar
isOperatorOwner	bool	Whether the current operator owns this calendar
ownerEmail	string?	Calendar owner's email address
lastSyncedAt	DateTime?	Last successful sync timestamp (UTC)