API Reference — Introducción

La API de MuseRelay permite a aplicaciones externas, asistentes de IA y herramientas de automatización interactuar con calendarios, citas y disponibilidad.

Autenticación

Todas las llamadas a la Calendar API requieren un token personal de calendario.

Crear un token

Entra en tu panel → Ajustes → API e Integraciones → Tokens de API
Haz clic en Nuevo token
Elige un nombre descriptivo, los scopes y los calendarios a los que tendrá acceso
Copia el token — solo se muestra una vez

Los tokens tienen el prefijo mrcal_. El sistema guarda el hash SHA-256, no el token en claro.

Usar el token

Authorization: Bearer mrcal_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Si la cabecera falta o el token está vacío:

{ "error": "Bearer token required" }

Si el token es inválido, inactivo o caducado:

{ "error": "Unauthorized" }

Rate limits

Límite	Valor
Por minuto	`120` requests / minuto por token (por defecto)
Máximo configurable	`3000` requests / minuto
Mínimo aplicado	`1` request / minuto
Por día	Sin límite si no está configurado; configurable por token
Por IP	Sin límite adicional salvo que el token tenga CIDRs restringidos

Si se supera el límite: 429 Too Many Requests con cabecera Retry-After.

Las respuestas incluyen:

Cache-Control: no-store, max-age=0
X-Request-Id: mrcal_req_...
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119

Convenciones

URL base

https://muserelay.com/api/calendar/v1

Formato de fechas

Las citas se devuelven como strings ISO 8601. Cada cita incluye el campo timezone con la zona horaria del calendario.

2026-05-12T10:30:00+02:00

Listas

Endpoint	Parámetro	Por defecto	Máximo
`GET /calendars/{calendar}/availability`	`limit`	`120`	`500`
`GET /calendars/{calendar}/appointments`	`limit`	`100`	`200`

No hay paginación page / per_page ni objeto meta.

Idempotencia

POST /api/calendar/v1/calendars/{calendar}/appointments
Idempotency-Key: retell-call-abc123-slot-20260512-1030

Punto	Valor
Cabecera	`Idempotency-Key`
TTL	`24` horas
Replay	HTTP `200` con el mismo payload cacheado
Cabecera en replay	`X-Idempotent-Replay: true`

Respuestas de error

Errores del middleware de token

HTTP	Body
`401`	`{ "error": "Bearer token required" }`
`401`	`{ "error": "Unauthorized" }`
`403`	`{ "error": "IP not allowed for token" }`
`403`	`{ "error": "Insufficient scope" }`
`429`	`{ "error": "Too many requests" }`
`429`	`{ "error": "Daily token limit exceeded" }`

Errores del controlador

HTTP	Body
`422`	`{ "message": "to_must_be_after_from" }`
`422`	`{ "message": "slot_unavailable" }`

Errores de validación y recursos

Los errores calendar_not_found, calendar_not_allowed, service_not_found, service_not_allowed, resource_not_found y resource_not_allowed usan el formato estándar de Laravel.

APIs disponibles

API	Base URL	Estado
Calendar API v1	`/api/calendar/v1`	Disponible
Calendar Webhooks	Configuración en panel	Disponible

Quickstart — primera llamada en 2 minutos

# 1. Crear token en el panel → Ajustes → API e Integraciones → Tokens de API

# 2. Ver tus calendarios disponibles
curl -H "Authorization: Bearer mrcal_..." \
  https://muserelay.com/api/calendar/v1/calendars

# 3. Consultar servicios del calendario
curl -H "Authorization: Bearer mrcal_..." \
  https://muserelay.com/api/calendar/v1/calendars/12/services

# 4. Consultar disponibilidad
curl -H "Authorization: Bearer mrcal_..." \
  "https://muserelay.com/api/calendar/v1/calendars/12/availability?service_id=5&from=2026-05-12&to=2026-05-16&limit=20"

# 5. Crear una cita
curl -X POST \
  -H "Authorization: Bearer mrcal_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mi-integracion-reserva-001" \
  -d '{
    "service_id": 5,
    "start_at": "2026-05-12T10:30:00+02:00",
    "customer": {
      "name": "Ana Pérez",
      "phone": "+34600111222",
      "email": "ana@example.com"
    }
  }' \
  https://muserelay.com/api/calendar/v1/calendars/12/appointments

Siguiente paso

Consulta la referencia completa de la Calendar API v1 →.