Get availability

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 organizationThis endpoint
ownerAllowed
adminAllowed
memberAllowed

Query parameters

ParameterTypeRequiredDescription
datestringyesA local day YYYY-MM-DD in the organization timezone — never an instant
durationMinutesintegeryesThe 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.