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

Always check slot availability before creating bookings
Store booking UIDs for future reference (cancel, reschedule)
Handle timezone conversions carefully - always use ISO 8601 format
Implement webhook handlers for real-time booking updates
Cache event type data to reduce API calls
Use appropriate error handling for all API calls

calcom-api

NPX Install

Tags

SKILL.md Content

Cal.com API v2

Base URL

Authentication

Core Concepts

Event Types

Bookings

Schedules

Slots

Common Operations

Check Available Slots

Create a Booking

Get Bookings

Get a Single Booking

Cancel a Booking

Reschedule a Booking

List Event Types

Get a Single Event Type

Create an Event Type

List Schedules

Get Default Schedule

Create a Schedule

Get Current User

Team and Organization Endpoints

List Organization Teams

Get Team Event Types

Create Team Booking

Webhooks

List Webhooks

Create a Webhook

Calendar Integration

List Connected Calendars

Check Busy Times

Error Handling

Rate Limiting

Pagination

Best Practices

Additional Resources