calcom-api

1---2name: calcom-api3description: Interact with the Cal.diy API v2 to manage scheduling, bookings, event types, availability, and calendars. Use this skill when building integrations that need to create or manage bookings, check availability, configure event types, or sync calendars with Cal.diy's scheduling infrastructure.4env:5  CAL_API_KEY:6    description: "Cal.diy API key (prefixed with cal_live_ or cal_test_). Required for all API requests."7    required: true8  CAL_CLIENT_ID:9    description: "OAuth client ID for platform integrations managing users on behalf of others. Sent as x-cal-client-id header."10    required: false11  CAL_SECRET_KEY:12    description: "OAuth client secret for platform integrations. Sent as x-cal-secret-key header."13    required: false14  CAL_WEBHOOK_SECRET:15    description: "Secret used to verify webhook payload signatures via X-Cal-Signature-256 header."16    required: false17---18 19# Cal.diy API v220 21This skill provides guidance for AI agents to interact with the Cal.diy API v2, enabling scheduling automation, booking management, and calendar integrations.22 23## Base URL24 25All API requests should be made to:26```27https://api.cal.com/v228```29 30## Required Credentials31 32| Environment Variable | Required | Description |33|---------------------|----------|-------------|34| `CAL_API_KEY` | Yes | Cal.diy API key (prefixed with `cal_live_` or `cal_test_`). Used as Bearer token for all API requests. Generate from Settings > Developer > API Keys. |35| `CAL_CLIENT_ID` | No | OAuth client ID for platform integrations that manage users on behalf of others. Sent as `x-cal-client-id` header. |36| `CAL_SECRET_KEY` | No | OAuth client secret for platform integrations. Sent as `x-cal-secret-key` header. |37| `CAL_WEBHOOK_SECRET` | No | Secret for verifying webhook payload signatures via the `X-Cal-Signature-256` header. |38 39## Authentication40 41All API requests require authentication via Bearer token:42 43```44Authorization: Bearer cal_<your_api_key>45```46 47For detailed authentication methods including OAuth/Platform authentication, see `references/authentication.md`.48 49## Core Concepts50 51**Event Types** define bookable meeting configurations (duration, location, availability rules). Each event type has a unique slug used in booking URLs.52 53**Bookings** are confirmed appointments created when someone books an event type. Each booking has a unique UID for identification.54 55**Schedules** define when a user is available for bookings. Users can have multiple schedules with different working hours.56 57**Slots** represent available time windows that can be booked based on event type configuration and user availability.58 59## Reference Documentation60 61This skill includes detailed API reference documentation for each domain:62 63| Reference | Description |64|-----------|-------------|65| `references/authentication.md` | API key and OAuth authentication, rate limiting, security best practices |66| `references/bookings.md` | Create, list, cancel, reschedule bookings |67| `references/event-types.md` | Configure bookable meeting types |68| `references/schedules.md` | Manage user availability schedules |69| `references/slots-availability.md` | Query available time slots |70| `references/calendars.md` | Calendar connections and busy times |71| `references/webhooks.md` | Real-time event notifications |72 73## Quick Start74 75### 1. Check Available Slots76 77Before creating a booking, check available time slots:78 79```http80GET /v2/slots?startTime=2024-01-15T00:00:00Z&endTime=2024-01-22T00:00:00Z&eventTypeId=12381```82 83See `references/slots-availability.md` for full details.84 85### 2. Create a Booking86 87```http88POST /v2/bookings89Content-Type: application/json90 91{92  "start": "2024-01-15T10:00:00Z",93  "eventTypeId": 123,94  "attendee": {95    "name": "John Doe",96    "email": "john@example.com",97    "timeZone": "America/New_York"98  }99}100```101 102See `references/bookings.md` for all booking operations.103 104### 3. Set Up Webhooks105 106Receive real-time notifications for booking events:107 108```http109POST /v2/webhooks110Content-Type: application/json111 112{113  "subscriberUrl": "https://your-app.com/webhook",114  "triggers": ["BOOKING_CREATED", "BOOKING_CANCELLED"]115}116```117 118See `references/webhooks.md` for available triggers and payload formats.119 120## Common Workflows121 122**Book a meeting**: Check slots -> Create booking -> Store booking UID123 124**Reschedule**: Get new slots -> POST /v2/bookings/{uid}/reschedule125 126**Cancel**: POST /v2/bookings/{uid}/cancel with optional reason127 128## Best Practices129 1301. Always check slot availability before creating bookings1312. Store booking UIDs for future operations (cancel, reschedule)1323. Use ISO 8601 format for all timestamps1334. Implement webhook handlers for real-time updates1345. Handle rate limiting with exponential backoff135 136## Additional Resources137 138- [Full API Reference](https://cal.com/docs/api-reference/v2)139- [OpenAPI Specification](https://api.cal.com/v2/docs)140