Cal.diy API versions and provider routes

This reference maps every public Cal.diy capability to the provider method,
cal-api-version header, and relative path selected by the reviewed connector.
Use it to review connector changes, diagnose provider-contract drift, or trace a
governed AIP action to its fixed outbound request shape.

Applications invoke AIP capabilities. They do not construct or call these
provider URLs directly. Authentication, tenant and account routing, policy,
approval, idempotency, and durable settlement still apply before provider
dispatch.

Status and scope

| Item | Reviewed value |

| Connector source revision | 97be86e9efedf07ecf1783b03800f683f107fb04 |
| Pinned Cal.diy upstream revision | f00434927386c9ecdcbd7e6c5f82d22044a245bc |
| Public business operations | 81 |
| Fixed provider path templates | 53 |
| Provider API surface | Cal.diy /v2 routes selected by source |
| Arbitrary provider pass-through | Not supported |

The table describes implementation at the exact source revision. It does not
claim that these are the latest routes published by Cal.diy or that an arbitrary
deployment has been live-qualified against them.

Version selection

The connector sets cal-api-version for every outbound provider request. The
value is selected by operation; it is not a caller or deployment setting.

| Operation group | cal-api-version | Operations |

| Profile, bookings, calendars, conferencing, and user webhooks | 2024-08-13 | 55 |
| Event types and event-type webhooks | 2024-06-14 | 11 |
| Private links | 2024-04-15 | 4 |
| Slots and reservations | 2024-09-04 | 5 |
| Schedules | 2024-06-11 | 6 |
| Total | Five outbound values | 81 |

The fixed webhook payload version 2021-10-20 is separate. The connector puts
it in user-level and event-type webhook create or update bodies and expects the
same version at inbound webhook ingress. It is not a cal-api-version header.

The method distribution is 36 GET, 22 POST, 10 PATCH, 1 PUT, and 12
DELETE operations.

Fixed request construction

The connector constructs provider requests in a deterministic order:
1. select the method, path template, and API version from the operation enum;
2. join the relative path to the deployment-owned provider base URL;
3. fill named path segments from validated action input;
4. serialize only the operation's declared query fields;
5. remove path and query fields from a non-delete mutation body;
6. apply deployment-owned authentication and trusted request metadata;
7. dispatch through a client with redirects disabled and a 30-second timeout.

Action input cannot override the provider base URL, method, route template, API
version, authentication headers, or trusted audit headers.

Headers

| Header | Source | Presence |

| Authorization: Bearer … | Deployment secret | One authentication mode |
| x-cal-client-id, x-cal-secret-key | Deployment client credentials | Alternative authentication mode |
| accept: application/json | Connector | Every request |
| cal-api-version | Operation mapping | Every request |
| x-aip-action-id | Validated AIP action | Every request |
| idempotency-key | Governed action metadata | When supplied to the provider client |
| x-aip-principal-id | Trusted execution context | When request metadata is present |
| x-aip-tenant-id | Trusted execution context | When request metadata is present |
| x-aip-external-account-id | Trusted execution context | When request metadata is present |
| x-aip-trace-id | Trusted execution context | When a trace id is present |

Provider credentials never come from the action input. Redirects are not
followed, so credentials are not forwarded to a redirect target.

Path parameters

Each placeholder is filled from the same-named action field and percent-encoded
as one URL path segment. Missing fields fail before dispatch.

| Placeholder | Used by |

| {eventtypeid} | Event-type, private-link, and event-type-webhook item routes |
| {linkid} | Private-link item routes |
| {webhookid} | Event-type and user-level webhook item routes |
| {reservationuid} | Slot-reservation item routes |
| {bookinguid} | Booking lifecycle and booking-child routes |
| {seatuid} | Booking lookup by seat |
| {userid} | Booking reassignment to one user |
| {attendeeid} | Booking-attendee item routes |
| {calendar} | Provider check, disconnect, direct events, and direct free/busy |
| {connectionid} | Unified calendar-connection routes |
| {eventid} | Unified connection-event item routes |
| {eventuid} | Direct provider event item routes |
| {app} | Conferencing default, connect, and disconnect routes |
| {scheduleid} | Schedule item routes |

The capability input schemas own identifier types, enums, and required fields.
For example, the direct calendar event surface fixes {calendar} to google,
while provider check and disconnect accept a broader provider enum.

Query parameters

Only the operations below serialize action fields into the query string. All
other operations use path fields, an empty read input, or a JSON mutation body.

| Capability or group | Query fields |

