> 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/dapta-docs-es/dcal/developers/rest-api.md).

# API REST

La API REST de dCal para tus propios sistemas: lee los horarios libres de un evento y crea, lista, reprograma y cancela reservas con una clave de API. Incluye la URL base, la autenticación, la idempot

La API REST permite que tus propios sistemas hagan lo mismo que un invitado en tu página de reservas: leer los horarios libres de un evento y reservar uno, además de listar, reprogramar y cancelar reservas. Usa el mismo motor que la página de reservas, así que ofrece los mismos horarios y respeta las mismas reglas.

Necesitas una [clave de API](https://docs.dapta.ai/dapta-docs-es/dcal/developers/api-keys.md) con los permisos adecuados. Solo los administradores y propietarios del workspace pueden crear una.

***

## URL base y autenticación

|                    |                                                                                        |
| ------------------ | -------------------------------------------------------------------------------------- |
| URL base           | `https://api.dcal.ai`                                                                  |
| Autenticación      | `Authorization: Bearer <tu clave>`. También sirve la cabecera `x-api-key: <tu clave>`. |
| Formato del cuerpo | JSON, con `Content-Type: application/json`                                             |
| Horas              | ISO 8601 en UTC, por ejemplo `2026-11-02T14:00:00.000Z`                                |

Todos los endpoints de abajo están bajo `/v1/machine`.

> **⚠️ Nota:** Llama a la API desde un servidor. Los navegadores bloquean las llamadas desde páginas de otros sitios web, y una clave puesta en una página web es una clave que cualquiera puede copiar. Nunca pongas una clave en una URL.

***

## Endpoints

| Método y ruta                               | Permiso                              | Qué hace                                                                               |
| ------------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
| `GET /v1/machine/availability`              | `availability:read`                  | Los horarios libres de un evento entre `from` y `to`.                                  |
| `POST /v1/machine/bookings`                 | `bookings:write`                     | Reserva un horario en un evento.                                                       |
| `GET /v1/machine/bookings`                  | `bookings:read`                      | Lista las reservas de tu workspace, de la hora de inicio más tardía a la más temprana. |
| `PATCH /v1/machine/bookings/{uid}`          | `bookings:write`                     | Mueve una reserva a una nueva hora de inicio.                                          |
| `POST /v1/machine/bookings/{uid}/cancel`    | `bookings:cancel` o `bookings:write` | Cancela una reserva.                                                                   |
| `POST /v1/machine/bookings/{uid}/attendees` | `bookings:write`                     | Añade un invitado más a una reserva.                                                   |

### Qué evento: identificador y slug, o ID del evento

Los endpoints de disponibilidad y de reserva necesitan saber de qué evento hablas. Envía una de estas dos cosas:

* `handle` y `slug`: las dos últimas partes del enlace público del evento. En `book.dcal.ai/k7m2xq/jdoe/intro-call`, el `handle` es `jdoe` y el `slug` es `intro-call`. Tu clave ya indica el workspace, así que la primera parte no hace falta.
* `eventTypeId`: el ID que aparece al final de la dirección cuando abres el evento en el panel, `app.dcal.ai/admin/event-types/<eventTypeId>`.

Estos endpoints funcionan con eventos personales. Los eventos de equipo no se pueden reservar por esta vía.

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

| Parámetro                          | Obligatorio | Significado                                                                                          |
| ---------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------- |
| `handle` y `slug`, o `eventTypeId` | Sí          | El evento.                                                                                           |
| `from`                             | Sí          | Inicio de la ventana, ISO 8601 en UTC.                                                               |
| `to`                               | Sí          | Fin de la ventana, ISO 8601 en UTC. Una ventana de más de 60 días se recorta a 60 días desde `from`. |
| `timeZone`                         | No          | Una zona horaria IANA, como `America/Bogota`.                                                        |

La respuesta trae los mismos horarios que ofrece la página de reservas: tu horario de trabajo, la antelación mínima, la **Antelación máxima (días)** del evento, los márgenes, las otras reservas y las horas ocupadas de los calendarios en los que verificas conflictos. No devuelve ningún horario más allá de la antelación máxima, aunque esté dentro de la ventana que pediste.

```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"
```

La respuesta, recortada a dos horarios:

```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` lista las preguntas propias del evento, para que sepas qué `answers` enviar.
* En un evento grupal, cada horario trae además `spotsLeft` y `capacity`.
* Cuando `slots` viene vacío por un problema de configuración, la respuesta añade `emptyReason`: `SCHEDULE_MISSING`, `NO_SCHEDULE`, `NO_HOURS`, `CALENDAR_UNAVAILABLE` o `NO_HOSTS`. Sin `emptyReason`, la ventana simplemente está llena. Mira [Solución de problemas](https://docs.dapta.ai/dapta-docs-es/dcal/troubleshooting.md).

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

| Campo del cuerpo                   | Obligatorio | Significado                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ---------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `handle` y `slug`, o `eventTypeId` | Sí          | El evento.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `startUtc`                         | Sí          | La hora de inicio. Usa un `startUtc` que te haya devuelto el endpoint de disponibilidad.                                                                                                                                                                                                                                                                                                                                                                                           |
| `attendees`                        | Sí          | Una lista con al menos una persona. La primera es el invitado que recibe los correos; las demás se añaden al evento del calendario como invitados adicionales. Con invitados adicionales, tu calendario le envía su propia invitación a todos los del evento, incluida la primera persona. Cada persona necesita `name`, `email` y `timeZone`, y opcionalmente `phone` y `notes`. Un `email` vacío se rechaza con `400` `INTAKE_INVALID`, `Every attendee needs an email address.` |
| `answers`                          | No          | Las respuestas a las preguntas del evento, con el nombre de cada pregunta como clave.                                                                                                                                                                                                                                                                                                                                                                                              |

Añade una cabecera `Idempotency-Key` para que un reintento nunca reserve dos veces. Mira [Idempotencia](#idempotencia).

```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" }
  }'
```

Una reserva responde `201` con el `uid` de la reserva, su `status`, `startUtc`, `endUtc` y `attendees`. Guarda el `uid`: los demás endpoints lo usan.

Lo que pasa después es exactamente lo mismo que tras una reserva en tu página de reservas:

* El invitado recibe el correo de confirmación con la invitación de calendario y el enlace para gestionar su reserva, en `book.dcal.ai`. La respuesta no trae ese enlace.
* Tú recibes el correo de nueva reserva, el evento se escribe en tu calendario, la reserva llega a HubSpot si lo conectaste y se dispara un webhook `booking.created`.
* En un evento con **Requiere confirmación**, la reserva se crea con `status` `pending` y espera a que la confirmes.
* **Redirigir después de reservar** y las UTM de campaña son de las reservas hechas en una página de reservas: la respuesta no trae ninguna dirección de redirección, y una reserva hecha con una clave no guarda UTM.

> **⚠️ Nota:** Una reserva hecha con una clave se escribe en tu nombre. dCal sigue rechazando un horario que choque con otra reserva o con un evento ocupado de tus calendarios, pero no comprueba que el horario sea uno que ofrecería la página de reservas, ni la antelación máxima del evento. Reserva un `startUtc` que te haya dado el endpoint de disponibilidad para respetar tu horario, tu antelación mínima y la antelación máxima. Las claves tampoco están sujetas a **Una reserva por persona**.

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

| Parámetro    | Significado                                      |
| ------------ | ------------------------------------------------ |
| `from`, `to` | Solo las reservas que empiezan en esta ventana.  |
| `status`     | `accepted`, `pending`, `cancelled` o `rejected`. |
| `limit`      | De 1 a 200. Por defecto, 50.                     |
| `cursor`     | El `nextCursor` de la página anterior.           |

La respuesta es `{ "items": [...], "nextCursor": "..." }`. Cada elemento trae `uid`, `status`, `title`, `startUtc`, `endUtc` y `hostMemberId`. `nextCursor` es `null` en la última página.

Los elementos no traen la campaña (UTM). Para leer la campaña de una reserva hecha en tu página de reservas, usa `GET /v2/bookings/{uid}` de la [API compatible con Cal.com](https://docs.dapta.ai/dapta-docs-es/dcal/developers/cal-com-compatible-api.md#leer-mover-y-cancelar).

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

Cuerpo: `{ "newStartUtc": "<ISO 8601 en UTC>" }`. Mueve la reserva, conserva su duración, mueve el evento del calendario y envía al invitado y al anfitrión los correos de reprogramación. A diferencia de una reserva nueva, la nueva hora tiene que ser una que ofrezca el evento: dentro de tu horario, después de la antelación mínima, dentro de la antelación máxima del evento y libre en tus calendarios. El enlace de gestión anterior del invitado deja de funcionar; el correo de reprogramación trae el nuevo. Solo se puede mover una reserva aceptada.

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

Cuerpo: `{ "reason": "..." }`, opcional. Cancela la reserva, quita el evento del calendario y envía correos al invitado y al anfitrión. Cancelar una reserva que ya está cancelada vuelve a responder con éxito, así que reintentar es seguro.

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

Cuerpo: `{ "attendee": { "name": "...", "email": "..." } }`, con `timeZone` (por defecto `UTC`), `phone` y `notes` opcionales. Añade una persona más a una reserva aceptada o que todavía espera tu confirmación.

| Respuesta                                                             | Cuándo                                                                                                                                 |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `201` con `{ "ok": true, "uid": "<uid>" }`                            | Se añadió la persona. También cuando ese correo ya está en la reserva: entonces no se escribe ni se envía nada otra vez.               |
| `400` `BAD_REQUEST`, `attendee name + email required`                 | Falta el nombre o el correo, o está vacío.                                                                                             |
| `403` `FORBIDDEN`                                                     | La reserva no es de tu workspace, o está fuera de los tipos de evento de la clave.                                                     |
| `410` `GONE`, `booking is no longer active`                           | La reserva está cancelada, rechazada o se movió.                                                                                       |
| `422` `LIMIT_EXCEEDED`, `The booking has no room for more attendees.` | La reserva ya tiene 30 personas, contando una vez a cada persona y a cada invitado, o los cupos por horario del evento cuando son más. |

dCal no le envía ningún correo a la persona añadida y no dispara ningún webhook. En una reserva aceptada que ya está en tu calendario, dCal actualiza ese evento del calendario para que la persona nueva quede como invitada, y tu calendario puede enviarle su propia invitación. HubSpot, si lo conectaste, también se actualiza. Para invitar a más personas desde el principio, inclúyelas en `attendees` al crear la reserva.

***

## Ajustes del tipo de evento

Los ajustes de un tipo de evento, como su **Antelación máxima (días)**, **Redirigir después de reservar** y sus ID de seguimiento, se configuran en el panel: ningún endpoint que pueda llamar una clave los cambia. Para leer la antelación máxima y la dirección de redirección de tus tipos de evento, usa `GET /v2/event-types` de la [API compatible con Cal.com](https://docs.dapta.ai/dapta-docs-es/dcal/developers/cal-com-compatible-api.md).

***

## Idempotencia

Reservar, reprogramar y cancelar aceptan una cabecera `Idempotency-Key`: cualquier texto de 1 a 200 caracteres. dCal la recuerda para tu workspace. Si envías la misma clave de idempotencia otra vez, recibes el resultado original, sin una segunda reserva, sin un segundo correo y sin un segundo webhook.

Usa una clave de idempotencia por cada acción real, construida con algo estable de tu lado, como `crm-lead-4821-intro-call`. No reutilices una clave para una acción distinta.

***

## Errores

Los errores de abajo comparten un mismo cuerpo:

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

El `message` viene en inglés y puede cambiar. Usa el código de `error`.

| Estado | `error`                | Significado                                                                                                                                                                                                                   |
| ------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `BAD_REQUEST`          | Falta un campo o un parámetro obligatorio, por ejemplo `from, to required` o `startUtc, attendees[] required`.                                                                                                                |
| `400`  | `INTAKE_INVALID`       | Falta una respuesta a una pregunta del evento o no es válida (el mensaje nombra la pregunta), una persona tiene el correo vacío, o la hora de inicio ya pasó o está a más de 2 años.                                          |
| `400`  | `INVALID_SLOT`         | La nueva hora de una reprogramación está fuera de tu horario, no respeta la antelación mínima, pasa la antelación máxima del evento o ya pasó.                                                                                |
| `401`  | `UNAUTHENTICATED`      | `Invalid API key.`: la clave falta, es incorrecta o fue revocada.                                                                                                                                                             |
| `403`  | `FORBIDDEN`            | `Missing scope: <permiso>`, o la reserva no es de tu workspace.                                                                                                                                                               |
| `404`  | `NOT_FOUND`            | No hay ningún evento con ese `handle` y `slug`, o con ese ID.                                                                                                                                                                 |
| `409`  | `SLOT_TAKEN`           | Otra persona tiene ese horario, o está ocupado en tu calendario. Elige otro.                                                                                                                                                  |
| `409`  | `CALENDAR_UNAVAILABLE` | No se pudo leer un calendario en el que verificas conflictos, así que no se reservó ni se movió nada. La respuesta trae `Retry-After: 5`: vuelve a intentarlo después de esos segundos.                                       |
| `410`  | `GONE`                 | `Booking is no longer active.`: intentaste mover una reserva cancelada, rechazada o todavía pendiente, o cancelar una rechazada. Añadir a alguien a una reserva que ya no está activa responde `booking is no longer active`. |
| `422`  | `LIMIT_EXCEEDED`       | Añadir a alguien llevaría la reserva a más de 30 personas, o a más de los cupos por horario del evento cuando son más.                                                                                                        |
| `429`  | `RATE_LIMITED`         | Demasiadas peticiones. Mira [Límites de uso](#limites-de-uso).                                                                                                                                                                |

Envía correos válidos, zonas horarias IANA y horas en ISO 8601: un valor que la API no puede leer no recibe uno de estos códigos.

Cada respuesta trae una cabecera `X-Request-Id`. Inclúyelo cuando escribas a soporte sobre una petición.

***

## Límites de uso

Los endpoints públicos detrás de tus páginas de reservas tienen un límite por visitante: una ráfaga de **60 peticiones** que se recarga a **1 petición por segundo**. Por encima del límite responden `429 Too Many Requests` con una cabecera `Retry-After` en segundos y el cuerpo `{"error":"RATE_LIMITED","message":"Too many requests. Please slow down."}`.

Los endpoints `/v1/machine` no tienen hoy un límite publicado por clave. Construye tu integración como si lo tuvieran: cuando recibas un `429`, espera los segundos de `Retry-After`; cuando recibas un `5xx`, reintenta con una espera cada vez mayor; y envía siempre un `Idempotency-Key` para que reintentar sea seguro.

El cuerpo de cada petición tiene un límite de 100 kB.

***

## Documento OpenAPI

La API se describe a sí misma:

* **`https://api.dcal.ai/openapi.json`**: el documento OpenAPI 3.1. Apunta a él tu generador de clientes o tu cliente HTTP.
* **`https://api.dcal.ai/docs`**: la referencia de la API, una sola página interactiva hecha con ese documento, en inglés. Empieza con una introducción: la URL base, un enlace a este documento OpenAPI, cómo autenticarte con una clave, las dos API, el `cal-api-version` que pide cada operación `/v2`, los reintentos seguros con `Idempotency-Key` y el servidor MCP. Después vienen las operaciones, bajo **REST API** (los endpoints `/v1/machine` de esta página), **Cal.com-compatible API**, **Calendar availability**, **Booking page** (los endpoints públicos detrás de tus páginas de reservas y de los enlaces para gestionar) y **Health**. En el panel, **API y webhooks** > **Docs de la API** la abre en una pestaña nueva.

> **💡 Tip:** El documento y la página `/docs` también describen los endpoints `/v2`, que siguen la forma de la API v2 de Cal.com. Mira [API compatible con Cal.com](https://docs.dapta.ai/dapta-docs-es/dcal/developers/cal-com-compatible-api.md).

Para comprobar que la API funciona, llama a `GET https://api.dcal.ai/health`.

## Relacionado

* [Claves de API](https://docs.dapta.ai/dapta-docs-es/dcal/developers/api-keys.md): crea la clave que necesitan estos endpoints.
* [API compatible con Cal.com](https://docs.dapta.ai/dapta-docs-es/dcal/developers/cal-com-compatible-api.md): los endpoints `/v2`, incluidos los eventos de equipo.
* [Webhooks](https://docs.dapta.ai/dapta-docs-es/dcal/integrations/webhooks.md): entérate de las reservas hechas desde cualquier lugar, sin consultar una y otra vez.
* [Cómo se calculan los horarios libres](https://docs.dapta.ai/dapta-docs-es/dcal/calendars-and-availability/how-open-times-work.md): las reglas detrás de cada horario que devuelve la API.
* [Deja que tu agente de Dapta agende](https://docs.dapta.ai/dapta-docs-es/dcal/dapta-agents.md): la forma sin código de que un agente de IA agende.


---

# 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/dapta-docs-es/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.
