Set up Cal.com with an AI agent

name: calcom
description: Use when building scheduling integrations, managing bookings and
  event types, automating workflows, connecting calendars, or working with
  team/organization scheduling infrastructure. Agents should reach for this
  skill when users need to create events, manage availability, book meetings,
  set up webhooks, or integrate Cal.com with other systems.
metadata:
  mintlify-proj: calcom
  version: "1.0"

Cal.com API v2 Skill

Product summary

Cal.com is an open-source scheduling platform with a comprehensive REST API v2 for managing bookings, event types, availability, calendars, and team workflows. Use the API to create and manage events, book meetings, retrieve available time slots, set up webhooks for automation, and integrate Cal.com with external systems. Key endpoints live at https://api.cal.com/v2/. Authentication uses OAuth tokens (recommended), API keys (prefix cal_ for test, cal_live_ for production), or managed user access tokens. Rate limit: 120 requests/minute by default (API key auth). Primary docs: https://cal.com/docs/api-reference/v2/introduction

When to use

Reach for this skill when:

• Booking operations: Creating, rescheduling, cancelling, or confirming bookings via API
• Event type management: Creating, updating, or listing event types for users or teams
• Availability queries: Fetching available time slots for scheduling
• Calendar integration: Connecting Google, Outlook, Apple calendars or checking busy times
• Workflow automation: Setting up webhooks or workflows triggered by booking events
• Team/org management: Managing teams, memberships, roles, and permissions
• Agent connections: Using MCP server or device authorization for headless agents
• Booking page access: Reading public booking pages without authentication (.md or /llms.txt suffix)

Quick reference

Authentication methods

Method	Use case	Header	Prefix
OAuth token	Recommended; user-authorized access	Authorization: Bearer <token>	N/A
API key	Direct access; easier setup	Authorization: Bearer <token>	cal_ (test), cal_live_ (prod)
Managed user token	Platform customers managing users	Authorization: Bearer <token>	N/A

Core API endpoints

Resource	Key endpoints
Bookings	POST /v2/bookings (create), GET /v2/bookings (list), PATCH /v2/bookings/{uid} (reschedule), DELETE /v2/bookings/{uid} (cancel)
Event Types	POST /v2/event-types (create), GET /v2/event-types (list), PATCH /v2/event-types/{id} (update), DELETE /v2/event-types/{id}
Slots	GET /v2/slots?eventTypeId=X&start=Y&end=Z&timeZone=TZ (get available times)
Schedules	POST /v2/schedules (create), GET /v2/schedules (list), PATCH /v2/schedules/{id} (update)
Calendars	GET /v2/calendars (list), POST /v2/calendars/{calendar}/connect (OAuth URL), DELETE /v2/calendars/{id} (disconnect)
Webhooks	POST /v2/webhooks (create), GET /v2/webhooks (list), PATCH /v2/webhooks/{id} (update), DELETE /v2/webhooks/{id}
Teams	POST /v2/teams (create), GET /v2/teams (list), PATCH /v2/teams/{id} (update)
Workflows	POST /v2/workflows (create), GET /v2/workflows (list), PATCH /v2/workflows/{id} (update)

Required headers

Authorization: Bearer YOUR_API_KEY_OR_TOKEN
cal-api-version: 2024-06-14  (or latest version for specific endpoints)
Content-Type: application/json

OAuth scopes (most common)

Scope	Grants access to
EVENT_TYPE_READ	List and view event types
EVENT_TYPE_WRITE	Create, update, delete event types
BOOKING_READ	View bookings and attendees
BOOKING_WRITE	Create, reschedule, cancel bookings
SCHEDULE_READ	View availability and schedules
SCHEDULE_WRITE	Create, update, delete schedules
APPS_READ	View connected calendars
APPS_WRITE	Connect/disconnect calendars
WEBHOOK_READ	View webhooks
WEBHOOK_WRITE	Create, update, delete webhooks
PROFILE_READ	View user profile
PROFILE_WRITE	Update user profile

Decision guidance

When to use OAuth vs API key

Scenario	Use OAuth	Use API key
Building a third-party app or integration	✓
User-authorized access; app store listing	✓
Server-to-server automation; internal tools		✓
Testing or development		✓
Need fine-grained scopes	✓
Simple, direct access		✓

When to use individual vs team vs org endpoints

Scope	Endpoint pattern	Use when
Individual	/v2/event-types, /v2/bookings	Managing single user's events and bookings
Team	/v2/teams/{teamId}/event-types	Managing shared team resources; round-robin or collective scheduling
Organization	/v2/organizations/{orgId}/teams	Multi-team management; org-wide settings and roles

Booking creation: public vs authenticated

Scenario	Authentication	Endpoint
Public booking (guest booking)	None required	POST /v2/bookings (public endpoint)
Authenticated booking (admin creating)	API key or OAuth	POST /v2/bookings (with token)
Fetch slots for public page	None required	GET /v2/slots?eventTypeSlug=X&username=Y

Workflow

Typical booking flow

1. Identify the event type

   • If you have the event type ID, use it directly
   • Otherwise, query GET /v2/event-types to list and find the ID
   • For team events, use GET /v2/teams/{teamId}/event-types

2. Get available slots

   • Call GET /v2/slots?eventTypeId=X&start=YYYY-MM-DD&end=YYYY-MM-DD&timeZone=TZ
   • Specify date range and timezone; returns available time slots
   • For rescheduling, add bookingUidToReschedule=UID to exclude the original slot

