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

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.

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

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.

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.

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 webhook_secret_ref 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

Event types, private links, and event-type webhooks

Slots and reservations

Bookings

Calendars and free/busy

Conferencing

Schedules

User webhooks

Diagnose route or version drift

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
• Generated capability snapshot
• Cal.diy configuration
• Connector contract
• Error reference