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:

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

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

{
  "start": "2024-01-15T10:00:00Z",
  "eventTypeId": 123,
  "attendee": {
    "name": "John Doe",
    "email": "[email protected]",
    "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:

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

GET /v2/bookings/{bookingUid}

Cancel a Booking

POST /v2/bookings/{bookingUid}/cancel
Content-Type: application/json

{
  "cancellationReason": "Schedule conflict"
}

Reschedule a Booking

POST /v2/bookings/{bookingUid}/reschedule
Content-Type: application/json

{
  "start": "2024-01-16T14:00:00Z",
  "reschedulingReason": "Conflict with another meeting"
}