3. Create the booking

   • Call POST /v2/bookings with event type ID, attendee email, start time, and any custom booking fields
   • Include cal-api-version header (e.g., 2024-06-14)
   • Response includes booking UID, confirmation status, and attendee details

4. Handle confirmation if required

   • If event type requires confirmation, booking starts in PENDING_CONFIRMATION status
   • Call POST /v2/bookings/{uid}/confirm to confirm (host only)
   • Call POST /v2/bookings/{uid}/decline to decline

5. Manage the booking

   • Reschedule: POST /v2/bookings/{uid}/reschedule with new start time
   • Cancel: DELETE /v2/bookings/{uid}
   • Get details: GET /v2/bookings/{uid}

Typical event type creation flow

1. Prepare event type data

   • Required: title, slug, lengthInMinutes, schedulingType (collective, roundRobin, managed)
   • Optional: description, bookingLimits, buffers, bookingFields, destinationCalendar

2. Create the event type

   • Individual: POST /v2/event-types
   • Team: POST /v2/teams/{teamId}/event-types
   • Include cal-api-version header

3. Configure booking fields (optional)

   • Call POST /v2/event-types/{id}/booking-fields to add custom fields
   • At least one contact field (email or phone) must be visible and required

4. Set up webhooks (optional)

   • Call POST /v2/event-types/{id}/webhooks to trigger automations on booking events
   • Specify triggers (BOOKING_CREATED, BOOKING_RESCHEDULED, etc.) and subscriber URL

5. Verify and test

   • Fetch the event type: GET /v2/event-types/{id}
   • Test booking flow with test slots

Typical webhook setup flow

1. Identify trigger events

   • Choose from: BOOKING_CREATED, BOOKING_RESCHEDULED, BOOKING_CANCELLED, MEETING_STARTED, MEETING_ENDED, RECORDING_READY, etc.

2. Create webhook

   • Call POST /v2/webhooks or POST /v2/event-types/{id}/webhooks
   • Provide subscriberUrl (your endpoint), triggers array, and active: true
   • Optionally add secret for signature verification and customHeaders for auth

3. Verify webhook delivery

   • Cal.com sends POST requests to your subscriber URL with booking data
   • Verify the signature using the secret (if provided)
   • Respond with 200 OK to confirm receipt

4. Update or delete

   • Modify: PATCH /v2/webhooks/{id}
   • Remove: DELETE /v2/webhooks/{id}

Common gotchas

• Missing cal-api-version header: Some endpoints default to older versions if not specified. Always include cal-api-version: 2024-06-14 (or the latest version for your use case).

• Time zones in slot queries: Always pass timeZone parameter in slot queries; defaults to UTC. Use IANA timezone names (e.g., America/New_York, Europe/London).

• Booking field requirements: At least one contact field (email or phone) must remain visible and required on event types. Attempting to hide all contact fields fails.

• Managed event types and slots: Managed event types are templates; you cannot fetch slots for the parent. Fetch slots for the child event type assigned to a specific team member.

• Confirmation policy: If an event type requires confirmation, bookings start in PENDING_CONFIRMATION status. Guests cannot confirm their own bookings; only hosts can.

• Rate limits: API key auth is limited to 120 requests/minute by default. Markdown documents (.md and /llms.txt) are limited to 300 requests/minute per IP. Hitting the limit returns 429 with Retry-After header.

• OAuth token expiry: Access tokens expire in 60 minutes; refresh tokens last 1 year. Use the refresh endpoint to get new tokens before expiry.

• Scope mismatch: OAuth tokens can only access endpoints covered by their granted scopes. Requests outside scopes return 403 Forbidden.

• Team vs org endpoints: Team endpoints require team membership; org endpoints require org membership. Organization admins can access team endpoints without separate team membership.

• Webhook payload versions: Webhook version 2026-07-27 includes ICS calendar content; version 2021-10-20 does not. Specify version when creating webhooks.

• Booking location updates: Use PATCH /v2/bookings/{uid}/location to update meeting location after booking is created.

• Attendee phone numbers: If SMS reminders are enabled on an event type, attendees must provide phone numbers during booking. Pass attendee.phoneNumber in the booking request.

Verification checklist

Before submitting work with Cal.com API:

• Authentication header is present and valid (Authorization: Bearer <token>)
• cal-api-version header is included for endpoints that require it
• Time zones are specified in slot queries (not relying on UTC default)
• Booking requests include required fields: eventTypeId, attendee.email, start, end
• Event type creation includes required fields: title, slug, lengthInMinutes, schedulingType
• At least one contact field (email or phone) is visible and required on event types
• Webhook subscriber URL is publicly accessible and responds with 200 OK
• OAuth scopes match the endpoints being called
• Team/org membership is verified before accessing team/org endpoints
• Booking confirmation flow is handled if event type requires confirmation
• Error responses are checked for rate limits (429) or scope issues (403)

Resources

Comprehensive API navigation: https://cal.com/docs/llms.txt

Critical documentation pages:

1. API v2 Introduction & Authentication — authentication methods, rate limits, endpoint overview
2. OAuth & Scopes — OAuth setup, available scopes, authorization flow
3. Access Control & Roles — membership roles, PBAC, scope levels for teams and orgs
4. Agent Quickstart — MCP server setup and device authorization for headless agents
5. Bookings API — create, reschedule, cancel bookings
6. Slots API — fetch available time slots
7. Webhooks Guide — webhook setup and automation patterns

---

For additional documentation and navigation, see: https://cal.com/docs/llms.txt