Назад към всички

calcom-api

// Interact with the Cal.com API v2 to manage scheduling, bookings, event types, availability, and calendars. Use this skill when building integrations that need to create or manage bookings, check availability, configure event types, or sync calendars with Cal.com's scheduling infrastructure.

$ git log --oneline --stat
stars:40,437
forks:7.7k
updated:March 4, 2026
SKILL.mdreadonly
SKILL.md Frontmatter
namecalcom-api
descriptionInteract with the Cal.com API v2 to manage scheduling, bookings, event types, availability, and calendars. Use this skill when building integrations that need to create or manage bookings, check availability, configure event types, or sync calendars with Cal.com's scheduling infrastructure.
env[object Object]

Cal.com API v2

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

Required Credentials

Environment VariableRequiredDescription
CAL_API_KEYYesCal.com API key (prefixed with cal_live_ or cal_test_). Used as Bearer token for all API requests. Generate from Settings > Developer > API Keys.
CAL_CLIENT_IDNoOAuth client ID for platform integrations that manage users on behalf of others. Sent as x-cal-client-id header.
CAL_SECRET_KEYNoOAuth client secret for platform integrations. Sent as x-cal-secret-key header.
CAL_WEBHOOK_SECRETNoSecret for verifying webhook payload signatures via the X-Cal-Signature-256 header.

Authentication

All API requests require authentication via Bearer token:

Authorization: Bearer cal_<your_api_key>

For detailed authentication methods including OAuth/Platform authentication, see references/authentication.md.

Core Concepts

Event Types define bookable meeting configurations (duration, location, availability rules). Each event type has a unique slug used in booking URLs.

Bookings are confirmed appointments created when someone books an event type. Each booking has a unique UID for identification.

Schedules define when a user is available for bookings. Users can have multiple schedules with different working hours.

Slots represent available time windows that can be booked based on event type configuration and user availability.

Reference Documentation

This skill includes detailed API reference documentation for each domain:

ReferenceDescription
references/authentication.mdAPI key and OAuth authentication, rate limiting, security best practices
references/bookings.mdCreate, list, cancel, reschedule bookings
references/event-types.mdConfigure bookable meeting types
references/schedules.mdManage user availability schedules
references/slots-availability.mdQuery available time slots
references/calendars.mdCalendar connections and busy times
references/webhooks.mdReal-time event notifications

Quick Start

1. 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

See references/slots-availability.md for full details.

2. 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"
  }
}

See references/bookings.md for all booking operations.

3. Set Up Webhooks

Receive real-time notifications for booking events:

POST /v2/webhooks
Content-Type: application/json

{
  "subscriberUrl": "https://your-app.com/webhook",
  "triggers": ["BOOKING_CREATED", "BOOKING_CANCELLED"]
}

See references/webhooks.md for available triggers and payload formats.

Common Workflows

Book a meeting: Check slots -> Create booking -> Store booking UID

Reschedule: Get new slots -> POST /v2/bookings/{uid}/reschedule

Cancel: POST /v2/bookings/{uid}/cancel with optional reason

Best Practices

  1. Always check slot availability before creating bookings
  2. Store booking UIDs for future operations (cancel, reschedule)
  3. Use ISO 8601 format for all timestamps
  4. Implement webhook handlers for real-time updates
  5. Handle rate limiting with exponential backoff

Additional Resources