Problem
The cal-api-version header is required for API v2 endpoints. When Cal.com updates this version (e.g., from 2024-08-13 to 2026-02-25 for POST /bookings), existing integrations break silently with no prior notice.
There is currently no programmatic way to:
- Discover the latest supported
cal-api-version for a given endpoint.
- Receive notifications when a version changes.
- Maintain backward compatibility with older versions.
This causes all automations relying on hardcoded versions to fail unexpectedly.
Proposed Solution
One or more of the following:
- A
GET /api/v2/versions endpoint returning the latest cal-api-version per endpoint.
- A deprecation policy with advance notice before breaking changes.
- Backward compatibility: continue supporting older
cal-api-version values for a grace period.
- A changelog webhook or notification system for version updates.
Impact
Any external integration, automation, or AI agent using the Cal.com API v2 is affected. Breaking changes without notice undermine trust in the API's stability.
Environment
- API: Cal.com API v2
- Affected endpoint example:
POST /v2/bookings (cal-api-version: 2026-02-25)
Problem
The
cal-api-versionheader is required for API v2 endpoints. When Cal.com updates this version (e.g., from2024-08-13to2026-02-25forPOST /bookings), existing integrations break silently with no prior notice.There is currently no programmatic way to:
cal-api-versionfor a given endpoint.This causes all automations relying on hardcoded versions to fail unexpectedly.
Proposed Solution
One or more of the following:
GET /api/v2/versionsendpoint returning the latestcal-api-versionper endpoint.cal-api-versionvalues for a grace period.Impact
Any external integration, automation, or AI agent using the Cal.com API v2 is affected. Breaking changes without notice undermine trust in the API's stability.
Environment
POST /v2/bookings(cal-api-version: 2026-02-25)