Files
cal.diy/agents/skills/calcom-api/references/calendars.md
T
12abc316e6 refactor: consolidate agent config into agents directory (#27427)
* refactor: consolidate agent config folders into agents directory

- Move .claude/skills and .claude/rules content to agents/
- Remove duplicate .cursor/ and .goose/ folders
- Create symlinks from .claude/ and .cursor/ to agents/
- Convert review.mdc to quality-review-checklist.md with proper frontmatter

Co-Authored-By: Claude Haiku 4.5 <[email protected]>

* feat: add Cal.com APIv2 skills to agents directory

Move the Cal.com API v2 skills from PR #27445 into the consolidated
agents/skills/ directory structure. This includes:
- SKILL.md - Main skill file with API overview
- references/authentication.md - Authentication methods
- references/bookings.md - Bookings API reference
- references/calendars.md - Calendars API reference
- references/event-types.md - Event types API reference
- references/schedules.md - Schedules API reference
- references/slots-availability.md - Slots and availability API reference
- references/webhooks.md - Webhooks API reference

Co-Authored-By: [email protected] <[email protected]>

* fix: update calcom-api skill to use Claude Code frontmatter format

Remove non-standard frontmatter fields (license, metadata) and keep only
the Claude Code supported fields (name, description) as per the
Claude Code skills specification.

Co-Authored-By: [email protected] <[email protected]>

* refactor: restructure calcom-api SKILL.md as index file

Convert SKILL.md from a comprehensive API doc (317 lines) to a concise
index file (108 lines) that references the detailed documentation in
the references/ folder. This follows the Claude Code skills pattern of
keeping SKILL.md focused with supporting files for detailed content.

The SKILL.md now:
- Provides a quick start guide with essential examples
- References all 7 detailed reference docs in a table
- Lists common workflows and best practices
- Points to external resources

Co-Authored-By: [email protected] <[email protected]>

* docs: preserve deleted content in reference files

Move content that was removed from SKILL.md to appropriate reference files:
- Add Error Handling and Pagination sections to authentication.md
- Add Organization endpoints to event-types.md
- Add Core Concepts section back to SKILL.md

This ensures no useful API documentation is lost during the restructuring.

Co-Authored-By: [email protected] <[email protected]>

---------

Co-authored-by: Claude Haiku 4.5 <[email protected]>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
2026-02-03 14:14:41 +01:00

328 lines
7.0 KiB
Markdown

# Calendars API Reference
Detailed documentation for calendar integration endpoints in the Cal.com API v2.
## Endpoints Overview
| 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 |
## List Connected Calendars
```http
GET /v2/calendars
```
### Response
```json
{
"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]"
}
}
}
```
## Get Busy Times
Check busy times from connected calendars to understand availability.
```http
GET /v2/calendars/busy-times
```
### Query Parameters
| 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 |
### Example Request
```http
GET /v2/calendars/busy-times?startTime=2024-01-15T00:00:00Z&endTime=2024-01-22T00:00:00Z&loggedInUsersTz=America/New_York
```
### Response
```json
{
"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"
}
]
}
```
## Calendar Connection
### Check Calendar Connection
```http
GET /v2/calendars/{calendar}/check
```
### Path Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| calendar | string | Calendar type (e.g., `google-calendar`, `office365-calendar`) |
### Connect a Calendar
```http
POST /v2/calendars/{calendar}/connect
```
This initiates the OAuth flow for calendar connection.
### Disconnect a Calendar
```http
DELETE /v2/calendars/{calendar}/disconnect
```
## Supported Calendar Types
| 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 |
## Destination Calendars
The destination calendar is where new bookings are created.
### List Destination Calendars
```http
GET /v2/destination-calendars
```
### Response
```json
{
"status": "success",
"data": [
{
"id": 1,
"integration": "google_calendar",
"externalId": "primary",
"name": "[email protected]",
"userId": 123,
"eventTypeId": null,
"credentialId": 456
}
]
}
```
## Selected Calendars
Selected calendars are checked for conflicts when calculating availability.
### List Selected Calendars
```http
GET /v2/selected-calendars
```
### Response
```json
{
"status": "success",
"data": [
{
"integration": "google_calendar",
"externalId": "primary",
"credentialId": 123
},
{
"integration": "google_calendar",
"externalId": "work-calendar-id",
"credentialId": 123
}
]
}
```
## ICS Feed
### Check ICS Feed
```http
GET /v2/calendars/ics-feed/check
```
### Save ICS Feed
```http
POST /v2/calendars/ics-feed/save
```
```json
{
"url": "https://calendar.example.com/feed.ics"
}
```
## Calendar Events
### Get Calendar Event
```http
GET /v2/calendars/{calendar}/events/{eventUid}
```
### Response
```json
{
"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"
}
}
```
## Understanding Calendar Integration
### How Calendars Affect Availability
1. **Selected Calendars**: Events from selected calendars block availability
2. **Destination Calendar**: New bookings are created in this calendar
3. **Busy Times**: The API aggregates busy times from all selected calendars
### Calendar Sync Flow
```
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 Event Identification
Cal.com events in external calendars can be identified by their iCalUID ending with `@Cal.com` (e.g., `[email protected]`).
## Team Calendar Integration
For team-level calendar management:
### Team Conferencing
```http
GET /v2/organizations/{orgId}/teams/{teamId}/conferencing
```
### Connect Team Calendar
```http
POST /v2/organizations/{orgId}/teams/{teamId}/conferencing/{app}/connect
```
## Best Practices
1. **Check connection status**: Verify calendar is connected before operations
2. **Handle OAuth expiry**: Calendar tokens may expire, handle re-authentication
3. **Respect rate limits**: Calendar APIs have their own rate limits
4. **Cache busy times**: Busy times don't change frequently, cache appropriately
5. **Use webhooks**: Subscribe to booking events instead of polling calendars