Listings
Retrieve live availability
GET /api/v1/listings/{id}/calendar
Per-day availability, computed on request from reservations and calendar blocks. This is the one read that is not snapshot-bound: a booking taken thirty seconds ago is reflected immediately, because a stale calendar double-books a nine-month tenancy.
Path parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| id required | path | string | The listing id. It must be published. |
Query parameters
| Parameter | In | Type | Description |
|---|---|---|---|
| start | query | date | Defaults to today in the listing’s timezone. YYYY-MM-DD |
| end | query | date | Inclusive. Defaults to start + 730 days. The range may span at most 1100 days. YYYY-MM-DD |
Response
200 { days: CalendarDay[] }
CalendarDay fields
| Field | Type | Description |
|---|---|---|
| date | date | YYYY-MM-DD |
| status | enum | booked is a confirmed tenancy; reserved is held but not yet firm; unavailable is a calendar block such as a renovation; available is bookable. "available""reserved""booked""unavailable" |
| minNights | integer | The listing’s base minimum. |
| isBaseMinNights | boolean | Always true today; carried so a consumer written against per-day minimums keeps working if they ever vary. |
Errors
Every failure is { error, message }; see Errors. A missing or expired bearer is a 401 on every endpoint
but the token exchange.
| Status | error | When |
|---|---|---|
| 400 | invalid_request | A date that is not YYYY-MM-DD, end before start, or a span over 1100 days. |
| 404 | not_found | Unknown or unpublished listing. |
Notes
bookedis a confirmed tenancy;reservedis held but not yet firm;unavailableis a calendar block (renovation, owner use);availableis bookable.- Enquiries and options never block a day. Cancelling releases the days immediately.
- Check-out is exclusive. A tenancy ending on the 30th leaves the 30th available, because the handover is at noon that day.
minNightsis the listing’s base minimum andisBaseMinNightsis always true today; both are carried so a consumer written against per-day minimums keeps working if they ever vary.