Index of every page on this site: llms.txt
All skills
calcom avatar

/calcom-api

@ae027bb
by Cal.com, Inc.calcom/cal.diy50k stars
15,696
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/calcom/cal.diy/calcom-api

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈76 tokens for metadata: the name and description. ≈990 when used: this file. ≈13k more on demand in 7 files.

Description uses 3.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈304 characters, or 3.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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:

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

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts1mo3 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    The skill is a comprehensive API reference for the Cal.com (also known as Cal.diy) scheduling platform. It enables the agent to manage bookings, event types, schedules, and calendars via official API endpoints. No malicious patterns, obfuscation, or security risks were detected. The skill correctly utilizes environment variables for authentication and targets legitimate vendor domains.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

Signed by skilld at ae027bb. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated 7 months ago
Other metadata
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
  }
}

README badge

README badge for calcom/cal.diy/calcom-api