Get availability | VillaSlot Documentation

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

The free slots of a villa, for one local day and one duration. This is the same engine the calendar and the public booking page use: opening hours, existing bookings and the buffer between two shootings are all taken into account.

Authorization

Role in the organization	This endpoint
`owner`	Allowed
`admin`	Allowed
`member`	Allowed

Query parameters

Parameter	Type	Required	Description
`date`	string	yes	A local day `YYYY-MM-DD` in the organization timezone — never an instant
`durationMinutes`	integer	yes	The duration you intend to book

Example

bash

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

Response

200 OK — the slots, as instants, plus the timezone they were computed in.

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

What it refuses

422 Unprocessable Entity — date is not YYYY-MM-DD, or durationMinutes is not a positive integer.
401 Unauthorized — missing or invalid key, or a key whose bearer left the organization.
404 Not Found — unknown id, or an id belonging to another organization. The two are deliberately indistinguishable.
429 Too Many Requests — over 120 requests in a minute for this key.

Notes

An empty list does not say why. A villa closed that day and a villa fully booked both answer []. Ask the creation endpoint if you need the reason: it names CLOSED, OUTSIDE_OPENING_HOURS or OVERLAP.
The slots are returned as instants; convert them with the timezone field, not with your own clock.