agents/skills/calcom-api/references/calendars.md
Detailed documentation for calendar integration endpoints in the Cal.com API v2.
| Method | Endpoint | Description |
|---|---|---|
| GET | /v2/calendars | List connected calendars |
| GET | /v2/calendars/busy-times | Get busy times |
| GET | /v2/calendars/{calendar}/check | Check calendar connection |
| POST | /v2/calendars/{calendar}/connect | Connect a calendar |
| DELETE | /v2/calendars/{calendar}/disconnect | Disconnect a calendar |
| GET | /v2/calendars/{calendar}/credentials | Get calendar credentials |
| GET | /v2/destination-calendars | List destination calendars |
| GET | /v2/selected-calendars | List selected calendars |
GET /v2/calendars
{
"status": "success",
"data": {
"connectedCalendars": [
{
"integration": {
"type": "google_calendar",
"title": "Google Calendar",
"slug": "google-calendar"
},
"credentialId": 123,
"primary": {
"externalId": "primary",
"name": "[email protected]",
"email": "[email protected]",
"isSelected": true,
"readOnly": false
},
"calendars": [
{
"externalId": "primary",
"name": "[email protected]",
"email": "[email protected]",
"isSelected": true,
"readOnly": false
},
{
"externalId": "calendar-id-2",
"name": "Work Calendar",
"email": "[email protected]",
"isSelected": true,
"readOnly": false
}
]
}
],
"destinationCalendar": {
"id": 1,
"integration": "google_calendar",
"externalId": "primary",
"name": "[email protected]"
}
}
}
Check busy times from connected calendars to understand availability.
GET /v2/calendars/busy-times
| Parameter | Type | Required | Description |
|---|---|---|---|
| startTime | string | Yes | ISO 8601 start of date range |
| endTime | string | Yes | ISO 8601 end of date range |
| loggedInUsersTz | string | No | User's timezone |
| credentialId | number | No | Specific calendar credential ID |
GET /v2/calendars/busy-times?startTime=2024-01-15T00:00:00Z&endTime=2024-01-22T00:00:00Z&loggedInUsersTz=America/New_York
{
"status": "success",
"data": [
{
"start": "2024-01-15T10:00:00.000Z",
"end": "2024-01-15T11:00:00.000Z",
"title": "Team Meeting",
"source": "google_calendar"
},
{
"start": "2024-01-16T14:00:00.000Z",
"end": "2024-01-16T15:00:00.000Z",
"title": "Client Call",
"source": "google_calendar"
}
]
}
GET /v2/calendars/{calendar}/check
| Parameter | Type | Description |
|---|---|---|
| calendar | string | Calendar type (e.g., google-calendar, office365-calendar) |
POST /v2/calendars/{calendar}/connect
This initiates the OAuth flow for calendar connection.
DELETE /v2/calendars/{calendar}/disconnect
| Type | Slug | Description |
|---|---|---|
| Google Calendar | google-calendar | Google Workspace calendars |
| Microsoft 365 | office365-calendar | Outlook/Microsoft 365 calendars |
| Apple Calendar | apple-calendar | iCloud calendars (CalDAV) |
| CalDAV | caldav-calendar | Generic CalDAV calendars |
The destination calendar is where new bookings are created.
GET /v2/destination-calendars
{
"status": "success",
"data": [
{
"id": 1,
"integration": "google_calendar",
"externalId": "primary",
"name": "[email protected]",
"userId": 123,
"eventTypeId": null,
"credentialId": 456
}
]
}
Selected calendars are checked for conflicts when calculating availability.
GET /v2/selected-calendars
{
"status": "success",
"data": [
{
"integration": "google_calendar",
"externalId": "primary",
"credentialId": 123
},
{
"integration": "google_calendar",
"externalId": "work-calendar-id",
"credentialId": 123
}
]
}
GET /v2/calendars/ics-feed/check
POST /v2/calendars/ics-feed/save
{
"url": "https://calendar.example.com/feed.ics"
}
GET /v2/calendars/{calendar}/events/{eventUid}
{
"status": "success",
"data": {
"id": "event-id-123",
"title": "Meeting",
"description": "Discussion",
"start": {
"time": "2024-01-15T10:00:00.000Z",
"timeZone": "America/New_York"
},
"end": {
"time": "2024-01-15T11:00:00.000Z",
"timeZone": "America/New_York"
},
"attendees": [
{
"email": "[email protected]",
"name": "Attendee Name",
"responseStatus": "accepted"
}
],
"status": "accepted",
"source": "google"
}
}
1. User connects calendar (OAuth)
POST /v2/calendars/google-calendar/connect
2. User selects which calendars to check for conflicts
(Done via Cal.com dashboard)
3. User sets destination calendar for new bookings
(Done via Cal.com dashboard)
4. When checking slots:
- API fetches busy times from all selected calendars
- Busy times are excluded from available slots
5. When booking is created:
- Event is created in destination calendar
- Confirmation emails sent to attendees
Cal.com events in external calendars can be identified by their iCalUID ending with @Cal.com (e.g., [email protected]).
For team-level calendar management:
GET /v2/organizations/{orgId}/teams/{teamId}/conferencing
POST /v2/organizations/{orgId}/teams/{teamId}/conferencing/{app}/connect