{ "openapi": "3.1.0", "info": { "title": "Rental Escapes Partner API", "description": "Catalog, rates, availability, locations and inquiries for Rental Escapes partners.\n\n# Getting started\n\n1. **Get a test key.** Email partner support for a key starting `re_test_`. It reads the real catalog,\n rates and availability, and lets you send inquiries that are checked but never created, so nobody is\n contacted while you build.\n2. **Make a first call.** Send the key in the `X-RE-API-TOKEN` header:\n\n ```bash\n curl -H \"X-RE-API-TOKEN: re_test_...\" \"https://api.rentalescapes.com/v2/properties?per_page=5\"\n ```\n\n3. **Load the catalog once.** Page through `GET /properties` (up to 200 per page, follow\n `pagination.next`). For each property, fetch what you need: `GET /properties/{id}` for content,\n `/rates`, `/availability` and `/images`. Store each property's `updated` times.\n4. **Stay in sync.** At most hourly, call `GET /properties/changes?since=`.\n Re-fetch only the areas whose time moved, and drop properties reported as `removed`.\n5. **Price and send leads.** `GET /properties/{id}/quote` prices a stay. `POST /inquiries` hands a guest\n to a reservations agent; with a test key the response says `\"test\": true` and nothing is created.\n6. **Go live.** Ask for a live key (starts `re_live_`) and swap it in. Nothing else changes: same URL,\n same responses.\n\nPrefer a client? Import the [OpenAPI document](https://developers.rentalescapes.com/openapi.json)\ninto your tools, or use the [Postman collection](https://developers.rentalescapes.com/postman/rental-escapes-partner-api.postman_collection.json)\nwith its [test](https://developers.rentalescapes.com/postman/test.postman_environment.json) and\n[live](https://developers.rentalescapes.com/postman/live.postman_environment.json) environments.\n\n# Authentication\n\nEvery request carries the `X-RE-API-TOKEN` header. Keys have scopes: `properties:read` and\n`locations:read` allow `GET`, `inquiries:write` allows `POST /inquiries`. A key may be limited to an\nallow-list of properties; everything outside it behaves as if it did not exist (404, or an\nunknown-property error on inquiries). Keep keys on your servers, never in a browser or mobile app.\n\n**Test mode.** Keys starting `re_test_` use the same URL and see the real catalog, rates and\navailability, but `POST /inquiries` only validates: it returns the normal response with\n`\"test\": true` and creates nothing. Every response to a partner key carries `X-RE-Mode: test` or\n`X-RE-Mode: live`.\n\n# Errors\n\nEvery error has the same body:\n\n```json\n{ \"error\": { \"code\": \"validation_failed\", \"message\": \"Invalid inquiry.\",\n \"validation\": { \"stay.checkin\": \"Must not be in the past.\" },\n \"request_id\": \"req_7f3a9c11e2b04d5a6c8e9f01\" } }\n```\n\nBranch on `code`, which is stable: `validation_failed`, `invalid_request`, `unauthorized`,\n`forbidden`, `not_found`, `method_not_allowed`, `rate_limited`, `internal_error`. `message` is for\npeople and may change. Every response carries an `X-Request-Id` header; send your own (8-64 of\n`A-Za-z0-9._-`) to have it reused, and quote it when you contact us.\n\n# Rate limits\n\nPer key, test and live alike: about 600 requests a minute and 10,000 an hour, and about 60\n`POST /inquiries` per 10 minutes. Over a limit you get `429` with `code: rate_limited` and a\n`Retry-After` header: wait that long, then retry. A 429 never creates anything, so retrying an\ninquiry is safe. After the first full load, sync with `GET /properties/changes` rather than\nre-reading the catalog.\n\n# Versioning\n\nThe version is in the path (`/v2`). Within a version we only make additive changes:\n\n- new endpoints, new optional query parameters and new optional request fields;\n- new fields in responses;\n- new values in enums, such as a new fee `type`.\n\nBuild your client to ignore fields it does not know and to handle unknown enum values gracefully.\n\nBreaking changes (removing or renaming a field, changing a type, making a parameter required,\nchanging authentication) only ship in a new version. We announce a new version at least 90 days\nahead by email to every partner, and keep the previous version running for at least 6 months\nafter it launches.\n\n# Changelog\n\n**1.0.0 (October 2026).** First release: property catalog and detail, rates, availability,\nphotos, quotes, the change feed, the location catalog, property and general inquiries, and\ntest-mode keys.\n", "contact": { "name": "Rental Escapes partner support", "email": "support@rentalescapes.com" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.rentalescapes.com/v2", "description": "Production, API version 2" } ], "paths": { "/properties": { "get": { "tags": [ "Properties" ], "summary": "List properties", "description": "Paginated catalog of live properties (limited to the allow-list for restricted keys). Poll with `updated_since` for incremental sync.", "operationId": "listProperties", "parameters": [ { "name": "page", "in": "query", "description": "Page number, from 1.", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Page size.", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200, "minimum": 1 } }, { "name": "updated_since", "in": "query", "description": "Only properties changed at or after this instant (ISO 8601).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "location", "in": "query", "description": "Location id from GET /locations; matches the location and every descendant.", "required": false, "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "description": "Sort field; prefix with - for descending.", "required": false, "schema": { "type": "string", "default": "id", "enum": [ "id", "-id", "bedrooms", "-bedrooms", "sleeps", "-sleeps", "updated", "-updated" ] } }, { "name": "checkin", "in": "query", "description": "With checkout: only properties free for the whole stay.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "checkout", "in": "query", "description": "With checkin.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "guests", "in": "query", "description": "Minimum sleeps.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "rooms", "in": "query", "description": "Minimum bedrooms.", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "A page of properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyIndex" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/properties/changes": { "get": { "tags": [ "Properties" ], "summary": "List property changes", "description": "Lightweight change log for incremental sync. Without `since`, every live property with its area change times. With `since`, only live properties that changed in some area at or after it, plus properties that left the catalog after it (`status: removed`) so you can drop them. Refreshed hourly: poll no more often than that and pass the time of your previous run as `since`.", "operationId": "listPropertyChanges", "parameters": [ { "name": "since", "in": "query", "description": "Only changes at or after this instant (ISO 8601).", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "description": "Page number, from 1.", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "per_page", "in": "query", "description": "Page size.", "required": false, "schema": { "type": "integer", "default": 500, "maximum": 1000, "minimum": 1 } } ], "responses": { "200": { "description": "A page of changes, ordered by property id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyChanges" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/properties/{id}": { "get": { "tags": [ "Properties" ], "summary": "Get a property", "description": "Everything shown on the property page: the catalog summary (the same shape as `GET /properties`) plus descriptions, rooms and beds, amenities, policies and reviews. Rates, availability and photos have their own endpoints. Re-fetch when `updated.content` changes.", "operationId": "getProperty", "parameters": [ { "$ref": "#/components/parameters/PropertyId" } ], "responses": { "200": { "description": "Property content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/properties/{id}/rates": { "get": { "tags": [ "Properties" ], "summary": "Get rates, fees and taxes", "description": "Seasonal rate periods, the default rate, fees, taxes and rate notes: the inputs to a quote.", "operationId": "getPropertyRates", "parameters": [ { "$ref": "#/components/parameters/PropertyId" }, { "name": "from", "in": "query", "description": "Exclude periods ending before this date. Default today.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Exclude periods starting after this date. Default open.", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Rate sheet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateSheet" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/properties/{id}/availability": { "get": { "tags": [ "Properties" ], "summary": "Get booked dates", "description": "GET /properties/{id}/availability — booked date ranges for one property.", "operationId": "getPropertyAvailability", "parameters": [ { "$ref": "#/components/parameters/PropertyId" }, { "name": "from", "in": "query", "description": "Window start. Default today.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Window end. Default from + 2 years.", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Booked ranges in the window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Availability" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/properties/{id}/images": { "get": { "tags": [ "Properties" ], "summary": "Get the photo gallery", "description": "GET /properties/{id}/images — full photo gallery for one property.", "operationId": "getPropertyImages", "parameters": [ { "$ref": "#/components/parameters/PropertyId" } ], "responses": { "200": { "description": "Photos in display order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PropertyImages" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/properties/{id}/quote": { "get": { "tags": [ "Properties" ], "summary": "Price a stay", "description": "Authoritative total for a specific stay, including fees, taxes and discounts.", "operationId": "quoteProperty", "parameters": [ { "$ref": "#/components/parameters/PropertyId" }, { "name": "checkin", "in": "query", "description": "Today or later.", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "checkout", "in": "query", "description": "After checkin.", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "adults", "in": "query", "description": "Adults in the party. Used for capacity and for per-adult and per-guest fees.", "required": false, "schema": { "type": "integer", "default": 2, "maximum": 50, "minimum": 1 } }, { "name": "children", "in": "query", "description": "Children in the party. They count toward capacity and per-guest fees, and per-child fees use this number.", "required": false, "schema": { "type": "integer", "default": 0, "maximum": 50, "minimum": 0 } }, { "name": "bedrooms", "in": "query", "description": "Bedrooms to price; raised to fit the guests at two per room.", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1 } } ], "responses": { "200": { "description": "Quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/locations": { "get": { "tags": [ "Locations" ], "summary": "List locations", "description": "Flat catalog of every location with live properties beneath it (counted within the allow-list for restricted keys). About 800 rows; refresh daily. Needs `locations:read`.", "operationId": "listLocations", "responses": { "200": { "description": "Location catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocationCatalog" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/inquiries": { "post": { "tags": [ "Inquiries" ], "summary": "Submit an inquiry", "description": "Hands a stay request for the guest in `contact` to a reservations agent, who follows up by email. The inquiry is tagged with your partner source and, if your key has one, credited to your travel advisor, which carries to the booking. Needs `inquiries:write`. Property rules the agent enforces, such as a minimum stay or maximum guests, return 400 with a plain message and no field map.", "operationId": "createInquiry", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InquiryRequest" } } } }, "responses": { "201": { "description": "Inquiry created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inquiry" } } } }, "400": { "$ref": "#/components/responses/ValidationFailed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "schemas": { "AreaUpdates": { "description": "Last change to each area of the property, UTC, refreshed hourly. Re-fetch only the areas that moved: `content` → `GET /properties/{id}`, `rates` → `/rates`, `availability` → `/availability`, `images` → `/images`. Null means no change has been recorded for that area.", "required": [ "content", "rates", "availability", "images" ], "properties": { "content": { "description": "Name, description, layout, amenities, location, house rules.", "type": [ "string", "null" ], "format": "date-time" }, "rates": { "description": "Rate periods, default rate, fees, taxes, promotions, rate notes.", "type": [ "string", "null" ], "format": "date-time" }, "availability": { "description": "Bookings, holds and availability settings.", "type": [ "string", "null" ], "format": "date-time" }, "images": { "description": "Photos and videos, including their order.", "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "Availability": { "required": [ "property_id", "from", "to", "booked" ], "properties": { "property_id": { "type": "integer", "example": 553 }, "from": { "description": "Start of the window returned.", "type": "string", "format": "date", "example": "2026-10-05" }, "to": { "description": "End of the window returned.", "type": "string", "format": "date", "example": "2028-10-05" }, "booked": { "description": "Each range blocks the nights from checkin up to, not including, checkout. Ranges straddling the window are included whole.", "type": "array", "items": { "required": [ "checkin", "checkout", "checkin_full_day", "checkout_full_day", "status" ], "properties": { "checkin": { "type": "string", "format": "date", "example": "2026-12-20" }, "checkout": { "type": "string", "format": "date", "example": "2027-01-03" }, "checkin_full_day": { "description": "A new stay cannot end on this checkin day.", "type": "boolean" }, "checkout_full_day": { "description": "A new stay cannot start on this checkout day.", "type": "boolean" }, "status": { "description": "Both block the dates.", "type": "string", "enum": [ "confirmed", "hold" ] } }, "type": "object" } } }, "type": "object" }, "Error": { "required": [ "error" ], "properties": { "error": { "required": [ "code", "message", "request_id" ], "properties": { "code": { "description": "Stable, machine-readable. `validation_failed` (see `validation`), `invalid_request`, `unauthorized`, `forbidden`, `not_found`, `method_not_allowed`, `rate_limited`, `internal_error`.", "type": "string", "enum": [ "validation_failed", "invalid_request", "unauthorized", "forbidden", "not_found", "method_not_allowed", "rate_limited", "internal_error" ], "example": "validation_failed" }, "message": { "description": "Human-readable; do not match on it.", "type": "string", "example": "Invalid inquiry." }, "validation": { "description": "Present on validation failures: field (dotted path for nested fields) to message.", "type": "object", "example": { "stay.checkin": "Must not be in the past.", "contact.email": "Must be a valid email address." }, "additionalProperties": { "type": "string" } }, "request_id": { "description": "Same as the `X-Request-Id` response header. Null only on a 429 from our edge, which never reached the API; its `cf-ray` header identifies it.", "type": [ "string", "null" ], "example": "req_7f3a9c11e2b04d5a6c8e9f01" } }, "type": "object" } }, "type": "object" }, "ImageSizes": { "description": "Resized variants. Any width can be requested by appending `-{width}w` to the original URL.", "required": [ "thumb", "medium", "large" ], "properties": { "thumb": { "description": "400 px wide.", "type": "string", "format": "uri", "example": "https://cdn.rentalescapes.com/images/2f6c1a3e-7b4d-4e1a-9c2b-5d8e0f1a2b3c/silent-waters-villa-1-400w" }, "medium": { "description": "800 px wide.", "type": "string", "format": "uri", "example": "https://cdn.rentalescapes.com/images/2f6c1a3e-7b4d-4e1a-9c2b-5d8e0f1a2b3c/silent-waters-villa-1-800w" }, "large": { "description": "1600 px wide.", "type": "string", "format": "uri", "example": "https://cdn.rentalescapes.com/images/2f6c1a3e-7b4d-4e1a-9c2b-5d8e0f1a2b3c/silent-waters-villa-1-1600w" } }, "type": "object" }, "Inquiry": { "description": "The created inquiry. `property` is null on a general inquiry, `destination` null on a property inquiry.", "required": [ "id", "status", "test", "created_at", "reference", "property", "destination", "budget", "stay", "contact", "agent" ], "properties": { "id": { "type": "integer", "example": 221345 }, "status": { "description": "Always `new` on creation; a reservations agent takes it from there.", "type": "string", "enum": [ "new" ], "example": "new" }, "test": { "description": "True when sent with a `re_test_` key: the inquiry was validated and answered but not created, and nobody was notified. Test ids start at 900000000.", "type": "boolean", "example": false }, "created_at": { "type": "string", "format": "date-time", "example": "2026-10-05T14:02:11Z" }, "reference": { "description": "Your `reference`, echoed back.", "type": [ "string", "null" ], "example": "trip-991" }, "property": { "required": [ "id", "name", "url" ], "properties": { "id": { "type": "integer", "example": 553 }, "name": { "type": "string", "example": "Silent Waters Villa" }, "url": { "type": "string", "format": "uri", "example": "https://www.rentalescapes.com/rentals/luxury-villa-rentals-caribbean/jamaica/montego-bay/silent-waters-villa-553" } }, "type": [ "object", "null" ] }, "destination": { "description": "`id` and `path` are null for a free-text destination.", "required": [ "id", "name", "path" ], "properties": { "id": { "type": [ "integer", "null" ], "example": 144 }, "name": { "type": "string", "example": "St. James" }, "path": { "type": [ "array", "null" ], "items": { "type": "string" }, "example": [ "Caribbean", "Barbados", "St. James" ] } }, "type": [ "object", "null" ] }, "budget": { "properties": { "min": { "type": [ "integer", "null" ], "example": 1500 }, "max": { "type": [ "integer", "null" ], "example": 4000 } }, "type": [ "object", "null" ] }, "stay": { "required": [ "checkin", "checkout", "nights", "guests", "bedrooms" ], "properties": { "checkin": { "type": "string", "format": "date", "example": "2026-12-20" }, "checkout": { "type": "string", "format": "date", "example": "2026-12-27" }, "nights": { "type": "integer", "example": 7 }, "guests": { "required": [ "adults", "children" ], "properties": { "adults": { "type": "integer", "example": 4 }, "children": { "type": "integer", "example": 1 } }, "type": "object" }, "bedrooms": { "type": [ "integer", "null" ], "example": 3 } }, "type": "object" }, "contact": { "required": [ "first_name", "last_name", "email" ], "properties": { "first_name": { "type": "string", "example": "Ada" }, "last_name": { "type": "string", "example": "Lovelace" }, "email": { "type": "string", "format": "email", "example": "ada@example.com" } }, "type": "object" }, "agent": { "description": "The Rental Escapes reservations agent who owns the lead.", "required": [ "first_name", "last_name", "email", "phone", "extension" ], "properties": { "first_name": { "type": "string", "example": "Maria" }, "last_name": { "type": "string", "example": "Lopez" }, "email": { "type": "string", "format": "email", "example": "maria@rentalescapes.com" }, "phone": { "type": "string", "example": "1-800-208-5097" }, "extension": { "type": "string", "example": "826" } }, "type": "object" } }, "type": "object" }, "InquiryRequest": { "description": "Send `property_id` for one property, or `destination` for a general request. Exactly one of the two.", "required": [ "stay", "contact" ], "properties": { "property_id": { "description": "A live property from the catalog.", "type": "integer", "example": 553 }, "destination": { "description": "General inquiry: a catalog location id, free text, or both (the text is kept as a note).", "properties": { "id": { "description": "From `GET /locations`.", "type": "integer", "example": 144 }, "name": { "type": "string", "maxLength": 200, "example": "west coast, near Sandy Lane" } }, "type": "object" }, "stay": { "required": [ "checkin", "checkout" ], "properties": { "checkin": { "description": "Today or later.", "type": "string", "format": "date", "example": "2026-12-20" }, "checkout": { "description": "After checkin.", "type": "string", "format": "date", "example": "2026-12-27" }, "guests": { "properties": { "adults": { "type": "integer", "default": 2, "maximum": 50, "minimum": 1, "example": 4 }, "children": { "type": "integer", "default": 0, "maximum": 50, "minimum": 0, "example": 1 } }, "type": "object" }, "bedrooms": { "description": "Bedrooms wanted, for properties that rent a subset. Ignored on general inquiries.", "type": "integer", "minimum": 1, "example": 3 } }, "type": "object" }, "budget": { "description": "Nightly budget, general inquiries only.", "properties": { "min": { "type": "integer", "minimum": 0, "example": 1500 }, "max": { "description": "Not below min.", "type": "integer", "minimum": 0, "example": 4000 } }, "type": "object" }, "contact": { "description": "The traveller the stay is for, not the advisor. A returning guest is recognised by email. The inquiry is attributed to your organisation through your API key; put the advisor handling the trip in `message`.", "required": [ "first_name", "last_name", "email" ], "properties": { "first_name": { "type": "string", "maxLength": 100, "example": "Ada" }, "last_name": { "type": "string", "maxLength": 100, "example": "Lovelace" }, "email": { "type": "string", "format": "email", "example": "ada@example.com" }, "phone": { "type": "string", "maxLength": 50, "example": "+1 514 555 0100" } }, "type": "object" }, "message": { "description": "Requests, and anything the agent should know, such as the advisor handling the trip.", "type": "string", "maxLength": 5000, "example": "Celebrating an anniversary; private chef for two dinners. Advisor: Jane Smith, jane@agency.example" }, "reference": { "description": "Your own id for this lead; stored and echoed back.", "type": "string", "maxLength": 255, "example": "trip-991" } }, "type": "object" }, "LocationCatalog": { "required": [ "locations" ], "properties": { "locations": { "description": "Every location with live properties beneath it, ordered by path so a parent precedes its children.", "type": "array", "items": { "required": [ "id", "parent_id", "name", "path", "url", "property_count" ], "properties": { "id": { "description": "Accepted by the index `location` filter and as `destination.id` on inquiries.", "type": "integer", "example": 144 }, "parent_id": { "type": [ "integer", "null" ], "example": 16 }, "name": { "type": "string", "example": "St. James" }, "path": { "type": "array", "items": { "type": "string" }, "example": [ "Caribbean", "Barbados", "St. James" ] }, "url": { "type": "string", "format": "uri", "example": "https://www.rentalescapes.com/rentals/luxury-villa-rentals-caribbean/jamaica/montego-bay" }, "property_count": { "description": "Live properties here and in all descendants, exactly what `GET /properties?location={id}` returns.", "type": "integer", "example": 185 } }, "type": "object" } } }, "type": "object" }, "LocationRef": { "required": [ "id", "name", "path", "url" ], "properties": { "id": { "description": "Same id as in `GET /locations`.", "type": "integer", "example": 213 }, "name": { "type": "string", "example": "Necker Island" }, "path": { "type": "array", "items": { "type": "string" }, "example": [ "Caribbean", "British Virgin Islands (BVI)", "Necker Island" ] }, "url": { "type": "string", "format": "uri", "example": "https://www.rentalescapes.com/rentals/luxury-villa-rentals-caribbean/jamaica/montego-bay" } }, "type": "object" }, "Pagination": { "required": [ "page", "per_page", "total", "total_pages", "next" ], "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 3970 }, "total_pages": { "type": "integer", "example": 80 }, "next": { "description": "Relative URL of the next page with the same filters, or null on the last page.", "type": [ "string", "null" ], "example": "/properties?per_page=50&page=2" } }, "type": "object" }, "Policy": { "description": "`on_request`: allowed with the owner's approval. null: not stated.", "type": [ "string", "null" ], "enum": [ "yes", "no", "on_request", null ] }, "PropertyChange": { "required": [ "id", "status" ], "properties": { "id": { "type": "integer", "example": 126859 }, "status": { "description": "`live`: in the catalog, see `updated`. `removed`: no longer bookable, drop it.", "type": "string", "enum": [ "live", "removed" ] }, "updated": { "$ref": "#/components/schemas/AreaUpdates", "description": "Only when live." }, "removed_at": { "description": "Only when removed. UTC.", "type": "string", "format": "date-time" } }, "type": "object", "oneOf": [ { "required": [ "updated" ], "properties": { "status": { "type": "string", "enum": [ "live" ] } }, "type": "object" }, { "required": [ "removed_at" ], "properties": { "status": { "type": "string", "enum": [ "removed" ] } }, "type": "object" } ] }, "PropertyChanges": { "required": [ "changes", "pagination" ], "properties": { "changes": { "type": "array", "items": { "$ref": "#/components/schemas/PropertyChange" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" }, "PropertyDetail": { "description": "The catalog summary (identical to a `GET /properties` item) plus descriptive content. Text fields are null rather than empty. Rates, availability and photos have their own endpoints.", "allOf": [ { "$ref": "#/components/schemas/PropertySummary" }, { "required": [ "description", "location_description", "amenities", "amenity_notes", "staff", "inclusions", "house_rules", "rooms", "policies", "arrival", "reviews" ], "properties": { "description": { "description": "HTML.", "type": [ "string", "null" ], "example": "

A secluded nine-bedroom estate on the cliffs above Montego Bay, with an infinity pool and full staff.

" }, "location_description": { "type": [ "string", "null" ], "example": "Ten minutes from Sangster International Airport, near Rose Hall." }, "amenities": { "type": "array", "items": { "required": [ "category", "items" ], "properties": { "category": { "type": "string", "example": "General" }, "items": { "type": "array", "items": { "type": "string" }, "example": [ "Pool", "Wifi" ] } }, "type": "object" } }, "amenity_notes": { "description": "HTML.", "type": [ "string", "null" ], "example": "

Daily housekeeping; chef available on request.

" }, "staff": { "type": "array", "items": { "type": "string" }, "example": [ "Chef", "House Manager" ] }, "inclusions": { "type": [ "string", "null" ], "example": "Breakfast and daily housekeeping included." }, "house_rules": { "type": [ "string", "null" ], "example": "No events without approval. Quiet hours after 11pm." }, "rooms": { "required": [ "bedrooms", "bathrooms", "bedroom_notes", "bathroom_notes" ], "properties": { "bedrooms": { "type": "array", "items": { "required": [ "name", "type", "sleeps", "beds", "notes" ], "properties": { "name": { "type": "string", "example": "Master suite" }, "type": { "type": [ "string", "null" ], "example": null }, "sleeps": { "type": "integer" }, "beds": { "required": [ "king", "queen", "double", "single", "bunk", "sofa_bed", "crib", "child" ], "properties": { "king": { "type": "integer" }, "queen": { "type": "integer" }, "double": { "type": "integer" }, "single": { "type": "integer" }, "bunk": { "type": "integer" }, "sofa_bed": { "type": "integer" }, "crib": { "type": "integer" }, "child": { "type": "integer" } }, "type": "object" }, "notes": { "type": [ "string", "null" ], "example": "Ocean view, private terrace." } }, "type": "object" } }, "bathrooms": { "type": "array", "items": { "required": [ "name", "type", "features", "notes" ], "properties": { "name": { "type": "string", "example": "Master bathroom" }, "type": { "type": [ "string", "null" ], "example": "full" }, "features": { "type": "array", "items": { "type": "string", "enum": [ "toilet", "shower", "tub", "shower_tub_combo", "whirlpool", "bidet", "outdoor" ] } }, "notes": { "type": [ "string", "null" ], "example": "Outdoor rain shower." } }, "type": "object" } }, "bedroom_notes": { "type": [ "string", "null" ], "example": null }, "bathroom_notes": { "type": [ "string", "null" ], "example": null } }, "type": "object" }, "policies": { "description": "null when the owner has not said.", "required": [ "children", "pets", "smoking", "events", "seniors", "wheelchair_accessible", "long_term" ], "properties": { "children": { "$ref": "#/components/schemas/Policy" }, "pets": { "$ref": "#/components/schemas/Policy" }, "smoking": { "$ref": "#/components/schemas/Policy" }, "events": { "$ref": "#/components/schemas/Policy" }, "seniors": { "$ref": "#/components/schemas/Policy" }, "wheelchair_accessible": { "$ref": "#/components/schemas/Policy" }, "long_term": { "$ref": "#/components/schemas/Policy" } }, "type": "object" }, "arrival": { "required": [ "checkin_time", "checkout_time", "notes" ], "properties": { "checkin_time": { "description": "Local time, HH:MM.", "type": [ "string", "null" ], "example": "15:00" }, "checkout_time": { "type": [ "string", "null" ], "example": "12:00" }, "notes": { "type": [ "string", "null" ], "example": "The property manager meets guests on arrival." } }, "type": "object" }, "reviews": { "description": "Approved guest reviews, newest first.", "type": "array", "items": { "required": [ "author", "date", "title", "text", "rating" ], "properties": { "author": { "type": "string", "example": "Sarah M." }, "date": { "type": [ "string", "null" ], "format": "date", "example": "2026-03-14" }, "title": { "type": [ "string", "null" ], "example": "Perfect family week" }, "text": { "type": [ "string", "null" ], "example": "The staff were wonderful and the views even better than the photos." }, "rating": { "description": "Out of 5.", "type": [ "number", "null" ], "example": 5 } }, "type": "object" } } }, "type": "object" } ] }, "PropertyImages": { "required": [ "property_id", "images" ], "properties": { "property_id": { "type": "integer", "example": 553 }, "images": { "description": "In display order; the first is the cover.", "type": "array", "items": { "required": [ "id", "position", "caption", "url", "sizes", "width", "height" ], "properties": { "id": { "type": "integer", "example": 48211 }, "position": { "type": "integer", "minimum": 1, "example": 1 }, "caption": { "type": [ "string", "null" ], "example": "Infinity pool at sunset" }, "url": { "description": "Original.", "type": "string", "format": "uri", "example": "https://cdn.rentalescapes.com/images/2f6c1a3e-7b4d-4e1a-9c2b-5d8e0f1a2b3c/silent-waters-villa-1" }, "sizes": { "$ref": "#/components/schemas/ImageSizes" }, "width": { "type": [ "integer", "null" ], "example": 1920 }, "height": { "type": [ "integer", "null" ], "example": 1080 } }, "type": "object" } } }, "type": "object" }, "PropertyIndex": { "required": [ "properties", "pagination" ], "properties": { "properties": { "type": "array", "items": { "$ref": "#/components/schemas/PropertySummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" }, "PropertySummary": { "required": [ "id", "name", "type", "url", "updated_at", "updated", "bedrooms", "bathrooms", "sleeps", "rating", "latitude", "longitude", "location", "image" ], "properties": { "id": { "type": "integer", "example": 117388 }, "name": { "type": "string", "example": "Necker Island" }, "type": { "type": "string", "example": "villa" }, "url": { "description": "Public page on rentalescapes.com.", "type": "string", "format": "uri", "example": "https://www.rentalescapes.com/rentals/luxury-villa-rentals-caribbean/jamaica/montego-bay/silent-waters-villa-553" }, "updated_at": { "description": "Last change of any kind, UTC. Use with `updated_since`; see `updated` for which area changed.", "type": "string", "format": "date-time" }, "updated": { "$ref": "#/components/schemas/AreaUpdates" }, "bedrooms": { "type": "integer", "example": 24 }, "bathrooms": { "type": "integer", "example": 20 }, "sleeps": { "type": "integer", "example": 48 }, "rating": { "description": "Average review rating out of 5, one decimal.", "type": [ "number", "null" ], "example": 4.8 }, "latitude": { "type": [ "number", "null" ], "example": 18.44104 }, "longitude": { "type": [ "number", "null" ], "example": -77.98475 }, "location": { "$ref": "#/components/schemas/LocationRef" }, "image": { "description": "Cover photo, or null when none is uploaded.", "required": [ "caption", "url", "sizes" ], "properties": { "caption": { "type": [ "string", "null" ], "example": "Infinity pool at sunset" }, "url": { "type": "string", "format": "uri", "example": "https://cdn.rentalescapes.com/images/2f6c1a3e-7b4d-4e1a-9c2b-5d8e0f1a2b3c/silent-waters-villa-1" }, "sizes": { "$ref": "#/components/schemas/ImageSizes" } }, "type": [ "object", "null" ] } }, "type": "object" }, "Quote": { "description": "Price for a stay in the property currency. When `price_on_request` is true the property has no published total: `totals`, `average_nightly_rate`, `tax_rate` and `accuracy` are null and `rate_range` gives the nightly range instead.", "required": [ "property_id", "currency", "price_on_request", "stay", "totals", "average_nightly_rate", "tax_rate", "accuracy", "rate_range" ], "properties": { "property_id": { "type": "integer", "example": 553 }, "currency": { "required": [ "code", "symbol" ], "properties": { "code": { "type": "string", "example": "USD" }, "symbol": { "type": "string", "example": "$" } }, "type": "object" }, "price_on_request": { "type": "boolean", "example": false }, "stay": { "required": [ "checkin", "checkout", "nights", "guests", "bedrooms" ], "properties": { "checkin": { "type": "string", "format": "date", "example": "2026-12-20" }, "checkout": { "type": "string", "format": "date", "example": "2026-12-27" }, "nights": { "type": "integer", "example": 7 }, "guests": { "required": [ "adults", "children" ], "properties": { "adults": { "type": "integer", "example": 4 }, "children": { "type": "integer", "example": 1 } }, "type": "object" }, "bedrooms": { "description": "Bedrooms priced: the requested count, raised to fit the guests at two per room, rounded up to the nearest rate tier.", "type": [ "integer", "null" ], "example": 3 } }, "type": "object" }, "totals": { "required": [ "rate", "discounts", "fees", "taxes", "total", "refundable_deposits", "total_payable" ], "properties": { "rate": { "description": "Accommodation for all nights.", "type": "number", "example": 26901 }, "discounts": { "description": "Promotions applied, subtracted from the total.", "type": "number", "example": 0 }, "fees": { "description": "Non-refundable fees.", "type": "number", "example": 299 }, "taxes": { "type": "number", "example": 2690.1 }, "total": { "description": "rate − discounts + fees + taxes.", "type": "number", "example": 29890.1 }, "refundable_deposits": { "description": "Returned after the stay.", "type": "number", "example": 0 }, "total_payable": { "description": "total + refundable_deposits.", "type": "number", "example": 29890.1 } }, "type": [ "object", "null" ] }, "average_nightly_rate": { "type": [ "number", "null" ], "example": 3843 }, "tax_rate": { "description": "Combined tax percentage.", "type": [ "number", "null" ], "example": 10 }, "accuracy": { "description": "`exact`: every night has a published rate. `estimated`: some nights use the prior year's rate. `incomplete`: some nights have no rate and are excluded from the total; ask an agent.", "type": [ "string", "null" ], "enum": [ "exact", "estimated", "incomplete", null ] }, "rate_range": { "required": [ "min", "max" ], "properties": { "min": { "type": "number", "example": 2853 }, "max": { "type": "number", "example": 4250 } }, "type": [ "object", "null" ] } }, "type": "object" }, "RateSheet": { "required": [ "property_id", "currency", "from", "to", "rates", "default_rate", "fees", "taxes", "notes" ], "properties": { "property_id": { "type": "integer", "example": 553 }, "currency": { "required": [ "code", "symbol" ], "properties": { "code": { "type": "string", "example": "USD" }, "symbol": { "type": "string", "example": "$" } }, "type": "object" }, "from": { "description": "Start of the window returned.", "type": "string", "format": "date", "example": "2026-10-05" }, "to": { "description": "End of the window returned, or null when open-ended.", "type": [ "string", "null" ], "format": "date", "example": null }, "rates": { "description": "Seasonal periods. Several periods can share dates for different bedroom counts; use the smallest `rooms` at least the bedrooms needed.", "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 90412 }, "name": { "type": "string", "example": "Low Season: 1 - 7 people" }, "start_date": { "type": "string", "format": "date", "example": "2027-04-15" }, "end_date": { "type": "string", "format": "date", "example": "2027-12-14" }, "rooms": { "description": "Bedrooms this price covers.", "type": "integer", "example": 4 }, "nightly": { "type": [ "number", "null" ], "example": 2853 }, "weekly": { "description": "Divide by 7 for a nightly figure.", "type": [ "number", "null" ] }, "monthly": { "description": "Divide by 30 for a nightly figure.", "type": [ "number", "null" ] }, "min_stay": { "description": "Minimum nights.", "type": [ "integer", "null" ], "example": 5 }, "balance_days": { "description": "Days before arrival the balance is due.", "type": [ "integer", "null" ], "example": 60 }, "currency": { "type": "string", "example": "USD" }, "cancellation_policy": { "required": [ "name", "description" ], "properties": { "name": { "type": "string", "example": "Standard" }, "description": { "type": "string", "example": "Deposit refundable until 60 days before arrival, less a 10% fee." } }, "type": [ "object", "null" ] } }, "type": "object" } }, "default_rate": { "description": "Fallback when no period covers a date. No dates.", "properties": { "id": { "type": "integer", "example": 90400 }, "name": { "type": "string", "example": "Default" }, "rooms": { "type": "integer", "example": 9 }, "nightly": { "type": [ "number", "null" ], "example": 4250 }, "weekly": { "type": [ "number", "null" ], "example": null }, "monthly": { "type": [ "number", "null" ], "example": null }, "min_stay": { "type": [ "integer", "null" ], "example": 5 }, "balance_days": { "type": [ "integer", "null" ], "example": 60 }, "currency": { "type": "string", "example": "USD" } }, "type": [ "object", "null" ] }, "fees": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "Damage Waiver" }, "description": { "type": [ "string", "null" ], "example": "Covers accidental damage up to $2,500." }, "amount": { "type": "number", "example": 299 }, "currency": { "type": "string", "example": "USD" }, "type": { "description": "How `amount` applies: once per stay, per night, per guest, per adult, per child, or per guest per night.", "type": "string", "enum": [ "flat", "daily", "guest", "adult", "child", "guest daily" ], "example": "flat" }, "type_text": { "type": "string", "example": "per night" }, "refundable": { "description": "Deposit returned after the stay.", "type": "boolean" }, "taxable": { "description": "Taxes apply to this fee.", "type": "boolean" } }, "type": "object" } }, "taxes": { "type": "array", "items": { "properties": { "name": { "type": "string", "example": "General Consumption Tax" }, "rate": { "description": "Percentage of the rate plus taxable fees.", "type": "number", "example": 10 }, "description": { "type": [ "string", "null" ], "example": null } }, "type": "object" } }, "notes": { "description": "Free-text rate notes; may contain HTML.", "type": [ "string", "null" ], "example": "Holiday weeks (Dec 20 - Jan 5) require a 7-night minimum." } }, "type": "object" } }, "responses": { "Unauthorized": { "description": "Missing or unknown key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The key lacks the scope for this route or method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Unknown or unpublished property, or outside the key's allow-list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationFailed": { "description": "Invalid input. `error.validation` maps each offending field (dotted path for nested fields) to a message; every problem is reported at once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Too many requests for this key. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServerError": { "description": "Something failed on our side. The message is always generic; quote `error.request_id` (also the `X-Request-Id` header) when reporting it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": { "PropertyId": { "name": "id", "in": "path", "description": "Property id from the catalog.", "required": true, "schema": { "type": "integer", "minimum": 1 }, "example": 553 } }, "securitySchemes": { "apiKey": { "type": "apiKey", "description": "Partner key issued by Rental Escapes: `re_live_…` for production, `re_test_…` for test mode.", "name": "X-RE-API-TOKEN", "in": "header" } } }, "security": [ { "apiKey": [] } ], "tags": [ { "name": "Properties", "description": "Catalog, per-property detail, rates, availability and photos." }, { "name": "Locations", "description": "Destination catalog with ids." }, { "name": "Inquiries", "description": "Stay requests handed to a reservations agent." } ] }