calcom-api

The Cal.diy API v2 skill enables AI agents to programmatically interact with self-hosted Cal.diy scheduling infrastructure. This toolset is designed for developers and automation engineers looking to embed powerful scheduling capabilities into custom applications, internal tools, or AI-driven workflows. By leveraging this API, users can transition from manual calendar coordination to fully automated booking systems that respect complex availability rules, handle multiple event types, and verify real-time calendar status.

Key capabilities include:

• Comprehensive booking lifecycle management, including creation, rescheduling, cancellation, and retrieval of appointment details.
• Dynamic slot querying to identify available time windows based on specific event types, user constraints, and date ranges.
• Granular control over event type configurations, enabling agents to define meeting durations, locations, and booking rules.
• Real-time notification support through webhooks, allowing systems to react immediately to booking events like creation, confirmation, or cancellation.
• Full support for multi-tenant or platform integrations via client ID and secret authentication headers.

Practical usage notes and constraints:

• All requests to the API require a valid bearer token using the CAL_API_KEY environment variable. For platform scenarios, ensure headers for x-cal-client-id and x-cal-secret-key are properly injected.
• Always prioritize the use of ISO 8601 date formats for all timestamp inputs to ensure compatibility with the underlying system.
• Prior to creating a booking, agents should consistently perform a GET /v2/slots request to validate that the requested time window remains available.
• Store and track booking UIDs returned by the API; these identifiers are essential for any subsequent lifecycle operations such as updates or cancellations.
• Implement robust error handling and respect rate limits using exponential backoff strategies to maintain system stability when performing batch operations or high-frequency scheduling tasks.
• Note that this skill interacts with the open-source Cal.diy instance, which is intended for self-hosted environments. Ensure your target infrastructure is properly configured with Node.js and PostgreSQL as required by the platform.