Cal.com Scheduling

---
name: cal-com
description: Cal.com API v2 for AI agents to manage scheduling - check availability, create bookings, handle rescheduling and cancellations.
---

# Cal.com Scheduling API

AI agents can use Cal.com API v2 to manage scheduling for users.

## Installation

Install the CLI via npm or see official docs for other methods:
https://cal.com/docs/agents

## Authentication

Generate an API key in Settings → Developer → API Keys:
https://app.cal.com/settings/developer/api-keys

Set as environment variable:
export CAL_API_KEY=cal_live_xxx

## Required Header

Always include: cal-api-version: 2024-08-13

## Common Workflows

### 1. Check Availability

curl -X GET "https://api.cal.com/v2/slots?username=USERNAME&eventSlug=EVENT_SLUG&startTime=2024-01-15T00:00:00Z&endTime=2024-01-16T23:59:59Z" -H "cal-api-version: 2024-08-13"

Response: slots with available times

### 2. Create Booking

curl -X POST "https://api.cal.com/v2/bookings" -H "Content-Type: application/json" -H "cal-api-version: 2024-08-13" -d "{eventTypeSlug: 15min, username: USERNAME, start: 2024-01-15T09:00:00Z, attendee: {name: John Doe, email: john@example.com, timeZone: America/New_York}}"

Note: Booking creation is public - no auth required!

### 3. Custom Booking Questions

Include required fields in bookingFieldsResponses

### 4. Instant Bookings (urgent)

Use instant: true flag for urgent requests

### 5. Get Event Types

curl -X GET "https://api.cal.com/v2/event-types?username=USERNAME" -H "Authorization: Bearer $CAL_API_KEY" -H "cal-api-version: 2024-08-13"

### 6. Reschedule

curl -X POST "https://api.cal.com/v2/bookings/BOOKING_UID/reschedule" -H "Content-Type: application/json" -H "cal-api-version: 2024-08-13" -d "{start: 2024-01-16T10:00:00Z, rescheduleReason: Requested different time}"

### 7. Cancel

curl -X POST "https://api.cal.com/v2/bookings/BOOKING_UID/cancel" -H "Content-Type: application/json" -H "cal-api-version: 2024-08-13" -d "{cancellationReason: No longer needed}"

## Key Endpoints

GET /v2/slots - Check available time slots
POST /v2/bookings - Create a new booking
POST /v2/bookings/:uid/reschedule - Reschedule booking
POST /v2/bookings/:uid/cancel - Cancel booking
GET /v2/event-types - List event types
GET /v2/schedules - Get user schedules

## Best Practices

1. Always include cal-api-version: 2024-08-13 header
2. Validate availability before booking
3. Handle time zones explicitly
4. Implement retry logic for API failures
5. Use webhooks for real-time updates

## Rate Limits

120 requests per minute with API key authentication.

---

Source: cal.com/docs/agents.md