| eventtype.list | username, eventSlug, usernames, orgSlug, orgId, sortCreatedAt |
| slot.list | start, end, eventTypeId, eventTypeSlug, username, teamSlug, organizationSlug, usernames, timeZone, duration, bookingUidToReschedule, format |
| booking.list | status, attendeeEmail, attendeeName, bookingUid, eventTypeIds, eventTypeId, teamsIds, teamId, afterStart, beforeEnd, afterCreatedAt, beforeCreatedAt, afterUpdatedAt, beforeUpdatedAt, sortStart, sortEnd, sortCreated, sortUpdatedAt, take, skip |
| booking.reference.list | type |
| eventtype.webhook.list, webhook.list | skip, take |
| calendar.busytime.list | timeZone, dateFrom, dateTo, calendarsToLoad |
| calendar.connection.event.list | from, to, timeZone, calendarId |
| Connection event get, create, update, and delete | calendarId |
| calendar.connection.freebusy.get | from, to, timeZone |
| calendar.event.list | from, to, timeZone, calendarId |
| calendar.freebusy.get | from, to, timeZone |
| calendar.selected.delete | integration, externalId, credentialId, delegationCredentialId |

Scalar arrays become repeated query keys. Arrays of objects use indexed bracket
notation; for example,
calendarsToLoad[0][credentialId]=42. Query nesting is rejected beyond eight
levels.

JSON bodies

GET and DELETE requests send no JSON body. Path and query fields are removed
from the action object before a POST, PATCH, or PUT body is sent. The
opaque webhooksecretref and internal compensation metadata are also removed.

For managed webhook create or update, the connector validates the destination,
resolves the opaque reference, and injects the provider secret afterward; a
raw secret never enters AIP action input.

This partition is significant for calendar.selected.delete: its supported
fields are query parameters because the connector sends no delete body.

Complete capability route map

The rows remain in the connector's source order. Paths are relative to the
configured provider base URL.

Profile

| Capability | Method | Version | Provider path |

| cap:caldiy:profile.get | GET | 2024-08-13 | /v2/me |
| cap:caldiy:profile.update | PATCH | 2024-08-13 | /v2/me |

Event types, private links, and event-type webhooks

| Capability | Method | Version | Provider path |

| cap:caldiy:eventtype.list | GET | 2024-06-14 | /v2/event-types |
| cap:caldiy:eventtype.get | GET | 2024-06-14 | /v2/event-types/{eventtypeid} |
| cap:caldiy:eventtype.create | POST | 2024-06-14 | /v2/event-types |
| cap:caldiy:eventtype.update | PATCH | 2024-06-14 | /v2/event-types/{eventtypeid} |
| cap:caldiy:eventtype.delete | DELETE | 2024-06-14 | /v2/event-types/{eventtypeid} |
| cap:caldiy:eventtype.privatelink.list | GET | 2024-04-15 | /v2/event-types/{eventtypeid}/private-links |
| cap:caldiy:eventtype.privatelink.create | POST | 2024-04-15 | /v2/event-types/{eventtypeid}/private-links |
| cap:caldiy:eventtype.privatelink.update | PATCH | 2024-04-15 | /v2/event-types/{eventtypeid}/private-links/{linkid} |
| cap:caldiy:eventtype.privatelink.delete | DELETE | 2024-04-15 | /v2/event-types/{eventtypeid}/private-links/{linkid} |
| cap:caldiy:eventtype.webhook.list | GET | 2024-06-14 | /v2/event-types/{eventtypeid}/webhooks |
| cap:caldiy:eventtype.webhook.get | GET | 2024-06-14 | /v2/event-types/{eventtypeid}/webhooks/{webhookid} |
| cap:caldiy:eventtype.webhook.create | POST | 2024-06-14 | /v2/event-types/{eventtypeid}/webhooks |
| cap:caldiy:eventtype.webhook.update | PATCH | 2024-06-14 | /v2/event-types/{eventtypeid}/webhooks/{webhookid} |
| cap:caldiy:eventtype.webhook.delete | DELETE | 2024-06-14 | /v2/event-types/{eventtypeid}/webhooks/{webhookid} |
| cap:caldiy:eventtype.webhook.deleteall | DELETE | 2024-06-14 | /v2/event-types/{eventtypeid}/webhooks |

Slots and reservations

| Capability | Method | Version | Provider path |

| cap:caldiy:slot.list | GET | 2024-09-04 | /v2/slots |
| cap:caldiy:slot.reservation.create | POST | 2024-09-04 | /v2/slots/reservations |
| cap:caldiy:slot.reservation.get | GET | 2024-09-04 | /v2/slots/reservations/{reservationuid} |
| cap:caldiy:slot.reservation.update | PATCH | 2024-09-04 | /v2/slots/reservations/{reservationuid} |
| cap:caldiy:slot.reservation.delete | DELETE | 2024-09-04 | /v2/slots/reservations/{reservationuid} |

Bookings

| Capability | Method | Version | Provider path |

