| name | cal-com |
| description | Cal.com open-source scheduling API. Use when user mentions "Cal.com", "cal.com", "open source scheduling", "booking", "event types", or asks about interview or meeting scheduling. |
Prerequisites
- Connect Cal.com in Zero at Settings > Connectors > Cal.com.
- Requests require
CALCOM_TOKEN. Zero supplies the same environment variable for OAuth and API token connections.
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 '.data | {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
- API version header: Always include
cal-api-version: 2024-08-13 — requests without this header will fail.
- Authentication: Zero refreshes OAuth tokens automatically. API keys use the
cal_live_ prefix for live environments and cal_ for test environments.
- eventTypeId: Required when creating a booking — get it from the List Event Types endpoint.
- Timestamps: Use ISO 8601 format with UTC timezone (e.g.,
2025-01-20T14:00:00.000Z).
- Rate limits: 120 requests per minute with API key auth. Response headers include
X-RateLimit-Remaining.
- Hosted API: The Zero connector allows requests to the hosted
api.cal.com API.
- Booking confirmation: If an event type requires manual confirmation, bookings start with
pending status until confirmed.
