{"openapi":"3.1.0","info":{"title":"VakayMood Public Inventory API","version":"1.2.0","description":"Read-only access to live timeshare rental inventory on vakaymood.com, built for AI agents and third-party developers.\n\n- **No authentication** is required.\n- **Rate limit**: 60 requests/minute per IP. Watch the X-RateLimit-* response headers; a 429 with Retry-After is returned when exceeded.\n- **Caching**: responses carry `Cache-Control: public, s-maxage=60`, so polling more often than once a minute returns cached data.\n- **Visibility**: only listings publicly visible on the website are returned (published inventory that is not hidden, disabled, or expired).\n- **Date matching rule**: `checkin` and `checkout` define a search *window*. A listing matches when its entire stay lies inside the window (`listing.checkin >= checkin AND listing.checkout <= checkout`). Timeshare stays have fixed dates, so this returns only stays an agent can actually book. Either bound may be used on its own.\n- **Pricing semantics**: `subtotal` is charged at booking; `fees` are payable at the resort (per-day fees are pre-multiplied to whole-stay amounts); `total = subtotal + feesTotal`. All amounts are USD.\n\n**Product facts**\n\n- Listings are timeshare units at resort properties: residential-style accommodations from studios to multi-bedroom units, most with a full or partial kitchen.\n- Guests have access to the host resort's facilities; each listing enumerates its amenities.\n- Every listing has fixed check-in and check-out dates and is individually bookable at the returned URL.\n- Pricing in responses includes the nightly rate, the amount charged at booking (`subtotal`), itemized fees payable at the resort (`fees`), and the all-in `total`.\n- Every listing is verified before it goes live: the reservation is checked against the owner's confirmation document before the listing is published.","contact":{"url":"https://vakaymood.com/developers"}},"servers":[{"url":"https://vakaymood.com","description":"Production"}],"paths":{"/api/v1/availability":{"get":{"operationId":"searchAvailability","summary":"Search available inventory","description":"Returns publicly visible listings matching the given filters. Ordering is controlled by `sort` (default: check-in date, then nightly price) and is deterministic across pages. All parameters are optional and combinable; unknown parameters are ignored.","parameters":[{"name":"resort","in":"query","required":false,"description":"Restrict to one resort. Accepts a resort SEO slug (`marriotts-ko-olina-beach-club-kapolei-RR12345678`), a bare RR code (`RR12345678`), or a resort document UUID.","schema":{"type":"string","maxLength":200},"example":"marriotts-ko-olina-beach-club-kapolei-RR12345678"},{"name":"location","in":"query","required":false,"description":"Free-form place name, matched fuzzily against resort country, state, and city. Accepts a country, a state, a city, or a combination.","schema":{"type":"string","maxLength":200},"example":"Orlando Florida"},{"name":"checkin","in":"query","required":false,"description":"Start of the search window (YYYY-MM-DD). Only listings whose check-in date is on or after this date match.","schema":{"type":"string","format":"date"},"example":"2026-08-01"},{"name":"checkout","in":"query","required":false,"description":"End of the search window (YYYY-MM-DD). Only listings whose checkout date is on or before this date match. When both dates are given, checkin must be before checkout.","schema":{"type":"string","format":"date"},"example":"2026-08-31"},{"name":"sleeps","in":"query","required":false,"description":"Minimum sleeping capacity: matches units whose occupancy is >= this value.","schema":{"type":"integer","minimum":1,"maximum":50},"example":4},{"name":"max_nightly_price","in":"query","required":false,"description":"Upper bound on the nightly rate in USD. Only listings whose nightly price is less than or equal to this value match.","schema":{"type":"number","exclusiveMinimum":0},"example":300},{"name":"brand","in":"query","required":false,"description":"Normalized resort brand. Brands are derived from resort names (the backend has no brand field yet). Every returned listing has `resort.brand` equal to this value.","schema":{"type":"string","enum":["worldmark","wyndham","ritz-carlton","westin","sheraton","marriott","hilton","disney","hyatt","bluegreen"]},"example":"marriott"},{"name":"sort","in":"query","required":false,"description":"Result ordering. `start_asc` (default) orders by check-in date then nightly price; `price_asc` and `price_desc` order by nightly price ascending or descending. Every ordering uses the listing code as a final tiebreaker, so pagination is deterministic.","schema":{"type":"string","enum":["price_asc","price_desc","start_asc"],"default":"start_asc"},"example":"price_asc"},{"name":"page","in":"query","required":false,"description":"1-based page number. `page * limit` must not exceed 10,000.","schema":{"type":"integer","minimum":1,"default":1},"example":1},{"name":"limit","in":"query","required":false,"description":"Results per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"example":25}],"responses":{"200":{"description":"Matching inventory.","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed per IP per minute.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer","example":59}},"X-RateLimit-Reset":{"description":"Unix epoch seconds when the current window resets.","schema":{"type":"integer","example":1780682460}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailabilityResponse"},"example":{"results":[{"listingId":"VK04437967","title":"2 Bedroom Ocean View at Marriott's Ko Olina Beach Club","resort":{"id":"RR12345678","name":"Marriott's Ko Olina Beach Club","slug":"marriotts-ko-olina-beach-club-kapolei-RR12345678","brand":"marriott","city":"Kapolei","state":"HI","country":"USA"},"unitType":"2 Bedroom Ocean View","sleeps":8,"bedrooms":2,"checkin":"2026-08-14","checkout":"2026-08-21","nights":7,"flexibleDates":false,"lastBookableCheckin":"2026-08-10","pricing":{"nightly":285,"subtotal":1995,"fees":[{"name":"Resort fee","amount":210}],"feesTotal":210,"total":2205,"currency":"USD"},"bookingUrl":"https://vakaymood.com/listings/2-bedroom-marriotts-ko-olina-beach-club-kapolei-VK04437967"}],"pagination":{"page":1,"limit":25,"total":137},"generatedAt":"2026-07-05T18:00:00.000Z"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamError"}}}},"/api/v1/listings/{id}":{"get":{"operationId":"getListing","summary":"Get full listing detail","description":"Returns the full detail of one publicly visible listing, including cancellation terms, bed configuration, and resort amenities. Listings that are hidden, disabled, expired, or not yet published return 404.","parameters":[{"name":"id","in":"path","required":true,"description":"Listing VK code (`VK04437967`), document UUID, or full listing SEO slug (`2-bedroom-marriotts-ko-olina-beach-club-kapolei-VK04437967`).","schema":{"type":"string","maxLength":300},"example":"VK04437967"}],"responses":{"200":{"description":"Listing detail.","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed per IP per minute.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer","example":59}},"X-RateLimit-Reset":{"description":"Unix epoch seconds when the current window resets.","schema":{"type":"integer","example":1780682460}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamError"}}}},"/api/v1/resorts/{idOrSlug}":{"get":{"operationId":"getResort","summary":"Get resort detail","description":"Returns one resort with address, geo coordinates, amenities, unit types, and policies.","parameters":[{"name":"idOrSlug","in":"path","required":true,"description":"Resort RR code (`RR12345678`), document UUID, or full resort SEO slug (`marriotts-ko-olina-beach-club-kapolei-RR12345678`).","schema":{"type":"string","maxLength":300},"example":"RR12345678"}],"responses":{"200":{"description":"Resort detail.","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed per IP per minute.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer","example":59}},"X-RateLimit-Reset":{"description":"Unix epoch seconds when the current window resets.","schema":{"type":"integer","example":1780682460}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResortDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamError"}}}}},"components":{"schemas":{"AvailabilityResponse":{"type":"object","required":["results","pagination","generatedAt"],"properties":{"results":{"type":"array","description":"Matching listings, ordered per the `sort` parameter (default: check-in date then nightly price).","items":{"$ref":"#/components/schemas/Listing"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"generatedAt":{"type":"string","format":"date-time","description":"When this response was generated (responses may be CDN-cached up to 60s)."}}},"Pagination":{"type":"object","required":["page","limit","total"],"properties":{"page":{"type":"integer","description":"Current 1-based page number.","example":1},"limit":{"type":"integer","description":"Results per page.","example":25},"total":{"type":"integer","description":"Total number of listings matching the query across all pages.","example":137}}},"ResortSummary":{"type":"object","description":"Compact resort reference embedded in every listing.","properties":{"id":{"type":["string","null"],"description":"Stable resort identifier (RR code). Use with /api/v1/resorts/{idOrSlug}.","example":"RR12345678"},"name":{"type":["string","null"],"example":"Marriott's Ko Olina Beach Club"},"slug":{"type":["string","null"],"description":"SEO slug; also accepted by /api/v1/resorts/{idOrSlug} and the resort filter.","example":"marriotts-ko-olina-beach-club-kapolei-RR12345678"},"brand":{"type":["string","null"],"enum":["worldmark","wyndham","ritz-carlton","westin","sheraton","marriott","hilton","disney","hyatt","bluegreen",null],"description":"Normalized brand derived from the resort name; null for independent resorts.","example":"marriott"},"city":{"type":["string","null"],"example":"Kapolei"},"state":{"type":["string","null"],"example":"HI"},"country":{"type":["string","null"],"example":"USA"}}},"Fee":{"type":"object","required":["name","amount"],"properties":{"name":{"type":"string","description":"Fee type.","example":"Resort fee"},"amount":{"type":"number","description":"Whole-stay amount in USD (per-day fees are pre-multiplied by nights).","example":210}}},"Pricing":{"type":"object","description":"All amounts in USD. `subtotal` is charged at booking; `fees` are payable at the resort; `total` is the all-in cost of the stay.","properties":{"nightly":{"type":["number","null"],"description":"Nightly rate.","example":285},"subtotal":{"type":["number","null"],"description":"Amount due at booking (nightly x nights).","example":1995},"fees":{"type":"array","description":"Additional fees payable at the resort, as whole-stay amounts.","items":{"$ref":"#/components/schemas/Fee"}},"feesTotal":{"type":"number","description":"Sum of resort-payable fees.","example":210},"total":{"type":["number","null"],"description":"All-in stay cost: subtotal + feesTotal.","example":2205},"currency":{"type":"string","const":"USD"}}},"Listing":{"type":"object","description":"One bookable stay. Timeshare inventory has fixed dates per listing.","properties":{"listingId":{"type":"string","description":"Stable listing identifier (VK code). Use with /api/v1/listings/{id}.","example":"VK04437967"},"title":{"type":["string","null"],"example":"2 Bedroom Ocean View at Marriott's Ko Olina Beach Club"},"resort":{"$ref":"#/components/schemas/ResortSummary"},"unitType":{"type":["string","null"],"description":"Unit type name.","example":"2 Bedroom Ocean View"},"sleeps":{"type":["integer","null"],"description":"Maximum occupancy.","example":8},"bedrooms":{"type":["integer","null"],"example":2},"checkin":{"type":["string","null"],"format":"date","description":"Stay check-in date.","example":"2026-08-14"},"checkout":{"type":["string","null"],"format":"date","description":"Stay checkout date.","example":"2026-08-21"},"nights":{"type":["integer","null"],"example":7},"flexibleDates":{"type":"boolean","description":"When true, checkin/checkout describe an availability window: a stay of `nights` nights may start on any date between `checkin` and `lastBookableCheckin`.","example":false},"lastBookableCheckin":{"type":["string","null"],"format":"date","description":"Latest possible check-in date for this listing.","example":"2026-08-10"},"pricing":{"$ref":"#/components/schemas/Pricing"},"bookingUrl":{"type":["string","null"],"format":"uri","description":"Canonical vakaymood.com page where this stay can be booked.","example":"https://vakaymood.com/listings/2-bedroom-marriotts-ko-olina-beach-club-kapolei-VK04437967"}}},"Bed":{"type":"object","properties":{"type":{"type":"string","description":"Bed type.","example":"King bed"},"count":{"type":"integer","example":1}}},"Amenity":{"type":"object","properties":{"label":{"type":"string","example":"Outdoor pool"},"category":{"type":["string","null"],"example":"Pool & wellness"}}},"ListingDetail":{"allOf":[{"$ref":"#/components/schemas/Listing"},{"type":"object","description":"Extra fields returned only by /api/v1/listings/{id}.","properties":{"unitView":{"type":["string","null"],"description":"View from the unit.","example":"Ocean view"},"kitchen":{"type":["string","null"],"description":"Kitchen type.","example":"Full kitchen"},"bathrooms":{"type":["integer","null"],"example":2},"beds":{"type":"array","description":"Bed configuration of the unit.","items":{"$ref":"#/components/schemas/Bed"}},"cancellationPolicy":{"type":["string","null"],"description":"Cancellation terms applying to this listing, as human-readable text."},"amenities":{"type":"array","description":"Resort amenities available to guests of this listing.","items":{"$ref":"#/components/schemas/Amenity"}}}}]},"UnitType":{"type":"object","properties":{"name":{"type":"string","example":"2 Bedroom Ocean View"},"bedrooms":{"type":["integer","null"],"example":2},"bathrooms":{"type":["integer","null"],"example":2},"sleeps":{"type":["integer","null"],"example":8},"kitchen":{"type":["string","null"],"example":"Full kitchen"},"view":{"type":["string","null"],"example":"Ocean view"}}},"ResortDetail":{"type":"object","properties":{"id":{"type":"string","description":"Stable resort identifier (RR code).","example":"RR12345678"},"name":{"type":["string","null"],"example":"Marriott's Ko Olina Beach Club"},"slug":{"type":["string","null"],"example":"marriotts-ko-olina-beach-club-kapolei-RR12345678"},"brand":{"type":["string","null"],"enum":["worldmark","wyndham","ritz-carlton","westin","sheraton","marriott","hilton","disney","hyatt","bluegreen",null],"example":"marriott"},"description":{"type":["string","null"],"description":"Resort description."},"address":{"type":["string","null"],"example":"92-161 Waipahe Pl"},"city":{"type":["string","null"],"example":"Kapolei"},"state":{"type":["string","null"],"example":"HI"},"country":{"type":["string","null"],"example":"USA"},"zip":{"type":["string","null"],"example":"96707"},"geo":{"type":["object","null"],"description":"WGS84 coordinates.","properties":{"lat":{"type":"number","example":21.3384},"lng":{"type":"number","example":-158.1214}}},"amenities":{"type":"array","items":{"$ref":"#/components/schemas/Amenity"}},"unitTypes":{"type":"array","description":"Unit types available at this resort.","items":{"$ref":"#/components/schemas/UnitType"}},"policies":{"type":"object","properties":{"goodForChildren":{"type":["boolean","null"],"description":"Family friendly."},"allowsDogs":{"type":["boolean","null"],"description":"Dogs allowed."}}},"googleRating":{"type":["number","null"],"description":"Google Places rating (1-5).","example":4.7},"activeListings":{"type":["integer","null"],"description":"Number of currently active listings at this resort.","example":12},"priceFrom":{"type":"object","description":"Lowest nightly rate among active listings.","properties":{"nightly":{"type":["number","null"],"example":189},"currency":{"type":"string","const":"USD"}}},"websiteUrl":{"type":["string","null"],"format":"uri","description":"Canonical vakaymood.com resort page.","example":"https://vakaymood.com/resorts/marriotts-ko-olina-beach-club-kapolei-RR12345678"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_parameter","not_found","rate_limited","upstream_error"],"description":"Machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."}}}}}},"responses":{"BadRequest":{"description":"A query or path parameter failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"invalid_parameter","message":"checkin must be before checkout"}}}}},"NotFound":{"description":"No publicly visible document matches the given identifier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"not_found","message":"No public listing found for 'VK00000000'"}}}}},"RateLimited":{"description":"Rate limit exceeded. Retry after the number of seconds in Retry-After.","headers":{"X-RateLimit-Limit":{"description":"Maximum requests allowed per IP per minute.","schema":{"type":"integer","example":60}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer","example":59}},"X-RateLimit-Reset":{"description":"Unix epoch seconds when the current window resets.","schema":{"type":"integer","example":1780682460}},"Retry-After":{"description":"Seconds until the rate-limit window resets.","schema":{"type":"integer","example":30}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"rate_limited","message":"Rate limit exceeded. Try again shortly."}}}}},"UpstreamError":{"description":"The inventory backend is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"upstream_error","message":"Inventory backend is unavailable. Try again later."}}}}}}}}