| cap:caldiy:booking.list | GET | 2024-08-13 | /v2/bookings |
| cap:caldiy:booking.get | GET | 2024-08-13 | /v2/bookings/{bookinguid} |
| cap:caldiy:booking.getbyseat | GET | 2024-08-13 | /v2/bookings/by-seat/{seatuid} |
| cap:caldiy:booking.create | POST | 2024-08-13 | /v2/bookings |
| cap:caldiy:booking.reschedule | POST | 2024-08-13 | /v2/bookings/{bookinguid}/reschedule |
| cap:caldiy:booking.cancel | POST | 2024-08-13 | /v2/bookings/{bookinguid}/cancel |
| cap:caldiy:booking.confirm | POST | 2024-08-13 | /v2/bookings/{bookinguid}/confirm |
| cap:caldiy:booking.decline | POST | 2024-08-13 | /v2/bookings/{bookinguid}/decline |
| cap:caldiy:booking.markabsent | POST | 2024-08-13 | /v2/bookings/{bookinguid}/mark-absent |
| cap:caldiy:booking.reassign | POST | 2024-08-13 | /v2/bookings/{bookinguid}/reassign |
| cap:caldiy:booking.reassigntouser | POST | 2024-08-13 | /v2/bookings/{bookinguid}/reassign/{userid} |
| cap:caldiy:booking.location.update | PATCH | 2024-08-13 | /v2/bookings/{bookinguid}/location |
| cap:caldiy:booking.attendee.list | GET | 2024-08-13 | /v2/bookings/{bookinguid}/attendees |
| cap:caldiy:booking.attendee.get | GET | 2024-08-13 | /v2/bookings/{bookinguid}/attendees/{attendeeid} |
| cap:caldiy:booking.attendee.add | POST | 2024-08-13 | /v2/bookings/{bookinguid}/attendees |
| cap:caldiy:booking.attendee.delete | DELETE | 2024-08-13 | /v2/bookings/{bookinguid}/attendees/{attendeeid} |
| cap:caldiy:booking.guest.add | POST | 2024-08-13 | /v2/bookings/{bookinguid}/guests |
| cap:caldiy:booking.calendarlinks.get | GET | 2024-08-13 | /v2/bookings/{bookinguid}/calendar-links |
| cap:caldiy:booking.reference.list | GET | 2024-08-13 | /v2/bookings/{bookinguid}/references |
| cap:caldiy:booking.recording.list | GET | 2024-08-13 | /v2/bookings/{bookinguid}/recordings |
| cap:caldiy:booking.transcript.list | GET | 2024-08-13 | /v2/bookings/{bookinguid}/transcripts |
| cap:caldiy:booking.conferencingsession.list | GET | 2024-08-13 | /v2/bookings/{bookinguid}/conferencing-sessions |

Calendars and free/busy

| Capability | Method | Version | Provider path |

| cap:caldiy:calendar.list | GET | 2024-08-13 | /v2/calendars |
| cap:caldiy:calendar.provider.check | GET | 2024-08-13 | /v2/calendars/{calendar}/check |
| cap:caldiy:calendar.disconnect | POST | 2024-08-13 | /v2/calendars/{calendar}/disconnect |
| cap:caldiy:calendar.icsfeed.check | GET | 2024-08-13 | /v2/calendars/ics-feed/check |
| cap:caldiy:calendar.busytime.list | GET | 2024-08-13 | /v2/calendars/busy-times |
| cap:caldiy:calendar.connection.list | GET | 2024-08-13 | /v2/calendars/connections |
| cap:caldiy:calendar.connection.event.list | GET | 2024-08-13 | /v2/calendars/connections/{connectionid}/events |
| cap:caldiy:calendar.connection.event.get | GET | 2024-08-13 | /v2/calendars/connections/{connectionid}/events/{eventid} |
| cap:caldiy:calendar.connection.event.create | POST | 2024-08-13 | /v2/calendars/connections/{connectionid}/events |
| cap:caldiy:calendar.connection.event.update | PATCH | 2024-08-13 | /v2/calendars/connections/{connectionid}/events/{eventid} |
| cap:caldiy:calendar.connection.event.delete | DELETE | 2024-08-13 | /v2/calendars/connections/{connectionid}/events/{eventid} |
| cap:caldiy:calendar.connection.freebusy.get | GET | 2024-08-13 | /v2/calendars/connections/{connectionid}/freebusy |
| cap:caldiy:calendar.event.list | GET | 2024-08-13 | /v2/calendars/{calendar}/events |
| cap:caldiy:calendar.event.get | GET | 2024-08-13 | /v2/calendars/{calendar}/events/{eventuid} |
| cap:caldiy:calendar.event.create | POST | 2024-08-13 | /v2/calendars/{calendar}/events |
| cap:caldiy:calendar.event.update | PATCH | 2024-08-13 | /v2/calendars/{calendar}/events/{eventuid} |
| cap:caldiy:calendar.event.delete | DELETE | 2024-08-13 | /v2/calendars/{calendar}/events/{eventuid} |
| cap:caldiy:calendar.freebusy.get | GET | 2024-08-13 | /v2/calendars/{calendar}/freebusy |
| cap:caldiy:calendar.destination.update | PUT | 2024-08-13 | /v2/destination-calendars |
| cap:caldiy:calendar.selected.add | POST | 2024-08-13 | /v2/selected-calendars |
| cap:caldiy:calendar.selected.delete | DELETE | 2024-08-13 | /v2/selected-calendars |

