---
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](https://cal.com/docs/api-reference/v2/introduction) — authentication methods, rate limits, endpoint overview
2. [OAuth & Scopes](https://cal.com/docs/api-reference/v2/oauth) — OAuth setup, available scopes, authorization flow
3. [Access Control & Roles](https://cal.com/docs/api-reference/v2/access-control) — membership roles, PBAC, scope levels for teams and orgs
4. [Agent Quickstart](https://cal.com/docs/agent-quickstart) — MCP server setup and device authorization for headless agents
5. [Bookings API](https://cal.com/docs/api-reference/v2/bookings/create-a-booking) — create, reschedule, cancel bookings
6. [Slots API](https://cal.com/docs/api-reference/v2/slots/get-available-time-slots-for-an-event-type) — fetch available time slots
7. [Webhooks Guide](https://cal.com/docs/developing/guides/automation/webhooks) — webhook setup and automation patterns

---

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