What 60 days of cal.com v2 API changes look like under a merge gate

What we did

We cloned github.com/calcom/cal.com, extracted docs/api-reference/v2/openapi.json at two points: the current HEAD (commit 46eb533d, 2026-05-03) and a baseline roughly 60 days earlier (commit 658e65be, 2026-03-05, the webhook triggers OpenAPI fix). We ran delimit lint in its standard configuration, with no policy overrides. The diff engine classified each change against its 27-type taxonomy. The semver classifier walked the breaking-vs-non-breaking partition and produced a bump recommendation. Everything below is mechanical output, annotated.

Headline numbers

The advertised info.version field on both specs is 1.0.0. A major-class change set shipped under an unchanged version string. The merge gate is designed to catch exactly this asymmetry before publish, not after.

Findings

4 breaking, 1 additive, 2 flagged as spec hygiene. Each finding cites the exact change-type from the 27-type taxonomy, the surface affected, and the consumer impact. Hygiene-class findings are real lint output that a careful reader will re-classify on reading; we surface both classes so the report stays honest.

1. breakingfinding F1
   change type: spec rewrite (whole-document restructuring)
   surface: info.title and overall surface

   The spec title changed from "Cal.com API v2" to "Cal.diy API v2". Endpoint count dropped from 174 to 82. Schema count dropped from 467 to 287. The advertised info.version field stayed at 1.0.0 throughout the window. A consumer pinned to the prior shape sees a major-class change set under the same version string. This is the kind of finding a pre-merge gate exists to surface before publish, not after.

2. breakingfinding F2
   change type: endpoint_removed (99 endpoints, mostly clustered)
   surface: /v2/organizations/{orgId}/* namespace

   Every organizations-scoped endpoint from the prior shape is absent from the new spec. The dropped routes include /attributes, /memberships, /roles, /routing-forms, /delegation-credentials, /workflows, and the team-nested variants under each. Org-level integrations against the prior shape have no drop-in replacement in the new spec without re-mapping to the surviving /v2/teams/* and /v2/calendars/* surfaces.

3. breakingfinding F3
   change type: required_field_added with type change
   surface: OAuth2ClientDto

   The OAuth2ClientDto schema renamed redirect_uri (string) to redirect_uris (array of strings) and re-listed it as required. Both the field name and the field type changed. OAuth registration code that reads or writes the prior string field will not deserialize the new array field, and code that sends the new array shape against the old string contract will be rejected.

4. additivefinding F4
   change type: endpoint_added (7 routes)
   surface: /v2/calendars/connections/* and /v2/calendars/{calendar}/*

   Seven new endpoints landed under the unified-calendar feature, including /v2/calendars/connections, /v2/calendars/connections/{connectionId}/freebusy, /v2/calendars/connections/{connectionId}/events, and /v2/calendars/{calendar}/freebusy. This is the substance of the visible expansion in the window. Pure addition. No break to existing clients.

5. breakingfinding F5
   change type: enum_value_removed
   surface: webhook trigger schemas (4 DTOs)

   The trigger value ROUTING_FORM_FALLBACK_HIT was removed from UserWebhookOutputDto, EventTypeWebhookOutputDto, OAuthClientWebhookOutputDto, and CreateWebhookInputDto. Likely tied to the routing-forms namespace removal. Subscribers configured for that trigger now fail validation on create or update, and existing subscriptions stop receiving events.

6. spec hygienefinding C1
   change type: required_param_added (spec hygiene, not behavior change)
   surface: /v2/oauth-clients/{clientId}/webhooks/{webhookId} and /v2/event-types/{eventTypeId}/webhooks/{webhookId}

   Six findings flagged required path parameters being newly declared in the operation object. The actual HTTP behavior is unchanged: the path templates always required {clientId} and {eventTypeId}. The prior spec referenced those tokens in the URL but never declared them as parameters, which is malformed. The new spec correctly declares them. The diff engine flags this conservatively because it follows the spec at face value. Worth surfacing in attestation review even though no consumer break exists, because spec-hygiene fixes are real conformance signal.

7. spec hygienefinding C2
   change type: enum_value_removed (spec hygiene, not behavior change)
   surface: ScheduleAvailabilityInput_2024_06_11.days

   Seven weekday names were flagged as removed from an enum at the array level. The prior spec defined the enum at both the array level and the items level. Per JSON Schema, enum on an array constrains the array value itself, not its members, which is almost never the intent. The new spec keeps only the items-level enum. The actual constraint, that days are Monday through Sunday, is unchanged. Same teaching point as C1: the engine errs on the side of surfacing rather than silently accepting.

What this report is not

Not a defect claim. Not a security advisory. Not a judgment of the cal.com team's release process. The largest change in this window is the cal.diy refactor (PR #28903, merged 2026-04-15), which is plainly an intentional rewrite, not a slip. The merge gate's job is to make sure the shape of an intentional rewrite is visible in pre-merge review and that the version string downstream consumers see matches the change class.

The findings above do not say cal.com made a mistake. They say: here is what a downstream consumer pinned to the old shape will need to re-map. That visibility is the artifact.

The attestation artifact

A Delimit attestation is a bounded evidence record at a single commit pair. The same Delimit version run against the same two commits produces the same bytes; that is the replayable property. The attestation does not opine on whether a change should have shipped, only on what shipped and how the change-type taxonomy classifies it.

For the precise list of checks, the explicit out-of-scope list, and the reproducibility guarantee, see the attestation methodology v1. This report is the OpenAPI-diff surface of the same primitive that powers the merge gate for AI-written code.

Reproduce locally

Anyone can re-run the analysis above against the same two commits and verify the same diff comes out. The full command sequence:

# Install the CLI
npm install -g delimit-cli

# Clone the repo (full history; the spec was renamed)
git clone https://github.com/calcom/cal.com
cd cal.com

# Extract the two specs
git show 658e65be:docs/api-reference/v2/openapi.json > /tmp/old.json
git show HEAD:docs/api-reference/v2/openapi.json > /tmp/new.json

# Run the merge gate
delimit lint /tmp/old.json /tmp/new.json

If the bytes you get differ from the bytes in this report, that is itself a finding worth reporting; raise it on the Delimit repo and we will look.