> 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/rest-api.md).

# REST API

The dCal REST API for your own systems: read an event's open times, then create, list, reschedule and cancel bookings with an API key. Covers the base URL, authentication, idempotency, errors, rate li

The REST API lets your own systems do what a guest does on your booking page: read the open times of an event and book one, plus list, reschedule and cancel bookings. It is the same engine as the booking page, so it offers the same times and keeps the same rules.

You need an [API key](https://docs.dapta.ai/dcal/developers/api-keys.md) with the right scopes. Only workspace admins and owners can create one.

***

## Base URL and authentication

|                |                                                                                    |
| -------------- | ---------------------------------------------------------------------------------- |
| Base URL       | `https://api.dcal.ai`                                                              |
| Authentication | `Authorization: Bearer <your key>`. The header `x-api-key: <your key>` also works. |
| Body format    | JSON, with `Content-Type: application/json`                                        |
| Times          | ISO 8601 in UTC, for example `2026-11-02T14:00:00.000Z`                            |

Every endpoint below sits under `/v1/machine`.

> **⚠️ Note:** Call the API from a server. Browsers block calls from pages on other websites, and a key placed in a web page is a key anyone can copy. Never put a key in a URL.

***

## Endpoints

| Method and path                             | Scope                                 | What it does                                                  |
| ------------------------------------------- | ------------------------------------- | ------------------------------------------------------------- |
| `GET /v1/machine/availability`              | `availability:read`                   | The open times of one event between `from` and `to`.          |
| `POST /v1/machine/bookings`                 | `bookings:write`                      | Book a time on one event.                                     |
| `GET /v1/machine/bookings`                  | `bookings:read`                       | List the bookings of your workspace, latest start time first. |
| `PATCH /v1/machine/bookings/{uid}`          | `bookings:write`                      | Move a booking to a new start time.                           |
| `POST /v1/machine/bookings/{uid}/cancel`    | `bookings:cancel` or `bookings:write` | Cancel a booking.                                             |
| `POST /v1/machine/bookings/{uid}/attendees` | `bookings:write`                      | Add one more guest to a booking.                              |

### Which event: handle and slug, or event ID

The availability and booking endpoints need to know which event you mean. Send either:

* `handle` and `slug`: the last two parts of the event's public link. For `book.dcal.ai/k7m2xq/jdoe/intro-call`, the handle is `jdoe` and the slug is `intro-call`. Your key already names the workspace, so the first part is not needed.
* `eventTypeId`: the ID at the end of the address when you open the event in the dashboard, `app.dcal.ai/admin/event-types/<eventTypeId>`.

These endpoints work with personal events. Team events cannot be booked through them.

### `GET /v1/machine/availability`

| Query parameter                       | Required | Meaning                                                                                      |
| ------------------------------------- | -------- | -------------------------------------------------------------------------------------------- |
| `handle` and `slug`, or `eventTypeId` | Yes      | The event.                                                                                   |
| `from`                                | Yes      | Start of the window, ISO 8601 UTC.                                                           |
| `to`                                  | Yes      | End of the window, ISO 8601 UTC. A window longer than 60 days is cut to 60 days from `from`. |
| `timeZone`                            | No       | An IANA time zone, such as `America/Bogota`.                                                 |

The answer is the same set of times the booking page offers: your working hours, minimum notice, the event's **Booking window (days)**, buffers, other bookings and the busy times of the calendars you check for conflicts. No time past the booking window is returned, even inside the window you asked for.

```bash
curl --get "https://api.dcal.ai/v1/machine/availability" \
  --header "Authorization: Bearer $DCAL_API_KEY" \
  --data-urlencode "handle=jdoe" \
  --data-urlencode "slug=intro-call" \
  --data-urlencode "from=2026-11-02T00:00:00Z" \
  --data-urlencode "to=2026-11-09T00:00:00Z" \
  --data-urlencode "timeZone=America/Bogota"
```

The response, trimmed to two times:

```json
{
  "eventType": {
    "slug": "intro-call",
    "title": "Intro call",
    "lengthMinutes": 30,
    "bookingFields": [],
    "schedulingType": null,
    "location": null
  },
  "timeZone": "America/Bogota",
  "slots": [
    { "startUtc": "2026-11-02T14:00:00.000Z" },
    { "startUtc": "2026-11-02T14:30:00.000Z" }
  ]
}
```

* `bookingFields` lists the event's own booking questions, so you know which `answers` to send.
* On a group event each slot also carries `spotsLeft` and `capacity`.
* When `slots` is empty because of a setup problem, the response adds `emptyReason`: `SCHEDULE_MISSING`, `NO_SCHEDULE`, `NO_HOURS`, `CALENDAR_UNAVAILABLE` or `NO_HOSTS`. With no `emptyReason`, the window is simply full. See [Troubleshooting](https://docs.dapta.ai/dcal/troubleshooting.md).

### `POST /v1/machine/bookings`

| Body field                            | Required | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `handle` and `slug`, or `eventTypeId` | Yes      | The event.                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `startUtc`                            | Yes      | The start time. Use a `startUtc` returned by the availability endpoint.                                                                                                                                                                                                                                                                                                                                                                            |
| `attendees`                           | Yes      | A list with at least one person. The first one is the guest who receives the emails; any others are added to the calendar event as extra guests. With extra guests, your calendar sends everyone on the event its own invitation, the first person included. Each person needs `name`, `email` and `timeZone`, plus optional `phone` and `notes`. A blank `email` is refused with `400` `INTAKE_INVALID`, `Every attendee needs an email address.` |
| `answers`                             | No       | Answers to the event's booking questions, keyed by each question's name.                                                                                                                                                                                                                                                                                                                                                                           |

Add an `Idempotency-Key` header so a retry can never book twice. See [Idempotency](#idempotency).

```bash
curl "https://api.dcal.ai/v1/machine/bookings" \
  --request POST \
  --header "Authorization: Bearer $DCAL_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: crm-lead-4821-intro-call" \
  --data '{
    "handle": "jdoe",
    "slug": "intro-call",
    "startUtc": "2026-11-02T14:00:00.000Z",
    "attendees": [
      { "name": "John Doe", "email": "docs-test+1@example.com", "timeZone": "America/Bogota", "phone": "+1 555 000 0000" }
    ],
    "answers": { "company": "Acme Corp" }
  }'
```

A booking answers `201` with the booking's `uid`, its `status`, `startUtc`, `endUtc` and `attendees`. Keep the `uid`: the other endpoints use it.

What happens next is exactly what happens after a booking on your booking page:

* The guest gets the confirmation email with the calendar invitation and the link to manage the booking, on `book.dcal.ai`. The response itself carries no manage link.
* You get the new booking email, the event is written to your calendar, the booking reaches HubSpot if you connected it, and a `booking.created` webhook fires.
* On an event with **Requires confirmation**, the booking is created with `status` `pending` and waits for you to confirm it.
* **Redirect after booking** and campaign UTMs belong to bookings made on a booking page: the response carries no redirect address, and a booking made with a key keeps no UTMs.

> **⚠️ Note:** A booking made with a key is written on your behalf. dCal still refuses a time that overlaps another booking or a busy event on your calendars, but it does not check that the time is one the booking page would offer, nor the event's booking window. Book a `startUtc` you got from the availability endpoint so your hours, minimum notice and booking window are respected. Keys are also exempt from **One booking per person**.

### `GET /v1/machine/bookings`

| Query parameter | Meaning                                           |
| --------------- | ------------------------------------------------- |
| `from`, `to`    | Only bookings that start in this window.          |
| `status`        | `accepted`, `pending`, `cancelled` or `rejected`. |
| `limit`         | 1 to 200. Default 50.                             |
| `cursor`        | The `nextCursor` of the previous page.            |

The answer is `{ "items": [...], "nextCursor": "..." }`. Each item has `uid`, `status`, `title`, `startUtc`, `endUtc` and `hostMemberId`. `nextCursor` is `null` on the last page.

The items carry no campaign (UTMs). To read the campaign of a booking made on your booking page, use `GET /v2/bookings/{uid}` from the [Cal.com-compatible API](https://docs.dapta.ai/dcal/developers/cal-com-compatible-api.md#reading-moving-and-cancelling).

### `PATCH /v1/machine/bookings/{uid}`

Body: `{ "newStartUtc": "<ISO 8601 UTC>" }`. Moves the booking, keeps its length, moves the calendar event and sends the guest and the host the rescheduled emails. Unlike a new booking, the new time must be one the event offers: inside your hours, after the minimum notice, within the event's booking window and free on your calendars. The guest's previous manage link stops working; the reschedule email carries the new one. Only an accepted booking can be moved.

### `POST /v1/machine/bookings/{uid}/cancel`

Body: `{ "reason": "..." }`, optional. Cancels the booking, removes the event from the calendar and emails the guest and the host. Cancelling a booking that is already cancelled answers success again, so a retry is safe.

### `POST /v1/machine/bookings/{uid}/attendees`

Body: `{ "attendee": { "name": "...", "email": "..." } }`, with optional `timeZone` (default `UTC`), `phone` and `notes`. Adds one more person to a booking that is accepted or still waiting for your confirmation.

| Answer                                                                | When                                                                                                                          |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `201` with `{ "ok": true, "uid": "<uid>" }`                           | The person was added. Also when that email is already on the booking: then nothing is written or sent again.                  |
| `400` `BAD_REQUEST`, `attendee name + email required`                 | The name or the email is missing or blank.                                                                                    |
| `403` `FORBIDDEN`                                                     | The booking is not in your workspace, or outside the key's event types.                                                       |
| `410` `GONE`, `booking is no longer active`                           | The booking is cancelled, declined or was moved.                                                                              |
| `422` `LIMIT_EXCEEDED`, `The booking has no room for more attendees.` | The booking already holds 30 people, counting every attendee and guest once, or the event's seats per time when that is more. |

dCal sends the added person no email and fires no webhook. On an accepted booking that is already on your calendar, dCal updates that calendar event so the new person is a guest on it, and your calendar may send them its own invitation. HubSpot, if connected, is updated too. To invite extra people from the start, list them in `attendees` when you create the booking.

***

## Event type settings

The settings of an event type, such as its **Booking window (days)**, its **Redirect after booking** and its tracking IDs, are set in the dashboard: no endpoint a key can call changes them. To read the booking window and the redirect address of your event types, use `GET /v2/event-types` from the [Cal.com-compatible API](https://docs.dapta.ai/dcal/developers/cal-com-compatible-api.md).

***

## Idempotency

Booking, rescheduling and cancelling accept an `Idempotency-Key` header: any string from 1 to 200 characters. dCal remembers it for your workspace. Send the same key again and you get the original result back, with no second booking, no second email and no second webhook.

Use one key per real-world action, built from something stable on your side, such as `crm-lead-4821-intro-call`. Do not reuse a key for a different action.

***

## Errors

The errors below share one body:

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

The `message` is in English and can change. Build on the `error` code.

| Status | `error`                | Meaning                                                                                                                                                                                                                            |
| ------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `BAD_REQUEST`          | A required field or parameter is missing, for example `from, to required` or `startUtc, attendees[] required`.                                                                                                                     |
| `400`  | `INTAKE_INVALID`       | An answer to a booking question is missing or invalid (the message names the question), an attendee has a blank email, or the start time is in the past or more than 2 years ahead.                                                |
| `400`  | `INVALID_SLOT`         | The new time of a reschedule is outside your hours, too soon for the minimum notice, past the event's booking window, or in the past.                                                                                              |
| `401`  | `UNAUTHENTICATED`      | `Invalid API key.`: the key is missing, wrong or revoked.                                                                                                                                                                          |
| `403`  | `FORBIDDEN`            | `Missing scope: <scope>`, or the booking is not in your workspace.                                                                                                                                                                 |
| `404`  | `NOT_FOUND`            | No event with that handle and slug, or with that ID.                                                                                                                                                                               |
| `409`  | `SLOT_TAKEN`           | Someone else has that time, or it is busy on your calendar. Pick another time.                                                                                                                                                     |
| `409`  | `CALENDAR_UNAVAILABLE` | A calendar you check for conflicts could not be read, so nothing was booked or moved. The answer carries `Retry-After: 5`: try again after that many seconds.                                                                      |
| `410`  | `GONE`                 | `Booking is no longer active.`: you tried to move a booking that is cancelled, declined or still pending, or to cancel a declined one. Adding someone to a booking that is no longer active answers `booking is no longer active`. |
| `422`  | `LIMIT_EXCEEDED`       | Adding someone would take the booking past 30 people, or past the event's seats per time when that is more.                                                                                                                        |
| `429`  | `RATE_LIMITED`         | Too many requests. See [Rate limits](#rate-limits).                                                                                                                                                                                |

Send valid emails, IANA time zones and ISO 8601 times: a value the API cannot read is not answered with one of these codes.

Every response carries an `X-Request-Id` header. Include it when you contact support about a request.

***

## Rate limits

The public endpoints behind your booking pages are throttled per visitor, with a burst of **60 requests** that refills at **1 request per second**. Past the limit they answer `429 Too Many Requests` with a `Retry-After` header in seconds and the body `{"error":"RATE_LIMITED","message":"Too many requests. Please slow down."}`.

The `/v1/machine` endpoints have no published per-key limit today. Build your integration 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 always send an `Idempotency-Key` so a retry is safe.

Request bodies are limited to 100 kB.

***

## OpenAPI document

The API describes itself:

* **`https://api.dcal.ai/openapi.json`**: the OpenAPI 3.1 document. Point your client generator or HTTP client at it.
* **`https://api.dcal.ai/docs`**: the API reference, one interactive page built from that document. It opens with an introduction: the base URL, a link to this OpenAPI document, how to authenticate with a key, the two APIs, the `cal-api-version` each `/v2` operation needs, safe retries with `Idempotency-Key`, and the MCP server. The operations follow, under **REST API** (the `/v1/machine` endpoints on this page), **Cal.com-compatible API**, **Calendar availability**, **Booking page** (the public endpoints behind your booking pages and manage links) and **Health**. In the dashboard, **API and webhooks** > **API docs** opens it in a new tab.

> **💡 Tip:** The document and the `/docs` page also describe the `/v2` endpoints, which follow the shape of Cal.com's API v2. See [Cal.com-compatible API](https://docs.dapta.ai/dcal/developers/cal-com-compatible-api.md).

To check that the API is up, call `GET https://api.dcal.ai/health`.

## Related

* [API keys](https://docs.dapta.ai/dcal/developers/api-keys.md): create the key these endpoints need.
* [Cal.com-compatible API](https://docs.dapta.ai/dcal/developers/cal-com-compatible-api.md): the `/v2` endpoints, including team events.
* [Webhooks](https://docs.dapta.ai/dcal/integrations/webhooks.md): get told about bookings made anywhere, instead of polling.
* [How open times are calculated](https://docs.dapta.ai/dcal/calendars-and-availability/how-open-times-work.md): the rules behind every slot the API returns.
* [Let your Dapta agent book](https://docs.dapta.ai/dcal/dapta-agents.md): the no-code way to let an AI agent book.


---

# 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/rest-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.
