API Reference — Introduction

ES EN

The MuseRelay API lets external applications, AI assistants and automation tools interact with calendars, appointments and availability.

Authentication

Every call to the Calendar API requires a personal calendar token.

Create a token

Go to your panel → Settings → API & Integrations → API tokens
Click New token
Choose a descriptive name, the scopes and the calendars it will have access to
Copy the token — it is only shown once

Tokens have the mrcal_ prefix. The system stores the SHA-256 hash, not the plain token.

Use the token

Authorization: Bearer mrcal_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

If the header is missing or the token is empty:

{ "error": "Bearer token required" }

If the token is invalid, inactive or expired:

{ "error": "Unauthorized" }

Rate limits

Limit	Value
Per minute	`120` requests / minute per token (default)
Configurable maximum	`3000` requests / minute
Enforced minimum	`1` request / minute
Per day	No limit unless configured; configurable per token
Per IP	No additional limit unless the token has restricted CIDRs

If the limit is exceeded: 429 Too Many Requests with a Retry-After header.

Responses include:

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

Conventions

Base URL

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

Date format

Appointments are returned as ISO 8601 strings. Each appointment includes a timezone field with the calendar's time zone.

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

Lists

Endpoint	Parameter	Default	Maximum
`GET /calendars/{calendar}/availability`	`limit`	`120`	`500`
`GET /calendars/{calendar}/appointments`	`limit`	`100`	`200`

There is no page / per_page pagination and no meta object.

Idempotency

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

Item	Value
Header	`Idempotency-Key`
TTL	`24` hours
Replay	HTTP `200` with the same cached payload
Replay header	`X-Idempotent-Replay: true`

Error responses

Token middleware errors

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

Controller errors

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

Validation and resource errors

The calendar_not_found, calendar_not_allowed, service_not_found, service_not_allowed, resource_not_found and resource_not_allowed errors use Laravel's standard format.

Available APIs

API	Base URL	Status
Calendar API v1	`/api/calendar/v1`	Available
Calendar Webhooks	Configured in the panel	Available

Quickstart — your first call in 2 minutes

# 1. Create a token in the panel → Settings → API & Integrations → API tokens

# 2. List your available calendars
curl -H "Authorization: Bearer mrcal_..." \
  https://muserelay.com/api/calendar/v1/calendars

# 3. Get the calendar's services
curl -H "Authorization: Bearer mrcal_..." \
  https://muserelay.com/api/calendar/v1/calendars/12/services

# 4. Check availability
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. Create an appointment
curl -X POST \
  -H "Authorization: Bearer mrcal_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-integration-booking-001" \
  -d '{
    "service_id": 5,
    "start_at": "2026-05-12T10:30:00+02:00",
    "customer": {
      "name": "Jane Smith",
      "phone": "+34600111222",
      "email": "jane@example.com"
    }
  }' \
  https://muserelay.com/api/calendar/v1/calendars/12/appointments

Next step

See the full Calendar API v1 reference →.