API Reference — Introduction

ES EN

Copy page

The Dhalinta AI Automation 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

1. Go to your panel → Settings → API & Integrations → API tokens
2. Click New token
3. Choose a descriptive name, the scopes and the calendars it will have access to
4. 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://app.dhalinta.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": "Calendar API not included in plan" }
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://app.dhalinta.com/api/calendar/v1/calendars

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

# 4. Check availability
curl -H "Authorization: Bearer mrcal_..." \
  "https://app.dhalinta.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://app.dhalinta.com/api/calendar/v1/calendars/12/appointments

---

Next step

See the full Calendar API v1 reference →.