> For the complete documentation index, see [llms.txt](https://docs.dapta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dapta.ai/dcal/developers/cal-com-compatible-api.md).

# Cal.com-compatible API

dCal's /v2 endpoints follow the shape of Cal.com's API v2, so a tool or automation that already speaks Cal.com can read your event types and open times and create, read, move and cancel dCal bookings

Some tools, automations and AI agents already know how to talk to Cal.com's API v2. dCal answers a set of the same operations under `/v2`, with the same paths, the same `cal-api-version` header and the same field names, so you can point those tools at dCal with a dCal API key.

If you are writing your own integration from scratch, the [REST API](https://docs.dapta.ai/dcal/developers/rest-api.md) may be simpler. Both share the same booking engine and offer the same open times. One difference: `/v2` books only a time the event offers, while `/v1/machine` can also book a free time outside those slots. dCal's MCP server for AI assistants, which uses that engine too, is available at `https://mcp.dcal.ai/mcp`: see [Connect an AI assistant (MCP)](https://docs.dapta.ai/dcal/developers/mcp-server.md).

No screenshots here: everything on this page happens between your system and the API.

***

## Base URL and authentication

|                |                                                                                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Base URL       | `https://api.dcal.ai/v2`                                                                                                                          |
| Authentication | `Authorization: Bearer <your API key>`. The key starts with `dcl_`. No other header is accepted.                                                  |
| Version header | `cal-api-version`, with the exact value each endpoint asks for (see below). A missing or different value answers `400` `UNSUPPORTED_API_VERSION`. |
| Body format    | JSON, with `Content-Type: application/json`                                                                                                       |
| Times          | ISO 8601 with `Z` or an offset, for example `2026-11-03T15:00:00-05:00`                                                                           |

Create the key in **API and webhooks** > **API keys**. See [API keys](https://docs.dapta.ai/dcal/developers/api-keys.md). A key limited to some event types sees only those: `/v2/event-types` lists only them, and any other event type, or a booking on one, answers `404` `RESOURCE_NOT_FOUND`. The calendar endpoints are not limited by event type.

> **⚠️ Note:** Call the API from a server. Never put a key in a web page or a URL.

***

## Endpoints

| Method and path                      | `cal-api-version` | Access the key needs                                                              | What it does                                                                                    |
| ------------------------------------ | ----------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `GET /v2/event-types`                | `2024-06-14`      | **See event types**                                                               | Lists your visible event types, personal and team.                                              |
| `GET /v2/slots`                      | `2024-09-04`      | **Check free times**                                                              | The open times of one event type.                                                               |
| `POST /v2/bookings`                  | `2026-02-25`      | **Create, hold, reschedule, confirm and decline bookings**                        | Books a time.                                                                                   |
| `GET /v2/bookings/{uid}`             | `2026-02-25`      | **Read bookings**                                                                 | Reads one booking.                                                                              |
| `POST /v2/bookings/{uid}/reschedule` | `2026-02-25`      | **Create, hold, reschedule, confirm and decline bookings**                        | Moves a booking. The moved booking gets a new `uid`.                                            |
| `POST /v2/bookings/{uid}/cancel`     | `2026-02-25`      | **Cancel bookings** or **Create, hold, reschedule, confirm and decline bookings** | Cancels a booking.                                                                              |
| `POST /v2/bookings/{uid}/guests`     | `2024-08-13`      | **Create, hold, reschedule, confirm and decline bookings**                        | Adds guests to a booking.                                                                       |
| `GET /v2/calendars`                  | none              | **See connected calendars**                                                       | Lists the calendars connected in your workspace.                                                |
| `POST /v2/calendars/availability`    | none              | **See connected calendars**                                                       | Open times of a given length across chosen calendars. A dCal addition, not a Cal.com operation. |

The access names are the ones in the **Create key** dialog. In code, they are the scopes `event-types:read`, `availability:read`, `bookings:write`, `bookings:read`, `bookings:cancel` and `calendars:read`.

Every answer has the same envelope: `{ "status": "success", "data": ... }`.

***

## Choosing the event

`/v2/slots` and `POST /v2/bookings` need to know which event type you mean. Send exactly one of:

* `eventTypeId`: the `id` that `/v2/event-types` returns. Its `daptaId` works too.
* `eventTypeSlug` with `username`: a personal event, by its slug and the host's handle.
* `eventTypeSlug` with `teamSlug`: a team event, by its slug and the team's slug.

For the link `book.dcal.ai/k7m2xq/jdoe/intro-call`, the handle is `jdoe` and the slug is `intro-call`. Team events work here, unlike the `/v1/machine` endpoints.

***

## GET /v2/event-types

Optional query filters: `username`, `teamSlug` and `eventSlug`. Hidden event types are never listed.

Each event type has `id`, `daptaId`, `title`, `slug`, `description`, `lengthInMinutes`, `hidden`, `type` (`personal` or `team`), `username`, `teamSlug`, `schedulingType`, `locations`, `bookingFields`, `bookingWindow`, `successRedirectUrl` and, for a team event, `team`.

| Field                | Meaning                                                                                                                                                                                             |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bookingWindow`      | How far ahead guests can book, from the event's **Booking window (days)**: `{ "type": "calendarDays", "value": 14, "rolling": false }` for 14 calendar days, or `null` when the event has no limit. |
| `successRedirectUrl` | The address set in the event's **Redirect after booking**, as typed, or `null` when guests stay on the confirmation.                                                                                |

Both are read only here: you change them in the event's settings in the dashboard. The OpenAPI document does not list these two fields.

***

## GET /v2/slots

| Query parameter | Required | Meaning                                                                             |
| --------------- | -------- | ----------------------------------------------------------------------------------- |
| The event       | Yes      | See [Choosing the event](#choosing-the-event).                                      |
| `start`         | Yes      | A date such as `2026-11-03`, or a time with an offset.                              |
| `end`           | Yes      | A date (that whole day is included) or a time with an offset.                       |
| `timeZone`      | No       | An IANA time zone. Default `UTC`.                                                   |
| `format`        | No       | `time` (default) gives each slot's `start`; `range` adds its `end`.                 |
| `duration`      | No       | Must equal the event's length. Another value answers `422` `FEATURE_NOT_SUPPORTED`. |

A bare date is read as a whole day in UTC. For days in your own time zone, send times with an offset. A window longer than 60 days is cut to 60 days, and no time past the event's booking window is returned. The answer groups the slots by day, in the time zone you asked for:

```json
{
  "status": "success",
  "data": {
    "2026-11-03": [
      { "start": "2026-11-03T09:00:00.000-05:00" },
      { "start": "2026-11-03T09:30:00.000-05:00" }
    ]
  }
}
```

These are the same times your booking page offers. See [How open times are calculated](https://docs.dapta.ai/dcal/calendars-and-availability/how-open-times-work.md).

***

## POST /v2/bookings

| Body field               | Required                              | Meaning                                                                                                                                                                                                      |
| ------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| The event                | Yes                                   | See [Choosing the event](#choosing-the-event).                                                                                                                                                               |
| `start`                  | Yes                                   | A slot from `/v2/slots`, with its offset.                                                                                                                                                                    |
| `attendee`               | Yes                                   | `name`, `email`, `timeZone`, plus optional `phoneNumber` and `language`. `email` must be a valid address: a blank one is refused with `400`. `language` is `en` or `es`, the language of the guest's emails. |
| `guests`                 | No                                    | Up to 10 more email addresses. dCal does not email them: they are added to the event on the host's calendar, and that calendar sends everyone on it its own invitation, the attendee included.               |
| `bookingFieldsResponses` | When the event has required questions | Answers to the event's booking questions, keyed by each question's name.                                                                                                                                     |
| `metadata`               | No                                    | Up to 50 keys of your own, each up to 40 characters, with text values up to 500 characters. Returned as is.                                                                                                  |
| `destinationCalendarId`  | No                                    | Personal events only: one of the host's calendars from `/v2/calendars` that can receive new events.                                                                                                          |

Add an `Idempotency-Key` header (1 to 128 characters) so a retry can never book twice. The same key with the same body returns the first booking; the same key with a different body answers `409` `IDEMPOTENCY_KEY_REUSED`.

A booking answers `201` with the booking: its `uid`, `status`, `start`, `end`, `duration`, `hosts`, `attendees`, `guests`, `location`, `meetingUrl`, `bookingFieldsResponses`, `metadata`, `utm` and more. What happens next is what happens after a booking on your page: the emails, with the guest's link to manage the booking on `book.dcal.ai`, the calendar event, HubSpot if you connected it, and a `booking.created` webhook. **One booking per person** does not apply to bookings made with a key. **Redirect after booking** and campaign UTMs belong to bookings made on a booking page: the answer carries no redirect address, and a booking made with a key keeps no UTMs, so its `utm` is `null` unless it takes a seat in a group booking that already has a campaign.

***

## Reading, moving and cancelling

* **`GET /v2/bookings/{uid}`** returns one booking, in the same shape. It also reads an event a host put on their own calendar with the MCP tool [`create_event`](https://docs.dapta.ai/dcal/developers/mcp-tools.md#create_event): such an event has no event type, so its `eventTypeId` and `eventType` are `null`. A key limited to some event types does not see it.
* **`POST /v2/bookings/{uid}/reschedule`** takes `start` (a new offered slot, with its offset, within the event's booking window), and optional `reschedulingReason` (up to 1,000 characters) and `rescheduledBy` (an email). It answers `201` with the moved booking, which has a **new** `uid`; the old booking is linked to it. Your webhooks receive `booking.rescheduled` with the new `uid` and `rescheduledFromUid`. The guest's **Booking rescheduled** email updates the entry already in their calendar instead of adding a second one.
* **`POST /v2/bookings/{uid}/cancel`** takes an optional `cancellationReason` (up to 1,000 characters). It answers `200` with the cancelled booking and emails the guest.
* **`POST /v2/bookings/{uid}/guests`** takes `guests`: 1 to 10 per call, each with a valid `email` and optional `name` and `timeZone`. A booking holds at most 30 people in all, counting the guest who booked, every attendee and every guest once, or the event's seats per time when that is more. An email already on the booking is skipped. When at least one guest is added to an accepted booking, dCal updates the event on the host's calendar so they are on it; dCal itself sends them no email. From then on, the host's calendar sends its own invitations and updates to everyone on the event, the attendee included.

Every one of these answers, like the answer to `POST /v2/bookings`, carries `utm`: the campaign the booking came from, or `null` when it has none. For a booking made on your booking page from a link with UTM tags, it holds the `utm_source`, `utm_medium`, `utm_campaign`, `utm_term` and `utm_content` the booking kept, each only when present. A booking moved with `reschedule` keeps its campaign under its new `uid`. `utm` is a dCal addition, not a Cal.com field, so a Cal.com client ignores it. See [Track where bookings come from](https://docs.dapta.ai/dcal/share/your-booking-page.md#track-where-bookings-come-from).

Rescheduling, cancelling and adding guests also accept an `Idempotency-Key` header, with the same rules as booking.

***

## Calendars

* **`GET /v2/calendars`** lists the calendars connected in your workspace, grouped by connection, plus a suggested `destinationCalendar`: the first primary calendar that is not read-only.
* **`POST /v2/calendars/availability`** answers the open slots, start and end in UTC, across up to 100 calendars from that list. Send `calendarIds`, `from`, `to`, `timeZone`, `durationMinutes` (1 to 1,440), optional `intervalMinutes`, `bufferBeforeMinutes` and `bufferAfterMinutes`, and a `mode`: `perCalendar`, `allAvailable` or `anyAvailable`. A range longer than 31 days answers `400` `RANGE_TOO_LARGE`.

***

## What is not supported

These Cal.com features answer `422` `FEATURE_NOT_SUPPORTED`, or are not available at all:

* Listing bookings. Use `GET /v1/machine/bookings` from the [REST API](https://docs.dapta.ai/dcal/developers/rest-api.md).
* Holding a slot before booking (`reservationUid`).
* Group events with more than one seat per time.
* Recurring bookings, instant meetings and routing.
* A length other than the event's own (`lengthInMinutes`, `duration`).
* Overriding the location or the meeting link of one booking.
* Email verification, `allowConflicts`, `allowBookingOutOfBounds` and `skipBookingLimits`.
* Leaving the booking being rescheduled out of `/v2/slots` (`bookingUidToReschedule`).
* A guest `language` (`attendee.language`) other than `en` or `es`.
* `destinationCalendarId` on a team event.

***

## Errors

Every error has the same body:

```json
{
  "status": "error",
  "error": {
    "code": "SLOT_TAKEN",
    "message": "That time was just booked. Pick another slot.",
    "details": {},
    "requestId": "..."
  }
}
```

The `message` is in English and can change. Build on the `code`. Every answer carries an `X-Request-Id` header with the same `requestId`: include it when you contact support.

| Status | `code`                    | Meaning                                                                                                                 |
| ------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `400`  | `INVALID_REQUEST`         | A field is missing or malformed.                                                                                        |
| `400`  | `INVALID_TIMEZONE`        | The time zone is not an IANA zone.                                                                                      |
| `400`  | `UNSUPPORTED_API_VERSION` | The `cal-api-version` header is missing or not the value that endpoint asks for.                                        |
| `400`  | `RANGE_TOO_LARGE`         | Calendar availability for more than 31 days.                                                                            |
| `400`  | `INVALID_SLOT`            | The new time of a reschedule is not one the event offers, for example a time past its booking window.                   |
| `401`  | `AUTHENTICATION_REQUIRED` | No `Authorization` header.                                                                                              |
| `401`  | `INVALID_API_KEY`         | The key is wrong, revoked or expired, or was not sent as `Bearer dcl_...`.                                              |
| `403`  | `INSUFFICIENT_SCOPE`      | The key lacks the access this endpoint needs.                                                                           |
| `403`  | `CALENDAR_READ_ONLY`      | The `destinationCalendarId` cannot receive new events.                                                                  |
| `404`  | `RESOURCE_NOT_FOUND`      | No such event type, booking or calendar in your workspace, or outside the key's event types.                            |
| `409`  | `SLOT_TAKEN`              | That time is no longer free. Pick another one from `/v2/slots`.                                                         |
| `409`  | `CALENDAR_UNAVAILABLE`    | A calendar that blocks bookings could not be read, so nothing was booked or moved. Try again in a moment.               |
| `409`  | `IDEMPOTENCY_KEY_REUSED`  | That `Idempotency-Key` was already used with a different request.                                                       |
| `410`  | `GONE`                    | The booking can no longer be changed.                                                                                   |
| `422`  | `BOOKING_FIELDS_INVALID`  | A required booking question has no answer, or the start time is not one the event offers.                               |
| `422`  | `LIMIT_EXCEEDED`          | Adding these guests would take the booking past 30 people in all, or past the event's seats per time when that is more. |
| `422`  | `FEATURE_NOT_SUPPORTED`   | See [What is not supported](#what-is-not-supported). `details.feature` names it.                                        |

***

## Limits

* Request bodies are limited to 100 kB.
* The `/v2` endpoints have no published per-key rate limit today. Build as if they had one: when you get a `429`, wait for `Retry-After` seconds; when you get a `5xx`, retry with a growing delay and the same `Idempotency-Key`.
* The [interactive reference](https://api.dcal.ai/docs) and the [OpenAPI document](https://api.dcal.ai/openapi.json) describe every field. In the dashboard, **API and webhooks** > **API docs** opens the reference, and the reference's introduction links the document. In the reference, the `/v2` operations are under **Cal.com-compatible API**, and `POST /v2/calendars/availability` under **Calendar availability**. Its introduction also lists the `cal-api-version` each `/v2` operation needs.

## Related

* [API keys](https://docs.dapta.ai/dcal/developers/api-keys.md): create the key and choose its access.
* [REST API](https://docs.dapta.ai/dcal/developers/rest-api.md): the `/v1/machine` endpoints, including the booking list.
* [Connect an AI assistant (MCP)](https://docs.dapta.ai/dcal/developers/mcp-server.md): dCal's MCP server, available at `https://mcp.dcal.ai/mcp` with a sign-in or an API key.
* [Webhooks](https://docs.dapta.ai/dcal/integrations/webhooks.md): get told about every booking change.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.dapta.ai/dcal/developers/cal-com-compatible-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
