cal-com

name	cal-com
description	Manage Cal.com scheduling - list bookings, event types, and availability. Use when you need to check schedules, manage booking links, or automate meeting scheduling with Cal.com's API.

Cal.com API

Manage scheduling and bookings via Cal.com API.

Setup

1. Get API key: Cal.com → Settings → Developer → API Keys
2. Store key:

mkdir -p ~/.config/calcom
echo "cal_live_XXXXX" > ~/.config/calcom/api_key

API Basics

CAL_KEY=$(cat ~/.config/calcom/api_key)
CAL_URL="https://api.cal.com/v1"  # or self-hosted URL

curl -s "${CAL_URL}/me?apiKey=${CAL_KEY}" | jq

List Event Types

curl -s "${CAL_URL}/event-types?apiKey=${CAL_KEY}" | jq '.event_types[] | {id, title, slug, length}'

Get Event Type

EVENT_TYPE_ID="123"

curl -s "${CAL_URL}/event-types/${EVENT_TYPE_ID}?apiKey=${CAL_KEY}" | jq

List Bookings

curl -s "${CAL_URL}/bookings?apiKey=${CAL_KEY}" | jq '.bookings[] | {id, title, startTime, endTime, status}'

Get Booking

BOOKING_ID="123"

curl -s "${CAL_URL}/bookings/${BOOKING_ID}?apiKey=${CAL_KEY}" | jq

Filter Bookings by Status

# upcoming, past, cancelled, recurring
curl -s "${CAL_URL}/bookings?apiKey=${CAL_KEY}&status=upcoming" | jq '.bookings'

Create Booking

curl -s -X POST "${CAL_URL}/bookings?apiKey=${CAL_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "eventTypeId": 123,
    "start": "2024-01-15T10:00:00.000Z",
    "end": "2024-01-15T10:30:00.000Z",
    "responses": {
      "name": "John Doe",
      "email": "[e-mail]",
      "notes": "Looking forward to our meeting"
    },
    "timeZone": "Europe/Paris",
    "language": "en"
  }' | jq

Cancel Booking

curl -s -X DELETE "${CAL_URL}/bookings/${BOOKING_ID}?apiKey=${CAL_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"cancellationReason": "Schedule conflict"}' | jq

Reschedule Booking

curl -s -X PATCH "${CAL_URL}/bookings/${BOOKING_ID}?apiKey=${CAL_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "start": "2024-01-16T14:00:00.000Z",
    "end": "2024-01-16T14:30:00.000Z"
  }' | jq

List Availabilities

curl -s "${CAL_URL}/availability?apiKey=${CAL_KEY}&eventTypeId=123&dateFrom=2024-01-15&dateTo=2024-01-22" | jq

Get Available Slots

curl -s "${CAL_URL}/slots?apiKey=${CAL_KEY}&eventTypeId=123&startTime=2024-01-15&endTime=2024-01-22&timeZone=Europe/Paris" | jq '.slots'

List Schedules

curl -s "${CAL_URL}/schedules?apiKey=${CAL_KEY}" | jq '.schedules[] | {id, name, timeZone}'

Webhooks

List:

curl -s "${CAL_URL}/webhooks?apiKey=${CAL_KEY}" | jq

Create:

curl -s -X POST "${CAL_URL}/webhooks?apiKey=${CAL_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriberUrl": "https://example.com/webhook",
    "eventTriggers": ["BOOKING_CREATED", "BOOKING_CANCELLED"],
    "active": true
  }' | jq

Event Triggers

• BOOKING_CREATED
• BOOKING_CANCELLED
• BOOKING_RESCHEDULED
• BOOKING_CONFIRMED
• BOOKING_REJECTED

Self-Hosted

For self-hosted Cal.com, change base URL:

CAL_URL="https://your-cal-instance.com/api/v1"

Rate Limits

• Default: No published limits (be reasonable)
• Self-hosted: Depends on your infrastructure