Agent Skills: cal-com

Troubleshooting

If requests fail, run zero doctor check-connector --env-name CALCOM_TOKEN or zero doctor check-connector --url https://api.cal.com/v2/me --method GET

Core APIs

Get Current User

curl -s "https://api.cal.com/v2/me" --header "Authorization: Bearer $CALCOM_TOKEN" --header "cal-api-version: 2024-08-13" | jq '{id, email, name, username, timeZone}'

List Event Types

curl -s "https://api.cal.com/v2/event-types" --header "Authorization: Bearer $CALCOM_TOKEN" --header "cal-api-version: 2024-08-13" | jq '[.data[] | {id, title, slug, length, hidden}]'

Get Event Type

Replace <event-type-id> with the numeric ID from the list above:

curl -s "https://api.cal.com/v2/event-types/<event-type-id>" --header "Authorization: Bearer $CALCOM_TOKEN" --header "cal-api-version: 2024-08-13" | jq '.data | {id, title, length, description, locations}'

Get Availability

Check available slots for an event type. Replace <username> and <event-type-slug> with actual values. Dates in YYYY-MM-DD format:

curl -s "https://api.cal.com/v2/slots/available?username=<username>&eventTypeSlug=<event-type-slug>&startTime=2025-01-15&endTime=2025-01-22&timeZone=America/New_York" --header "Authorization: Bearer $CALCOM_TOKEN" --header "cal-api-version: 2024-08-13" | jq '{slots: [.data.slots | to_entries[] | {date: .key, times: [.value[] | .time]}] | .[0:3]}'

Create Booking

Write to /tmp/calcom_request.json:

{
  "start": "2025-01-20T14:00:00.000Z",
  "eventTypeId": 123,
  "attendee": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "timeZone": "America/New_York",
    "language": "en"
  },
  "metadata": {
    "source": "clerk_sync"
  }
}

curl -s -X POST "https://api.cal.com/v2/bookings" --header "Authorization: Bearer $CALCOM_TOKEN" --header "cal-api-version: 2024-08-13" --header "Content-Type: application/json" -d @/tmp/calcom_request.json | jq '{uid, status, start, end, attendees: [.attendees[] | {name, email}]}'

Docs: https://cal.com/docs/api-reference/v2/bookings/create-a-booking

List Bookings

curl -s "https://api.cal.com/v2/bookings?take=20" --header "Authorization: Bearer $CALCOM_TOKEN" --header "cal-api-version: 2024-08-13" | jq '[.data[] | {uid, status, title, start, end, attendeeName: .attendees[0].name}]'

Get Booking

Replace <booking-uid> with the booking UID from the list above:

curl -s "https://api.cal.com/v2/bookings/<booking-uid>" --header "Authorization: Bearer $CALCOM_TOKEN" --header "cal-api-version: 2024-08-13" | jq '{uid, status, title, start, end, attendees}'

Cancel Booking

Replace <booking-uid> with the booking UID.

Write to /tmp/calcom_request.json:

{
  "cancellationReason": "Schedule conflict"
}

curl -s -X DELETE "https://api.cal.com/v2/bookings/<booking-uid>/cancel" --header "Authorization: Bearer $CALCOM_TOKEN" --header "cal-api-version: 2024-08-13" --header "Content-Type: application/json" -d @/tmp/calcom_request.json | jq '{status}'

Reschedule Booking

Replace <booking-uid> with the booking UID.

Write to /tmp/calcom_request.json:

{
  "start": "2025-01-22T15:00:00.000Z",
  "reschedulingReason": "Attendee requested different time"
}

curl -s -X POST "https://api.cal.com/v2/bookings/<booking-uid>/reschedule" --header "Authorization: Bearer $CALCOM_TOKEN" --header "cal-api-version: 2024-08-13" --header "Content-Type: application/json" -d @/tmp/calcom_request.json | jq '{uid, status, start, end}'

Guidelines

1. API version header: Always include cal-api-version: 2024-08-13 — requests without this header will fail.
2. API key prefix: Cal.com API keys are prefixed with cal_live_ (production) or cal_test_ (test environment).
3. eventTypeId: Required when creating a booking — get it from the List Event Types endpoint.
4. Timestamps: Use ISO 8601 format with UTC timezone (e.g., 2025-01-20T14:00:00.000Z).
5. Rate limits: 120 requests per minute with API key auth. Response headers include X-RateLimit-Remaining.
6. Self-hosted: If using a self-hosted Cal.com instance, replace api.cal.com with your own domain.
7. Booking confirmation: If an event type requires manual confirmation, bookings start with pending status until confirmed.