calcom-api

# Cal.com API v2

This skill provides guidance for AI agents to interact with the Cal.com API v2, enabling scheduling automation, booking management, and calendar integrations.

## Base URL

All API requests should be made to:
```
https://api.cal.com/v2
```

## Authentication

All API requests require authentication via Bearer token in the Authorization header:

```
Authorization: Bearer cal_<your_api_key>
```

API keys must be prefixed with `cal_`. You can generate API keys from your Cal.com dashboard under Settings > Developer > API Keys.

## Core Concepts

### Event Types
Event types define bookable meeting configurations (duration, location, availability rules). Each event type has a unique slug used in booking URLs.

### Bookings
Bookings are confirmed appointments created when someone books an event type. Each booking has a unique UID for identification.

### Schedules
Schedules define when a user is available for bookings. Users can have multiple schedules with different working hours.

### Slots
Slots represent available time windows that can be booked based on event type configuration and user availability.

## Common Operations

### Check Available Slots

Before creating a booking, check available time slots:

```http
GET /v2/slots?startTime=2024-01-15T00:00:00Z&endTime=2024-01-22T00:00:00Z&eventTypeId=123&eventTypeSlug=30min
```

Query parameters:
- `startTime` (required): ISO 8601 start of range
- `endTime` (required): ISO 8601 end of range  
- `eventTypeId` or `eventTypeSlug`: Identify the event type
- `timeZone`: Timezone for slot display (default: UTC)

Response contains available slots grouped by date.

### Create a Booking

```http
POST /v2/bookings
Content-Type: application/json

{
  "start": "2024-01-15T10:00:00Z",
  "eventTypeId": 123,
  "attendee": {
    "name": "John Doe",
    "email": "john@example.com",
    "timeZone": "America/New_York"
  },
  "meetingUrl": "https://cal.com/team/meeting",
  "metadata": {}
}
```

Required fields:
- `start`: I