Skip to main content
skill CX Codex

calcom-api — Claude Code skill: what it does, how to install

calcom-api equips AI agents with guidelines for the Cal.diy API v2 to check slot availability, book meetings, and handle calendar schedules.

MIT 1 installs ★ 50,297 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add calcom/cal.diy --skill calcom-api -a claude-code
Open on GitHub

What calcom-api does

This skill guides coding assistants when interacting with Cal.diy API v2 at https://api.cal.com/v2. It covers foundational domain concepts including event types, bookings identified by UID, user schedules, and slot discovery. Agents learn the recommended flow: query open windows first, then create a booking, and store the UID for future rescheduling or cancellation.

API calls require CAL_API_KEY starting with cal_live_ or cal_test_. Without it, calls fail. Platform integrations handling users on behalf of others also use CAL_CLIENT_ID and CAL_SECRET_KEY, while webhook payload signature verification relies on CAL_WEBHOOK_SECRET.

What it helps with

  • find open meeting slots for a specific event type ID
  • book an appointment with attendee details via /v2/bookings
  • reschedule or cancel an existing booking using its UID
  • register webhook endpoints to capture booking lifecycle events

Example prompts for the agent

  • Check available slots for eventTypeId 123 between 2024-01-15 and 2024-01-22
  • Book a meeting for John Doe at [email protected] using slot 2024-01-15T10:00:00Z
  • Cancel booking uid_987 with the reason requested by client

How to install calcom-api

1Skills CLI (Vercel)

npx skills add calcom/cal.diy --skill calcom-api -a claude-code

2Manually: put the files in place

~/.claude/skills/calcom-api/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/calcom-api/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about calcom-api

How to install calcom-api in Claude Code?

Run npx skills add calcom/cal.diy --skill calcom-api -a claude-code. The file will be placed at ~/.claude/skills/calcom-api/SKILL.md.

What does the calcom-api skill do?

It teaches AI coding agents how to interact with the Cal.diy API v2 for scheduling workflows, checking slots, and managing appointments.

Which environment variables are required?

Only CAL_API_KEY with a cal_live_ or cal_test_ prefix is mandatory. Platform setups can also supply CAL_CLIENT_ID, CAL_SECRET_KEY, and CAL_WEBHOOK_SECRET.

Source text

SKILL.md · MIT
---
name: calcom-api
description: Interact with the Cal.diy 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.diy's scheduling infrastructure.
env:
  CAL_API_KEY:
    description: "Cal.diy API key (prefixed with cal_live_ or cal_test_). Required for all API requests."
    required: true
  CAL_CLIENT_ID:
    description: "OAuth client ID for platform integrations managing users on behalf of others. Sent as x-cal-client-id header."
    required: false
  CAL_SECRET_KEY:
    description: "OAuth client secret for platform integrations. Sent as x-cal-secret-key header."
    required: false
  CAL_WEBHOOK_SECRET:
    description: "Secret used to verify webhook payload signatures via X-Cal-Signature-256 header."
    required: false
---

# Cal.diy API v2

This skill provides guidance for AI agents to interact with the Cal.diy 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 Variable | Required | Description |
|---------------------|----------|-------------|
| `CAL_API_KEY` | Yes | Cal.diy 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_ID` | No | OAuth client ID for platform integrations that manage users on behalf of others. Sent as `x-cal-client-id` header. |
| `CAL_SECRET_KEY` | No | OAuth client secret for platform integrations. Sent as `x-cal-secret-key` header. |
| `CAL_WEBHOOK_SECRET` | No | Secret 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:

| Reference | Description |
|-----------|-------------|
| `references/authentication.md` | API key and OAuth authentication, rate limiting, security best practices |
| `references/bookings.md` | Create, list, cancel, reschedule bookings |
| `references/event-types.md` | Configure bookable meeting types |
| `references/schedules.md` | Manage user availability schedules |
| `references/slots-availability.md` | Query available time slots |
| `references/calendars.md` | Calendar connections and busy times |
| `references/webhooks.md` | Real-time event notifications |

## Quick Start

### 1. Check Available Slots

Before creating a booking, check available time slots:

```http
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

```http
POST /v2/bookings
Content-Type: application/json

{
  "start": "2024-01-15T10:00:00Z",
  "eventTypeId": 123,
  "attendee": {
    "name": "John Doe",
    "email": "[email protected]",
    "timeZone": "America/New_York"
  }
}
```

See `references/bookings.md` for all booking operations.

### 3. Set Up Webhooks

Receive real-time notifications for booking events:

```http
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

- [Full API Reference](https://cal.com/docs/api-reference/v2)
- [OpenAPI Specification](https://api.cal.com/v2/docs)

© calcom · MIT · calcom/cal.diy

Similar skills

All skills for Backend and APIs →

Project sponsors

Companies that keep this analytics open