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_
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:
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
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:
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
GET /v2/bookings/{bookingUid}
Cancel a Booking
POST /v2/bookings/{bookingUid}/cancel
Content-Type
:
application/json
{
"cancellationReason"
:
"Schedule conflict"
}
Reschedule a Booking
POST /v2/bookings/{bookingUid}/reschedule
Content-Type
:
application/json
{
"start"
:
"2024-01-16T14:00:00Z"
,
"reschedulingReason"
:
"Conflict with another meeting"
}
List Event Types
GET /v2/event-types
Returns all event types for the authenticated user.
Get a Single Event Type
GET /v2/event-types/{eventTypeId}
Create an Event Type
POST /v2/event-types
Content-Type
:
application/json
{
"title"
:
"30 Minute Meeting"
,
"slug"
:
"30min"
,
"lengthInMinutes"
:
30
,
"locations"
:
[
{
"type"
:
"integration"
,
"integration"
:
"cal-video"
}
]
}
List Schedules
GET /v2/schedules
Get Default Schedule
GET /v2/schedules/default
Create a Schedule
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
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
GET /v2/organizations/{orgId}/teams
Get Team Event Types
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
GET /v2/webhooks
Create a Webhook
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
GET /v2/calendars
Check Busy Times
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:
{
"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
Additional Resources
Full API Reference
OpenAPI Specification