Conferencing

| Capability | Method | Version | Provider path |

| cap:caldiy:conferencing.list | GET | 2024-08-13 | /v2/conferencing |
| cap:caldiy:conferencing.default.get | GET | 2024-08-13 | /v2/conferencing/default |
| cap:caldiy:conferencing.default.set | POST | 2024-08-13 | /v2/conferencing/{app}/default |
| cap:caldiy:conferencing.connect | POST | 2024-08-13 | /v2/conferencing/{app}/connect |
| cap:caldiy:conferencing.disconnect | DELETE | 2024-08-13 | /v2/conferencing/{app}/disconnect |

Schedules

| Capability | Method | Version | Provider path |

| cap:caldiy:schedule.list | GET | 2024-06-11 | /v2/schedules |
| cap:caldiy:schedule.default.get | GET | 2024-06-11 | /v2/schedules/default |
| cap:caldiy:schedule.get | GET | 2024-06-11 | /v2/schedules/{scheduleid} |
| cap:caldiy:schedule.create | POST | 2024-06-11 | /v2/schedules |
| cap:caldiy:schedule.update | PATCH | 2024-06-11 | /v2/schedules/{scheduleid} |
| cap:caldiy:schedule.delete | DELETE | 2024-06-11 | /v2/schedules/{scheduleid} |

User webhooks

| Capability | Method | Version | Provider path |

| cap:caldiy:webhook.list | GET | 2024-08-13 | /v2/webhooks |
| cap:caldiy:webhook.get | GET | 2024-08-13 | /v2/webhooks/{webhookid} |
| cap:caldiy:webhook.create | POST | 2024-08-13 | /v2/webhooks |
| cap:caldiy:webhook.update | PATCH | 2024-08-13 | /v2/webhooks/{webhookid} |
| cap:caldiy:webhook.delete | DELETE | 2024-08-13 | /v2/webhooks/{webhookid} |

Diagnose route or version drift

| Observation | Interpretation | Safe response |

| Capability is absent from the admitted catalog | The current deployment did not admit this contract | Stop; do not derive a provider call from this table |
| Provider returns 404 or 405 | Route, method, account scope, or upstream behavior may differ | Preserve request evidence and compare exact revisions before changing source |
| Provider rejects cal-api-version | The pinned version may no longer match that provider deployment | Treat it as contract drift; do not override the header at runtime |
| Provider returns a redirect | The hardened client does not follow it | Verify the configured base URL and reviewed route mapping |
| Connector reports invalid action | A path, query, or body field failed the capability schema | Correct the AIP input; do not call the provider directly |
| Mutation outcome is uncertain | Dispatch may have crossed the provider boundary | Reconcile the original action and idempotency identity |
| Response exceeds the configured bound | Provider output was not accepted into the connector | Preserve status and request id, then review the response contract and bound |

A provider error alone does not prove that this table is wrong. First compare
the admitted catalog revision, connector artifact digest, configured upstream,
capability input, provider request id, and durable action state.

Review a route-map change

A connector change that alters any row should update and review one coherent
set of artifacts:
1. operation suffix, method, path template, path fields, query fields, and API
   version in source;
2. the input schema and path/query/body partition for the same capability;
3. route, version-header, encoding, and secret-boundary contract tests;
4. the generated capability snapshot and its source provenance;
5. this route map and the affected capability reference;
6. conformance and provider qualification evidence for the exact artifact.

Do not ship a route-only edit that leaves schemas, tests, generated metadata,
or evidence pinned to a different request shape.

Security and evidence boundaries
• Public actions select a known capability, not an arbitrary provider route.
• Deployment configuration owns the provider origin and authentication mode.
• Path values are encoded as individual URL segments.
• Only enumerated query fields are serialized, with bounded nesting.
• Provider credentials and raw webhook secrets are excluded from action input.
• Redirects are disabled and the provider exchange has a fixed timeout.
• A source-derived row proves implementation intent, not live provider support.
• Provider-route absence is not permission to use an operator-only endpoint.

Related documentation
• Cal.diy capability index (../capabilities/README.md)
• Generated capability snapshot (../assets/capabilities.json)
• Cal.diy configuration (configuration.md)
• Connector contract (../../../spec/connector-contract.md)
• Error reference (../../../reference/errors.md)