Lire les disponibilités | VillaSlot Documentation

GET /api/v1/properties/{propertyId}/availability

Les créneaux libres d’une villa, pour un jour local et une durée. C’est le même moteur que celui du calendrier et de la page de réservation publique : les horaires d’ouverture, les réservations existantes et le battement entre deux shootings sont tous pris en compte.

Autorisation

Rôle dans l’organisation	Cet endpoint
`owner`	Autorisé
`admin`	Autorisé
`member`	Autorisé

Paramètres de requête

Paramètre	Type	Obligatoire	Description
`date`	chaîne	oui	Un jour local `YYYY-MM-DD` dans le fuseau horaire de l’organisation — jamais un instant
`durationMinutes`	entier	oui	La durée que vous comptez réserver

Exemple

bash

curl -H "x-api-key: $VILLASLOT_API_KEY" \
  "https://villaslot.app/api/v1/properties/1f0a…/availability?date=2026-09-12&durationMinutes=120"

Réponse

200 OK — les créneaux, sous forme d’instants, plus le fuseau horaire dans lequel ils ont été calculés.

json

{
  "success": true,
  "data": {
    "propertyId": "1f0a…",
    "date": "2026-09-12",
    "timezone": "Asia/Makassar",
    "durationMinutes": 120,
    "slots": [
      {
        "startAt": "2026-09-12T00:00:00.000Z",
        "endAt": "2026-09-12T02:00:00.000Z"
      }
    ]
  }
}

Ce qu’il refuse

422 Unprocessable Entity — date n’est pas au format YYYY-MM-DD, ou durationMinutes n’est pas un entier positif.
401 Unauthorized — clé absente ou invalide, ou clé dont le porteur a quitté l’organisation.
404 Not Found — identifiant inconnu, ou identifiant appartenant à une autre organisation. Les deux sont volontairement indiscernables.
429 Too Many Requests — plus de 120 requêtes en une minute pour cette clé.

Notes

Une liste vide ne dit pas pourquoi. Une villa fermée ce jour-là et une villa complète répondent toutes deux []. Interrogez l’endpoint de création si vous avez besoin de la raison : il nomme CLOSED, OUTSIDE_OPENING_HOURS ou OVERLAP.
Les créneaux sont renvoyés sous forme d’instants ; convertissez-les avec le champ timezone, pas avec votre propre horloge.