{
  "schemaVersion": "1.0",
  "title": "Cal.diy API versions and provider routes",
  "description": "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 gover",
  "canonical": "https://getaip.org/docs/connectors/cal-diy/reference/api-versions-and-provider-routes",
  "route": "/docs/connectors/cal-diy/reference/api-versions-and-provider-routes",
  "source": "docs/connectors/cal-diy/reference/api-versions-and-provider-routes.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/cal-diy/reference/api-versions-and-provider-routes.md",
    "txt": "/docs/download/connectors/cal-diy/reference/api-versions-and-provider-routes.txt",
    "json": "/docs/download/connectors/cal-diy/reference/api-versions-and-provider-routes.json",
    "pdf": "/docs/download/connectors/cal-diy/reference/api-versions-and-provider-routes.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Cal.diy API versions and provider routes\ndescription: Look up the fixed provider method, version header, and route behind each public capability\nkind: reference\naudience: connector-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: cal-diy\n---\n\n# Cal.diy API versions and provider routes\n\nThis reference maps every public Cal.diy capability to the provider method,\n`cal-api-version` header, and relative path selected by the reviewed connector.\nUse it to review connector changes, diagnose provider-contract drift, or trace a\ngoverned AIP action to its fixed outbound request shape.\n\nApplications invoke AIP capabilities. They do not construct or call these\nprovider URLs directly. Authentication, tenant and account routing, policy,\napproval, idempotency, and durable settlement still apply before provider\ndispatch.\n\n## Status and scope\n\n| Item | Reviewed value |\n|---|---|\n| Connector source revision | `97be86e9efedf07ecf1783b03800f683f107fb04` |\n| Pinned Cal.diy upstream revision | `f00434927386c9ecdcbd7e6c5f82d22044a245bc` |\n| Public business operations | `81` |\n| Fixed provider path templates | `53` |\n| Provider API surface | Cal.diy `/v2` routes selected by source |\n| Arbitrary provider pass-through | Not supported |\n\nThe table describes implementation at the exact source revision. It does not\nclaim that these are the latest routes published by Cal.diy or that an arbitrary\ndeployment has been live-qualified against them.\n\n## Version selection\n\nThe connector sets `cal-api-version` for every outbound provider request. The\nvalue is selected by operation; it is not a caller or deployment setting.\n\n| Operation group | `cal-api-version` | Operations |\n|---|---|---:|\n| Profile, bookings, calendars, conferencing, and user webhooks | `2024-08-13` | 55 |\n| Event types and event-type webhooks | `2024-06-14` | 11 |\n| Private links | `2024-04-15` | 4 |\n| Slots and reservations | `2024-09-04` | 5 |\n| Schedules | `2024-06-11` | 6 |\n| **Total** | Five outbound values | **81** |\n\nThe fixed webhook payload version `2021-10-20` is separate. The connector puts\nit in user-level and event-type webhook create or update bodies and expects the\nsame version at inbound webhook ingress. It is not a `cal-api-version` header.\n\nThe method distribution is 36 `GET`, 22 `POST`, 10 `PATCH`, 1 `PUT`, and 12\n`DELETE` operations.\n\n## Fixed request construction\n\nThe connector constructs provider requests in a deterministic order:\n\n1. select the method, path template, and API version from the operation enum;\n2. join the relative path to the deployment-owned provider base URL;\n3. fill named path segments from validated action input;\n4. serialize only the operation's declared query fields;\n5. remove path and query fields from a non-delete mutation body;\n6. apply deployment-owned authentication and trusted request metadata;\n7. dispatch through a client with redirects disabled and a 30-second timeout.\n\nAction input cannot override the provider base URL, method, route template, API\nversion, authentication headers, or trusted audit headers.\n\n### Headers\n\n| Header | Source | Presence |\n|---|---|---|\n| `Authorization: Bearer …` | Deployment secret | One authentication mode |\n| `x-cal-client-id`, `x-cal-secret-key` | Deployment client credentials | Alternative authentication mode |\n| `accept: application/json` | Connector | Every request |\n| `cal-api-version` | Operation mapping | Every request |\n| `x-aip-action-id` | Validated AIP action | Every request |\n| `idempotency-key` | Governed action metadata | When supplied to the provider client |\n| `x-aip-principal-id` | Trusted execution context | When request metadata is present |\n| `x-aip-tenant-id` | Trusted execution context | When request metadata is present |\n| `x-aip-external-account-id` | Trusted execution context | When request metadata is present |\n| `x-aip-trace-id` | Trusted execution context | When a trace id is present |\n\nProvider credentials never come from the action input. Redirects are not\nfollowed, so credentials are not forwarded to a redirect target.\n\n### Path parameters\n\nEach placeholder is filled from the same-named action field and percent-encoded\nas one URL path segment. Missing fields fail before dispatch.\n\n| Placeholder | Used by |\n|---|---|\n| `{event_type_id}` | Event-type, private-link, and event-type-webhook item routes |\n| `{link_id}` | Private-link item routes |\n| `{webhook_id}` | Event-type and user-level webhook item routes |\n| `{reservation_uid}` | Slot-reservation item routes |\n| `{booking_uid}` | Booking lifecycle and booking-child routes |\n| `{seat_uid}` | Booking lookup by seat |\n| `{user_id}` | Booking reassignment to one user |\n| `{attendee_id}` | Booking-attendee item routes |\n| `{calendar}` | Provider check, disconnect, direct events, and direct free/busy |\n| `{connection_id}` | Unified calendar-connection routes |\n| `{event_id}` | Unified connection-event item routes |\n| `{event_uid}` | Direct provider event item routes |\n| `{app}` | Conferencing default, connect, and disconnect routes |\n| `{schedule_id}` | Schedule item routes |\n\nThe capability input schemas own identifier types, enums, and required fields.\nFor example, the direct calendar event surface fixes `{calendar}` to `google`,\nwhile provider check and disconnect accept a broader provider enum.\n\n### Query parameters\n\nOnly the operations below serialize action fields into the query string. All\nother operations use path fields, an empty read input, or a JSON mutation body.\n\n| Capability or group | Query fields |\n|---|---|\n| `event_type.list` | `username`, `eventSlug`, `usernames`, `orgSlug`, `orgId`, `sortCreatedAt` |\n| `slot.list` | `start`, `end`, `eventTypeId`, `eventTypeSlug`, `username`, `teamSlug`, `organizationSlug`, `usernames`, `timeZone`, `duration`, `bookingUidToReschedule`, `format` |\n| `booking.list` | `status`, `attendeeEmail`, `attendeeName`, `bookingUid`, `eventTypeIds`, `eventTypeId`, `teamsIds`, `teamId`, `afterStart`, `beforeEnd`, `afterCreatedAt`, `beforeCreatedAt`, `afterUpdatedAt`, `beforeUpdatedAt`, `sortStart`, `sortEnd`, `sortCreated`, `sortUpdatedAt`, `take`, `skip` |\n| `booking.reference.list` | `type` |\n| `event_type.webhook.list`, `webhook.list` | `skip`, `take` |\n| `calendar.busy_time.list` | `timeZone`, `dateFrom`, `dateTo`, `calendarsToLoad` |\n| `calendar.connection.event.list` | `from`, `to`, `timeZone`, `calendarId` |\n| Connection event get, create, update, and delete | `calendarId` |\n| `calendar.connection.free_busy.get` | `from`, `to`, `timeZone` |\n| `calendar.event.list` | `from`, `to`, `timeZone`, `calendarId` |\n| `calendar.free_busy.get` | `from`, `to`, `timeZone` |\n| `calendar.selected.delete` | `integration`, `externalId`, `credentialId`, `delegationCredentialId` |\n\nScalar arrays become repeated query keys. Arrays of objects use indexed bracket\nnotation; for example,\n`calendarsToLoad[0][credentialId]=42`. Query nesting is rejected beyond eight\nlevels.\n\n### JSON bodies\n\n`GET` and `DELETE` requests send no JSON body. Path and query fields are removed\nfrom the action object before a `POST`, `PATCH`, or `PUT` body is sent. The\nopaque `webhook_secret_ref` and internal compensation metadata are also removed.\n\nFor managed webhook create or update, the connector validates the destination,\nresolves the opaque reference, and injects the provider `secret` afterward; a\nraw secret never enters AIP action input.\n\nThis partition is significant for `calendar.selected.delete`: its supported\nfields are query parameters because the connector sends no delete body.\n\n## Complete capability route map\n\nThe rows remain in the connector's source order. Paths are relative to the\nconfigured provider base URL.\n\n### Profile\n\n| Capability | Method | Version | Provider path |\n|---|---|---|---|\n| `cap:cal_diy:profile.get` | `GET` | `2024-08-13` | `/v2/me` |\n| `cap:cal_diy:profile.update` | `PATCH` | `2024-08-13` | `/v2/me` |\n\n### Event types, private links, and event-type webhooks\n\n| Capability | Method | Version | Provider path |\n|---|---|---|---|\n| `cap:cal_diy:event_type.list` | `GET` | `2024-06-14` | `/v2/event-types` |\n| `cap:cal_diy:event_type.get` | `GET` | `2024-06-14` | `/v2/event-types/{event_type_id}` |\n| `cap:cal_diy:event_type.create` | `POST` | `2024-06-14` | `/v2/event-types` |\n| `cap:cal_diy:event_type.update` | `PATCH` | `2024-06-14` | `/v2/event-types/{event_type_id}` |\n| `cap:cal_diy:event_type.delete` | `DELETE` | `2024-06-14` | `/v2/event-types/{event_type_id}` |\n| `cap:cal_diy:event_type.private_link.list` | `GET` | `2024-04-15` | `/v2/event-types/{event_type_id}/private-links` |\n| `cap:cal_diy:event_type.private_link.create` | `POST` | `2024-04-15` | `/v2/event-types/{event_type_id}/private-links` |\n| `cap:cal_diy:event_type.private_link.update` | `PATCH` | `2024-04-15` | `/v2/event-types/{event_type_id}/private-links/{link_id}` |\n| `cap:cal_diy:event_type.private_link.delete` | `DELETE` | `2024-04-15` | `/v2/event-types/{event_type_id}/private-links/{link_id}` |\n| `cap:cal_diy:event_type.webhook.list` | `GET` | `2024-06-14` | `/v2/event-types/{event_type_id}/webhooks` |\n| `cap:cal_diy:event_type.webhook.get` | `GET` | `2024-06-14` | `/v2/event-types/{event_type_id}/webhooks/{webhook_id}` |\n| `cap:cal_diy:event_type.webhook.create` | `POST` | `2024-06-14` | `/v2/event-types/{event_type_id}/webhooks` |\n| `cap:cal_diy:event_type.webhook.update` | `PATCH` | `2024-06-14` | `/v2/event-types/{event_type_id}/webhooks/{webhook_id}` |\n| `cap:cal_diy:event_type.webhook.delete` | `DELETE` | `2024-06-14` | `/v2/event-types/{event_type_id}/webhooks/{webhook_id}` |\n| `cap:cal_diy:event_type.webhook.delete_all` | `DELETE` | `2024-06-14` | `/v2/event-types/{event_type_id}/webhooks` |\n\n### Slots and reservations\n\n| Capability | Method | Version | Provider path |\n|---|---|---|---|\n| `cap:cal_diy:slot.list` | `GET` | `2024-09-04` | `/v2/slots` |\n| `cap:cal_diy:slot.reservation.create` | `POST` | `2024-09-04` | `/v2/slots/reservations` |\n| `cap:cal_diy:slot.reservation.get` | `GET` | `2024-09-04` | `/v2/slots/reservations/{reservation_uid}` |\n| `cap:cal_diy:slot.reservation.update` | `PATCH` | `2024-09-04` | `/v2/slots/reservations/{reservation_uid}` |\n| `cap:cal_diy:slot.reservation.delete` | `DELETE` | `2024-09-04` | `/v2/slots/reservations/{reservation_uid}` |\n\n### Bookings\n\n| Capability | Method | Version | Provider path |\n|---|---|---|---|\n| `cap:cal_diy:booking.list` | `GET` | `2024-08-13` | `/v2/bookings` |\n| `cap:cal_diy:booking.get` | `GET` | `2024-08-13` | `/v2/bookings/{booking_uid}` |\n| `cap:cal_diy:booking.get_by_seat` | `GET` | `2024-08-13` | `/v2/bookings/by-seat/{seat_uid}` |\n| `cap:cal_diy:booking.create` | `POST` | `2024-08-13` | `/v2/bookings` |\n| `cap:cal_diy:booking.reschedule` | `POST` | `2024-08-13` | `/v2/bookings/{booking_uid}/reschedule` |\n| `cap:cal_diy:booking.cancel` | `POST` | `2024-08-13` | `/v2/bookings/{booking_uid}/cancel` |\n| `cap:cal_diy:booking.confirm` | `POST` | `2024-08-13` | `/v2/bookings/{booking_uid}/confirm` |\n| `cap:cal_diy:booking.decline` | `POST` | `2024-08-13` | `/v2/bookings/{booking_uid}/decline` |\n| `cap:cal_diy:booking.mark_absent` | `POST` | `2024-08-13` | `/v2/bookings/{booking_uid}/mark-absent` |\n| `cap:cal_diy:booking.reassign` | `POST` | `2024-08-13` | `/v2/bookings/{booking_uid}/reassign` |\n| `cap:cal_diy:booking.reassign_to_user` | `POST` | `2024-08-13` | `/v2/bookings/{booking_uid}/reassign/{user_id}` |\n| `cap:cal_diy:booking.location.update` | `PATCH` | `2024-08-13` | `/v2/bookings/{booking_uid}/location` |\n| `cap:cal_diy:booking.attendee.list` | `GET` | `2024-08-13` | `/v2/bookings/{booking_uid}/attendees` |\n| `cap:cal_diy:booking.attendee.get` | `GET` | `2024-08-13` | `/v2/bookings/{booking_uid}/attendees/{attendee_id}` |\n| `cap:cal_diy:booking.attendee.add` | `POST` | `2024-08-13` | `/v2/bookings/{booking_uid}/attendees` |\n| `cap:cal_diy:booking.attendee.delete` | `DELETE` | `2024-08-13` | `/v2/bookings/{booking_uid}/attendees/{attendee_id}` |\n| `cap:cal_diy:booking.guest.add` | `POST` | `2024-08-13` | `/v2/bookings/{booking_uid}/guests` |\n| `cap:cal_diy:booking.calendar_links.get` | `GET` | `2024-08-13` | `/v2/bookings/{booking_uid}/calendar-links` |\n| `cap:cal_diy:booking.reference.list` | `GET` | `2024-08-13` | `/v2/bookings/{booking_uid}/references` |\n| `cap:cal_diy:booking.recording.list` | `GET` | `2024-08-13` | `/v2/bookings/{booking_uid}/recordings` |\n| `cap:cal_diy:booking.transcript.list` | `GET` | `2024-08-13` | `/v2/bookings/{booking_uid}/transcripts` |\n| `cap:cal_diy:booking.conferencing_session.list` | `GET` | `2024-08-13` | `/v2/bookings/{booking_uid}/conferencing-sessions` |\n\n### Calendars and free/busy\n\n| Capability | Method | Version | Provider path |\n|---|---|---|---|\n| `cap:cal_diy:calendar.list` | `GET` | `2024-08-13` | `/v2/calendars` |\n| `cap:cal_diy:calendar.provider.check` | `GET` | `2024-08-13` | `/v2/calendars/{calendar}/check` |\n| `cap:cal_diy:calendar.disconnect` | `POST` | `2024-08-13` | `/v2/calendars/{calendar}/disconnect` |\n| `cap:cal_diy:calendar.ics_feed.check` | `GET` | `2024-08-13` | `/v2/calendars/ics-feed/check` |\n| `cap:cal_diy:calendar.busy_time.list` | `GET` | `2024-08-13` | `/v2/calendars/busy-times` |\n| `cap:cal_diy:calendar.connection.list` | `GET` | `2024-08-13` | `/v2/calendars/connections` |\n| `cap:cal_diy:calendar.connection.event.list` | `GET` | `2024-08-13` | `/v2/calendars/connections/{connection_id}/events` |\n| `cap:cal_diy:calendar.connection.event.get` | `GET` | `2024-08-13` | `/v2/calendars/connections/{connection_id}/events/{event_id}` |\n| `cap:cal_diy:calendar.connection.event.create` | `POST` | `2024-08-13` | `/v2/calendars/connections/{connection_id}/events` |\n| `cap:cal_diy:calendar.connection.event.update` | `PATCH` | `2024-08-13` | `/v2/calendars/connections/{connection_id}/events/{event_id}` |\n| `cap:cal_diy:calendar.connection.event.delete` | `DELETE` | `2024-08-13` | `/v2/calendars/connections/{connection_id}/events/{event_id}` |\n| `cap:cal_diy:calendar.connection.free_busy.get` | `GET` | `2024-08-13` | `/v2/calendars/connections/{connection_id}/freebusy` |\n| `cap:cal_diy:calendar.event.list` | `GET` | `2024-08-13` | `/v2/calendars/{calendar}/events` |\n| `cap:cal_diy:calendar.event.get` | `GET` | `2024-08-13` | `/v2/calendars/{calendar}/events/{event_uid}` |\n| `cap:cal_diy:calendar.event.create` | `POST` | `2024-08-13` | `/v2/calendars/{calendar}/events` |\n| `cap:cal_diy:calendar.event.update` | `PATCH` | `2024-08-13` | `/v2/calendars/{calendar}/events/{event_uid}` |\n| `cap:cal_diy:calendar.event.delete` | `DELETE` | `2024-08-13` | `/v2/calendars/{calendar}/events/{event_uid}` |\n| `cap:cal_diy:calendar.free_busy.get` | `GET` | `2024-08-13` | `/v2/calendars/{calendar}/freebusy` |\n| `cap:cal_diy:calendar.destination.update` | `PUT` | `2024-08-13` | `/v2/destination-calendars` |\n| `cap:cal_diy:calendar.selected.add` | `POST` | `2024-08-13` | `/v2/selected-calendars` |\n| `cap:cal_diy:calendar.selected.delete` | `DELETE` | `2024-08-13` | `/v2/selected-calendars` |\n\n### Conferencing\n\n| Capability | Method | Version | Provider path |\n|---|---|---|---|\n| `cap:cal_diy:conferencing.list` | `GET` | `2024-08-13` | `/v2/conferencing` |\n| `cap:cal_diy:conferencing.default.get` | `GET` | `2024-08-13` | `/v2/conferencing/default` |\n| `cap:cal_diy:conferencing.default.set` | `POST` | `2024-08-13` | `/v2/conferencing/{app}/default` |\n| `cap:cal_diy:conferencing.connect` | `POST` | `2024-08-13` | `/v2/conferencing/{app}/connect` |\n| `cap:cal_diy:conferencing.disconnect` | `DELETE` | `2024-08-13` | `/v2/conferencing/{app}/disconnect` |\n\n### Schedules\n\n| Capability | Method | Version | Provider path |\n|---|---|---|---|\n| `cap:cal_diy:schedule.list` | `GET` | `2024-06-11` | `/v2/schedules` |\n| `cap:cal_diy:schedule.default.get` | `GET` | `2024-06-11` | `/v2/schedules/default` |\n| `cap:cal_diy:schedule.get` | `GET` | `2024-06-11` | `/v2/schedules/{schedule_id}` |\n| `cap:cal_diy:schedule.create` | `POST` | `2024-06-11` | `/v2/schedules` |\n| `cap:cal_diy:schedule.update` | `PATCH` | `2024-06-11` | `/v2/schedules/{schedule_id}` |\n| `cap:cal_diy:schedule.delete` | `DELETE` | `2024-06-11` | `/v2/schedules/{schedule_id}` |\n\n### User webhooks\n\n| Capability | Method | Version | Provider path |\n|---|---|---|---|\n| `cap:cal_diy:webhook.list` | `GET` | `2024-08-13` | `/v2/webhooks` |\n| `cap:cal_diy:webhook.get` | `GET` | `2024-08-13` | `/v2/webhooks/{webhook_id}` |\n| `cap:cal_diy:webhook.create` | `POST` | `2024-08-13` | `/v2/webhooks` |\n| `cap:cal_diy:webhook.update` | `PATCH` | `2024-08-13` | `/v2/webhooks/{webhook_id}` |\n| `cap:cal_diy:webhook.delete` | `DELETE` | `2024-08-13` | `/v2/webhooks/{webhook_id}` |\n\n## Diagnose route or version drift\n\n| Observation | Interpretation | Safe response |\n|---|---|---|\n| 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 |\n| Provider returns `404` or `405` | Route, method, account scope, or upstream behavior may differ | Preserve request evidence and compare exact revisions before changing source |\n| 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 |\n| Provider returns a redirect | The hardened client does not follow it | Verify the configured base URL and reviewed route mapping |\n| Connector reports invalid action | A path, query, or body field failed the capability schema | Correct the AIP input; do not call the provider directly |\n| Mutation outcome is uncertain | Dispatch may have crossed the provider boundary | Reconcile the original action and idempotency identity |\n| 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 |\n\nA provider error alone does not prove that this table is wrong. First compare\nthe admitted catalog revision, connector artifact digest, configured upstream,\ncapability input, provider request id, and durable action state.\n\n## Review a route-map change\n\nA connector change that alters any row should update and review one coherent\nset of artifacts:\n\n1. operation suffix, method, path template, path fields, query fields, and API\n   version in source;\n2. the input schema and path/query/body partition for the same capability;\n3. route, version-header, encoding, and secret-boundary contract tests;\n4. the generated capability snapshot and its source provenance;\n5. this route map and the affected capability reference;\n6. conformance and provider qualification evidence for the exact artifact.\n\nDo not ship a route-only edit that leaves schemas, tests, generated metadata,\nor evidence pinned to a different request shape.\n\n## Security and evidence boundaries\n\n- Public actions select a known capability, not an arbitrary provider route.\n- Deployment configuration owns the provider origin and authentication mode.\n- Path values are encoded as individual URL segments.\n- Only enumerated query fields are serialized, with bounded nesting.\n- Provider credentials and raw webhook secrets are excluded from action input.\n- Redirects are disabled and the provider exchange has a fixed timeout.\n- A source-derived row proves implementation intent, not live provider support.\n- Provider-route absence is not permission to use an operator-only endpoint.\n\n## Related documentation\n\n- [Cal.diy capability index](../capabilities/README.md)\n- [Generated capability snapshot](../assets/capabilities.json)\n- [Cal.diy configuration](configuration.md)\n- [Connector contract](../../../spec/connector-contract.md)\n- [Error reference](../../../reference/errors.md)\n",
    "text": "Cal.diy API versions and provider routes\n\nThis reference maps every public Cal.diy capability to the provider method,\ncal-api-version header, and relative path selected by the reviewed connector.\nUse it to review connector changes, diagnose provider-contract drift, or trace a\ngoverned AIP action to its fixed outbound request shape.\n\nApplications invoke AIP capabilities. They do not construct or call these\nprovider URLs directly. Authentication, tenant and account routing, policy,\napproval, idempotency, and durable settlement still apply before provider\ndispatch.\n\nStatus and scope\n\n| Item | Reviewed value |\n\n| Connector source revision | 97be86e9efedf07ecf1783b03800f683f107fb04 |\n| Pinned Cal.diy upstream revision | f00434927386c9ecdcbd7e6c5f82d22044a245bc |\n| Public business operations | 81 |\n| Fixed provider path templates | 53 |\n| Provider API surface | Cal.diy /v2 routes selected by source |\n| Arbitrary provider pass-through | Not supported |\n\nThe table describes implementation at the exact source revision. It does not\nclaim that these are the latest routes published by Cal.diy or that an arbitrary\ndeployment has been live-qualified against them.\n\nVersion selection\n\nThe connector sets cal-api-version for every outbound provider request. The\nvalue is selected by operation; it is not a caller or deployment setting.\n\n| Operation group | cal-api-version | Operations |\n\n| Profile, bookings, calendars, conferencing, and user webhooks | 2024-08-13 | 55 |\n| Event types and event-type webhooks | 2024-06-14 | 11 |\n| Private links | 2024-04-15 | 4 |\n| Slots and reservations | 2024-09-04 | 5 |\n| Schedules | 2024-06-11 | 6 |\n| Total | Five outbound values | 81 |\n\nThe fixed webhook payload version 2021-10-20 is separate. The connector puts\nit in user-level and event-type webhook create or update bodies and expects the\nsame version at inbound webhook ingress. It is not a cal-api-version header.\n\nThe method distribution is 36 GET, 22 POST, 10 PATCH, 1 PUT, and 12\nDELETE operations.\n\nFixed request construction\n\nThe connector constructs provider requests in a deterministic order:\n1. select the method, path template, and API version from the operation enum;\n2. join the relative path to the deployment-owned provider base URL;\n3. fill named path segments from validated action input;\n4. serialize only the operation's declared query fields;\n5. remove path and query fields from a non-delete mutation body;\n6. apply deployment-owned authentication and trusted request metadata;\n7. dispatch through a client with redirects disabled and a 30-second timeout.\n\nAction input cannot override the provider base URL, method, route template, API\nversion, authentication headers, or trusted audit headers.\n\nHeaders\n\n| Header | Source | Presence |\n\n| Authorization: Bearer … | Deployment secret | One authentication mode |\n| x-cal-client-id, x-cal-secret-key | Deployment client credentials | Alternative authentication mode |\n| accept: application/json | Connector | Every request |\n| cal-api-version | Operation mapping | Every request |\n| x-aip-action-id | Validated AIP action | Every request |\n| idempotency-key | Governed action metadata | When supplied to the provider client |\n| x-aip-principal-id | Trusted execution context | When request metadata is present |\n| x-aip-tenant-id | Trusted execution context | When request metadata is present |\n| x-aip-external-account-id | Trusted execution context | When request metadata is present |\n| x-aip-trace-id | Trusted execution context | When a trace id is present |\n\nProvider credentials never come from the action input. Redirects are not\nfollowed, so credentials are not forwarded to a redirect target.\n\nPath parameters\n\nEach placeholder is filled from the same-named action field and percent-encoded\nas one URL path segment. Missing fields fail before dispatch.\n\n| Placeholder | Used by |\n\n| {eventtypeid} | Event-type, private-link, and event-type-webhook item routes |\n| {linkid} | Private-link item routes |\n| {webhookid} | Event-type and user-level webhook item routes |\n| {reservationuid} | Slot-reservation item routes |\n| {bookinguid} | Booking lifecycle and booking-child routes |\n| {seatuid} | Booking lookup by seat |\n| {userid} | Booking reassignment to one user |\n| {attendeeid} | Booking-attendee item routes |\n| {calendar} | Provider check, disconnect, direct events, and direct free/busy |\n| {connectionid} | Unified calendar-connection routes |\n| {eventid} | Unified connection-event item routes |\n| {eventuid} | Direct provider event item routes |\n| {app} | Conferencing default, connect, and disconnect routes |\n| {scheduleid} | Schedule item routes |\n\nThe capability input schemas own identifier types, enums, and required fields.\nFor example, the direct calendar event surface fixes {calendar} to google,\nwhile provider check and disconnect accept a broader provider enum.\n\nQuery parameters\n\nOnly the operations below serialize action fields into the query string. All\nother operations use path fields, an empty read input, or a JSON mutation body.\n\n| Capability or group | Query fields |\n\n| eventtype.list | username, eventSlug, usernames, orgSlug, orgId, sortCreatedAt |\n| slot.list | start, end, eventTypeId, eventTypeSlug, username, teamSlug, organizationSlug, usernames, timeZone, duration, bookingUidToReschedule, format |\n| booking.list | status, attendeeEmail, attendeeName, bookingUid, eventTypeIds, eventTypeId, teamsIds, teamId, afterStart, beforeEnd, afterCreatedAt, beforeCreatedAt, afterUpdatedAt, beforeUpdatedAt, sortStart, sortEnd, sortCreated, sortUpdatedAt, take, skip |\n| booking.reference.list | type |\n| eventtype.webhook.list, webhook.list | skip, take |\n| calendar.busytime.list | timeZone, dateFrom, dateTo, calendarsToLoad |\n| calendar.connection.event.list | from, to, timeZone, calendarId |\n| Connection event get, create, update, and delete | calendarId |\n| calendar.connection.freebusy.get | from, to, timeZone |\n| calendar.event.list | from, to, timeZone, calendarId |\n| calendar.freebusy.get | from, to, timeZone |\n| calendar.selected.delete | integration, externalId, credentialId, delegationCredentialId |\n\nScalar arrays become repeated query keys. Arrays of objects use indexed bracket\nnotation; for example,\ncalendarsToLoad[0][credentialId]=42. Query nesting is rejected beyond eight\nlevels.\n\nJSON bodies\n\nGET and DELETE requests send no JSON body. Path and query fields are removed\nfrom the action object before a POST, PATCH, or PUT body is sent. The\nopaque webhooksecretref and internal compensation metadata are also removed.\n\nFor managed webhook create or update, the connector validates the destination,\nresolves the opaque reference, and injects the provider secret afterward; a\nraw secret never enters AIP action input.\n\nThis partition is significant for calendar.selected.delete: its supported\nfields are query parameters because the connector sends no delete body.\n\nComplete capability route map\n\nThe rows remain in the connector's source order. Paths are relative to the\nconfigured provider base URL.\n\nProfile\n\n| Capability | Method | Version | Provider path |\n\n| cap:caldiy:profile.get | GET | 2024-08-13 | /v2/me |\n| cap:caldiy:profile.update | PATCH | 2024-08-13 | /v2/me |\n\nEvent types, private links, and event-type webhooks\n\n| Capability | Method | Version | Provider path |\n\n| cap:caldiy:eventtype.list | GET | 2024-06-14 | /v2/event-types |\n| cap:caldiy:eventtype.get | GET | 2024-06-14 | /v2/event-types/{eventtypeid} |\n| cap:caldiy:eventtype.create | POST | 2024-06-14 | /v2/event-types |\n| cap:caldiy:eventtype.update | PATCH | 2024-06-14 | /v2/event-types/{eventtypeid} |\n| cap:caldiy:eventtype.delete | DELETE | 2024-06-14 | /v2/event-types/{eventtypeid} |\n| cap:caldiy:eventtype.privatelink.list | GET | 2024-04-15 | /v2/event-types/{eventtypeid}/private-links |\n| cap:caldiy:eventtype.privatelink.create | POST | 2024-04-15 | /v2/event-types/{eventtypeid}/private-links |\n| cap:caldiy:eventtype.privatelink.update | PATCH | 2024-04-15 | /v2/event-types/{eventtypeid}/private-links/{linkid} |\n| cap:caldiy:eventtype.privatelink.delete | DELETE | 2024-04-15 | /v2/event-types/{eventtypeid}/private-links/{linkid} |\n| cap:caldiy:eventtype.webhook.list | GET | 2024-06-14 | /v2/event-types/{eventtypeid}/webhooks |\n| cap:caldiy:eventtype.webhook.get | GET | 2024-06-14 | /v2/event-types/{eventtypeid}/webhooks/{webhookid} |\n| cap:caldiy:eventtype.webhook.create | POST | 2024-06-14 | /v2/event-types/{eventtypeid}/webhooks |\n| cap:caldiy:eventtype.webhook.update | PATCH | 2024-06-14 | /v2/event-types/{eventtypeid}/webhooks/{webhookid} |\n| cap:caldiy:eventtype.webhook.delete | DELETE | 2024-06-14 | /v2/event-types/{eventtypeid}/webhooks/{webhookid} |\n| cap:caldiy:eventtype.webhook.deleteall | DELETE | 2024-06-14 | /v2/event-types/{eventtypeid}/webhooks |\n\nSlots and reservations\n\n| Capability | Method | Version | Provider path |\n\n| cap:caldiy:slot.list | GET | 2024-09-04 | /v2/slots |\n| cap:caldiy:slot.reservation.create | POST | 2024-09-04 | /v2/slots/reservations |\n| cap:caldiy:slot.reservation.get | GET | 2024-09-04 | /v2/slots/reservations/{reservationuid} |\n| cap:caldiy:slot.reservation.update | PATCH | 2024-09-04 | /v2/slots/reservations/{reservationuid} |\n| cap:caldiy:slot.reservation.delete | DELETE | 2024-09-04 | /v2/slots/reservations/{reservationuid} |\n\nBookings\n\n| Capability | Method | Version | Provider path |\n\n| cap:caldiy:booking.list | GET | 2024-08-13 | /v2/bookings |\n| cap:caldiy:booking.get | GET | 2024-08-13 | /v2/bookings/{bookinguid} |\n| cap:caldiy:booking.getbyseat | GET | 2024-08-13 | /v2/bookings/by-seat/{seatuid} |\n| cap:caldiy:booking.create | POST | 2024-08-13 | /v2/bookings |\n| cap:caldiy:booking.reschedule | POST | 2024-08-13 | /v2/bookings/{bookinguid}/reschedule |\n| cap:caldiy:booking.cancel | POST | 2024-08-13 | /v2/bookings/{bookinguid}/cancel |\n| cap:caldiy:booking.confirm | POST | 2024-08-13 | /v2/bookings/{bookinguid}/confirm |\n| cap:caldiy:booking.decline | POST | 2024-08-13 | /v2/bookings/{bookinguid}/decline |\n| cap:caldiy:booking.markabsent | POST | 2024-08-13 | /v2/bookings/{bookinguid}/mark-absent |\n| cap:caldiy:booking.reassign | POST | 2024-08-13 | /v2/bookings/{bookinguid}/reassign |\n| cap:caldiy:booking.reassigntouser | POST | 2024-08-13 | /v2/bookings/{bookinguid}/reassign/{userid} |\n| cap:caldiy:booking.location.update | PATCH | 2024-08-13 | /v2/bookings/{bookinguid}/location |\n| cap:caldiy:booking.attendee.list | GET | 2024-08-13 | /v2/bookings/{bookinguid}/attendees |\n| cap:caldiy:booking.attendee.get | GET | 2024-08-13 | /v2/bookings/{bookinguid}/attendees/{attendeeid} |\n| cap:caldiy:booking.attendee.add | POST | 2024-08-13 | /v2/bookings/{bookinguid}/attendees |\n| cap:caldiy:booking.attendee.delete | DELETE | 2024-08-13 | /v2/bookings/{bookinguid}/attendees/{attendeeid} |\n| cap:caldiy:booking.guest.add | POST | 2024-08-13 | /v2/bookings/{bookinguid}/guests |\n| cap:caldiy:booking.calendarlinks.get | GET | 2024-08-13 | /v2/bookings/{bookinguid}/calendar-links |\n| cap:caldiy:booking.reference.list | GET | 2024-08-13 | /v2/bookings/{bookinguid}/references |\n| cap:caldiy:booking.recording.list | GET | 2024-08-13 | /v2/bookings/{bookinguid}/recordings |\n| cap:caldiy:booking.transcript.list | GET | 2024-08-13 | /v2/bookings/{bookinguid}/transcripts |\n| cap:caldiy:booking.conferencingsession.list | GET | 2024-08-13 | /v2/bookings/{bookinguid}/conferencing-sessions |\n\nCalendars and free/busy\n\n| Capability | Method | Version | Provider path |\n\n| cap:caldiy:calendar.list | GET | 2024-08-13 | /v2/calendars |\n| cap:caldiy:calendar.provider.check | GET | 2024-08-13 | /v2/calendars/{calendar}/check |\n| cap:caldiy:calendar.disconnect | POST | 2024-08-13 | /v2/calendars/{calendar}/disconnect |\n| cap:caldiy:calendar.icsfeed.check | GET | 2024-08-13 | /v2/calendars/ics-feed/check |\n| cap:caldiy:calendar.busytime.list | GET | 2024-08-13 | /v2/calendars/busy-times |\n| cap:caldiy:calendar.connection.list | GET | 2024-08-13 | /v2/calendars/connections |\n| cap:caldiy:calendar.connection.event.list | GET | 2024-08-13 | /v2/calendars/connections/{connectionid}/events |\n| cap:caldiy:calendar.connection.event.get | GET | 2024-08-13 | /v2/calendars/connections/{connectionid}/events/{eventid} |\n| cap:caldiy:calendar.connection.event.create | POST | 2024-08-13 | /v2/calendars/connections/{connectionid}/events |\n| cap:caldiy:calendar.connection.event.update | PATCH | 2024-08-13 | /v2/calendars/connections/{connectionid}/events/{eventid} |\n| cap:caldiy:calendar.connection.event.delete | DELETE | 2024-08-13 | /v2/calendars/connections/{connectionid}/events/{eventid} |\n| cap:caldiy:calendar.connection.freebusy.get | GET | 2024-08-13 | /v2/calendars/connections/{connectionid}/freebusy |\n| cap:caldiy:calendar.event.list | GET | 2024-08-13 | /v2/calendars/{calendar}/events |\n| cap:caldiy:calendar.event.get | GET | 2024-08-13 | /v2/calendars/{calendar}/events/{eventuid} |\n| cap:caldiy:calendar.event.create | POST | 2024-08-13 | /v2/calendars/{calendar}/events |\n| cap:caldiy:calendar.event.update | PATCH | 2024-08-13 | /v2/calendars/{calendar}/events/{eventuid} |\n| cap:caldiy:calendar.event.delete | DELETE | 2024-08-13 | /v2/calendars/{calendar}/events/{eventuid} |\n| cap:caldiy:calendar.freebusy.get | GET | 2024-08-13 | /v2/calendars/{calendar}/freebusy |\n| cap:caldiy:calendar.destination.update | PUT | 2024-08-13 | /v2/destination-calendars |\n| cap:caldiy:calendar.selected.add | POST | 2024-08-13 | /v2/selected-calendars |\n| cap:caldiy:calendar.selected.delete | DELETE | 2024-08-13 | /v2/selected-calendars |\n\nConferencing\n\n| Capability | Method | Version | Provider path |\n\n| cap:caldiy:conferencing.list | GET | 2024-08-13 | /v2/conferencing |\n| cap:caldiy:conferencing.default.get | GET | 2024-08-13 | /v2/conferencing/default |\n| cap:caldiy:conferencing.default.set | POST | 2024-08-13 | /v2/conferencing/{app}/default |\n| cap:caldiy:conferencing.connect | POST | 2024-08-13 | /v2/conferencing/{app}/connect |\n| cap:caldiy:conferencing.disconnect | DELETE | 2024-08-13 | /v2/conferencing/{app}/disconnect |\n\nSchedules\n\n| Capability | Method | Version | Provider path |\n\n| cap:caldiy:schedule.list | GET | 2024-06-11 | /v2/schedules |\n| cap:caldiy:schedule.default.get | GET | 2024-06-11 | /v2/schedules/default |\n| cap:caldiy:schedule.get | GET | 2024-06-11 | /v2/schedules/{scheduleid} |\n| cap:caldiy:schedule.create | POST | 2024-06-11 | /v2/schedules |\n| cap:caldiy:schedule.update | PATCH | 2024-06-11 | /v2/schedules/{scheduleid} |\n| cap:caldiy:schedule.delete | DELETE | 2024-06-11 | /v2/schedules/{scheduleid} |\n\nUser webhooks\n\n| Capability | Method | Version | Provider path |\n\n| cap:caldiy:webhook.list | GET | 2024-08-13 | /v2/webhooks |\n| cap:caldiy:webhook.get | GET | 2024-08-13 | /v2/webhooks/{webhookid} |\n| cap:caldiy:webhook.create | POST | 2024-08-13 | /v2/webhooks |\n| cap:caldiy:webhook.update | PATCH | 2024-08-13 | /v2/webhooks/{webhookid} |\n| cap:caldiy:webhook.delete | DELETE | 2024-08-13 | /v2/webhooks/{webhookid} |\n\nDiagnose route or version drift\n\n| Observation | Interpretation | Safe response |\n\n| 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 |\n| Provider returns 404 or 405 | Route, method, account scope, or upstream behavior may differ | Preserve request evidence and compare exact revisions before changing source |\n| 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 |\n| Provider returns a redirect | The hardened client does not follow it | Verify the configured base URL and reviewed route mapping |\n| Connector reports invalid action | A path, query, or body field failed the capability schema | Correct the AIP input; do not call the provider directly |\n| Mutation outcome is uncertain | Dispatch may have crossed the provider boundary | Reconcile the original action and idempotency identity |\n| 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 |\n\nA provider error alone does not prove that this table is wrong. First compare\nthe admitted catalog revision, connector artifact digest, configured upstream,\ncapability input, provider request id, and durable action state.\n\nReview a route-map change\n\nA connector change that alters any row should update and review one coherent\nset of artifacts:\n1. operation suffix, method, path template, path fields, query fields, and API\n   version in source;\n2. the input schema and path/query/body partition for the same capability;\n3. route, version-header, encoding, and secret-boundary contract tests;\n4. the generated capability snapshot and its source provenance;\n5. this route map and the affected capability reference;\n6. conformance and provider qualification evidence for the exact artifact.\n\nDo not ship a route-only edit that leaves schemas, tests, generated metadata,\nor evidence pinned to a different request shape.\n\nSecurity and evidence boundaries\n• Public actions select a known capability, not an arbitrary provider route.\n• Deployment configuration owns the provider origin and authentication mode.\n• Path values are encoded as individual URL segments.\n• Only enumerated query fields are serialized, with bounded nesting.\n• Provider credentials and raw webhook secrets are excluded from action input.\n• Redirects are disabled and the provider exchange has a fixed timeout.\n• A source-derived row proves implementation intent, not live provider support.\n• Provider-route absence is not permission to use an operator-only endpoint.\n\nRelated documentation\n• Cal.diy capability index (../capabilities/README.md)\n• Generated capability snapshot (../assets/capabilities.json)\n• Cal.diy configuration (configuration.md)\n• Connector contract (../../../spec/connector-contract.md)\n• Error reference (../../../reference/errors.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "d4a257f0f96ce532351f9557eb77bbb451e00302f5dac3324bd067039d4b74d2"
  }
}