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`: ISO 8601 booking start time - `eventTypeId`: ID of the event type to book - `attendee.name`: Attendee's full name - `attendee.email`: Attendee's email address - `attendee.timeZone`: Attendee's timezone ### Get Bookings List bookings with optional filters: ```http GET /v2/bookings?status=upcoming&take=10 ``` Query parameters: - `status`: Filter by status (upcoming, recurring, past, cancelled, unconfirmed) - `attendeeEmail`: Filter by attendee email - `eventTypeId`: Filter by event type - `take`: Number of results (max 250) - `skip`: Pagination offset ### Get a Single Booking ```http GET /v2/bookings/{bookingUid} ``` ### Cancel a Booking ```http POST /v2/bookings/{bookingUid}/cancel Content-Type: application/json { "cancellationReason": "Schedule conflict" } ``` ### Reschedule a Booking ```http POST /v2/bookings/{bookingUid}/reschedule Content-Type: application/json { "start": "2024-01-16T14:00:00Z", "reschedulingReason": "Conflict with another meeting" } ``` ### List Event Types ```http GET /v2/event-types ``` Returns all event types for the authenticated user. ### Get a Single Event Type ```http GET /v2/event-types/{eventTypeId} ``` ### Create an Event Type ```http POST /v2/event-types Content-Type: application/json { "title": "30 Minute Meeting", "slug": "30min", "lengthInMinutes": 30, "locations": [ { "type": "integration", "integration": "cal-video" } ] } ``` ### List Schedules ```http GET /v2/schedules ``` ### Get Default Schedule ```http GET /v2/schedules/default ``` ### Create a Schedule ```http POST /v2/schedules Content-Type: application/json { "name": "Working Hours", "timeZone": "America/New_York", "isDefault": true, "availability": [ { "days": [1, 2, 3, 4, 5], "startTime": "09:00", "endTime": "17:00" } ] } ``` Days are 0-indexed (0 = Sunday, 1 = Monday, etc.). ### Get Current User ```http GET /v2/me ``` Returns the authenticated user's profile information. ## Team and Organization Endpoints For team bookings and organization management, use the organization-scoped endpoints: ### List Organization Teams ```http GET /v2/organizations/{orgId}/teams ``` ### Get Team Event Types ```http GET /v2/organizations/{orgId}/teams/{teamId}/event-types ``` ### Create Team Booking Team event types support different scheduling modes: - `COLLECTIVE`: All team members must attend - `ROUND_ROBIN`: Distributes bookings among team members ## Webhooks Configure webhooks to receive real-time notifications: ### List Webhooks ```http GET /v2/webhooks ``` ### Create a Webhook ```http POST /v2/webhooks Content-Type: application/json { "subscriberUrl": "https://your-app.com/webhook", "triggers": ["BOOKING_CREATED", "BOOKING_CANCELLED"], "active": true } ``` Available triggers: - `BOOKING_CREATED` - `BOOKING_CANCELLED` - `BOOKING_RESCHEDULED` - `BOOKING_CONFIRMED` - `MEETING_STARTED` - `MEETING_ENDED` ## Calendar Integration ### List Connected Calendars ```http GET /v2/calendars ``` ### Check Busy Times ```http GET /v2/calendars/busy-times?startTime=2024-01-15T00:00:00Z&endTime=2024-01-22T00:00:00Z ``` ## Error Handling The API returns standard HTTP status codes: - `200`: Success - `201`: Created - `400`: Bad Request (invalid parameters) - `401`: Unauthorized (invalid or missing API key) - `403`: Forbidden (insufficient permissions) - `404`: Not Found - `422`: Unprocessable Entity (validation error) - `500`: Internal Server Error Error responses include a message field: ```json { "status": "error", "message": "Booking not found" } ``` ## Rate Limiting The API implements rate limiting. If you exceed the limit, you'll receive a `429 Too Many Requests` response. Implement exponential backoff for retries. ## Pagination List endpoints support pagination via `take` and `skip` parameters: - `take`: Number of items to return (default: 10, max: 250) - `skip`: Number of items to skip ## Best Practices 1. Always check slot availability before creating bookings 2. Store booking UIDs for future reference (cancel, reschedule) 3. Handle timezone conversions carefully - always use ISO 8601 format 4. Implement webhook handlers for real-time booking updates 5. Cache event type data to reduce API calls 6. Use appropriate error handling for all API calls ## Additional Resources - [Full API Reference](https://cal.com/docs/api-reference/v2) - [OpenAPI Specification](https://api.cal.com/v2/docs)