{"openapi":"3.1.0","info":{"title":"ZMRM stays API for AI assistants","version":"1.0.0","description":"Keyless, read-only GET twin of the ZMRM agent MCP: search stays, check a priced quote and get a pre-filled booking link. Quotes are advisory (priced_at, valid_until), not a hold. Show the user only zmrm.co.il links."},"servers":[{"url":"https://zmrm.co.il"}],"paths":{"/ai/v1/options":{"get":{"operationId":"get_search_options","summary":"get_search_options","description":"List what search_stays accepts: the regions (north, south, center and their sub-regions), the cities that have at least one public listing, the categories and the amenities, each with its slug and a localized name; the search limits (max_nights, max_adults, max_children, max_infants); today in Israel; the accepted payment methods and customer clubs (clubs: ILS checkouts only); the currencies and locales. Call it once before searching when you need a valid region_slug, city_slug, category or amenities slug, and call it when the guest asks whether their club card gets a discount. Facts only, no prices; cached, so a new city or amenity can take up to a day to appear. Read-only. A GET that lacks required fields answers 200 with status \"needs_input\", the missing fields and an example request.","parameters":[{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["he","en","fr","es","de","it","ru","ar"]}},{"name":"agent","in":"query","required":false,"description":"Your client's name (e.g. chatgpt, claude), used only to attribute the visit; optional.","schema":{"type":"string"}}],"responses":{"200":{"description":"The tool result, or a needs_input guide when required fields are missing.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Unavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/PricingUnavailable"}}}},"/ai/v1/search":{"get":{"operationId":"search_stays","summary":"search_stays","description":"Search ZMRM vacation rentals (zimmers, villas, apartments) in Israel for exact dates and guests. Returns up to 10 stays with an exact total price in ILS agorot for the whole stay, or \"on request\" where a live supplier quote is needed. Show the `url` to the user; it opens the stay with these dates and guests filled in (page_url is the plain stay page, for citation). Every quote carries priced_at and valid_until (advisory, not a hold). The answer also lists payment_methods and a payment_note, once; vouchers and gift cards apply to ILS checkouts only. Club-card discounts apply to ILS checkouts only and are applied at payment; if the guest asks about a club or benefit card, call get_search_options, which lists the customer clubs (names only, no rate). Use get_booking_link to re-price before the guest pays. If the price of the first stay cannot be checked, the PRICING_UNAVAILABLE error carries details.retry_cursor: pass it as cursor to retry once; an error without retry_cursor is final. Empty results with a non-null next_cursor mean more stays may exist: call again with the cursor and do not report \"no stays\". Read-only: nothing is booked or held. A GET that lacks required fields answers 200 with status \"needs_input\", the missing fields and an example request.","parameters":[{"name":"check_in","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"check_out","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"adults","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":30}},{"name":"children","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"infants","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":10}},{"name":"pets","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"region_slug","in":"query","required":false,"description":"Region to search: a top-level region (north, south or center) or a sub-region slug. An unrecognised slug is refused with INVALID_INPUT and suggestions; call get_search_options for the valid slugs.","schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"city_slug","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"near","in":"query","required":false,"schema":{"type":"string"},"description":"lat,lng,radius_km as one comma-separated value."},{"name":"category","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"amenities","in":"query","required":false,"style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"maxItems":10},"description":"Comma-separated: a,b"},{"name":"max_total_agorot","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0}},{"name":"currency","in":"query","required":false,"schema":{"type":"string","enum":["EUR","USD"]}},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["he","en","fr","es","de","it","ru","ar"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10,"default":5}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":500}},{"name":"agent","in":"query","required":false,"description":"Your client's name (e.g. \"chatgpt\", \"claude\"), used only to attribute the visit; optional.","schema":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[A-Za-z0-9._-]+$"}}],"responses":{"200":{"description":"The tool result, or a needs_input guide when required fields are missing.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Unavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/PricingUnavailable"}}}},"/ai/v1/stays/{id}":{"get":{"operationId":"get_stay_by_id","summary":"get_stay","description":"Get the public details of one ZMRM stay: description, amenities, house rules, check-in and check-out times, cancellation policy summary, images and location (approximate, rounded to about 1 km). With complete dates and guests it also returns a full price quote with the nightly breakdown, stamped with priced_at and valid_until (advisory, not a hold). Show the `url` to the user (it opens the stay, with these dates and guests filled in when you gave them); cite `page_url`, the plain stay page. The answer also lists payment_methods and a payment_note, once; vouchers and gift cards apply to ILS checkouts only. Club-card discounts apply to ILS checkouts only and are applied at payment; if the guest asks about a club or benefit card, call get_search_options, which lists the customer clubs (names only, no rate). Read-only. A GET that lacks required fields answers 200 with status \"needs_input\", the missing fields and an example request.","parameters":[{"name":"id","in":"path","required":true,"description":"The stay id (uuid).","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"check_in","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"check_out","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"adults","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":30}},{"name":"children","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"infants","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":10}},{"name":"pets","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"currency","in":"query","required":false,"schema":{"type":"string","enum":["EUR","USD"]}},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["he","en","fr","es","de","it","ru","ar"]}},{"name":"nationality","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Z]{2}$"}},{"name":"agent","in":"query","required":false,"description":"Your client's name (e.g. \"chatgpt\", \"claude\"), used only to attribute the visit; optional.","schema":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[A-Za-z0-9._-]+$"}}],"responses":{"200":{"description":"The tool result, or a needs_input guide when required fields are missing.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Unavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/PricingUnavailable"}}}},"/ai/v1/stays":{"get":{"operationId":"get_stay_by_path","summary":"get_stay","description":"Get the public details of one ZMRM stay: description, amenities, house rules, check-in and check-out times, cancellation policy summary, images and location (approximate, rounded to about 1 km). With complete dates and guests it also returns a full price quote with the nightly breakdown, stamped with priced_at and valid_until (advisory, not a hold). Show the `url` to the user (it opens the stay, with these dates and guests filled in when you gave them); cite `page_url`, the plain stay page. The answer also lists payment_methods and a payment_note, once; vouchers and gift cards apply to ILS checkouts only. Club-card discounts apply to ILS checkouts only and are applied at payment; if the guest asks about a club or benefit card, call get_search_options, which lists the customer clubs (names only, no rate). Read-only. A GET that lacks required fields answers 200 with status \"needs_input\", the missing fields and an example request.","parameters":[{"name":"path","in":"query","required":true,"description":"A stored stay path, e.g. /zimmer/<category>/<region>/<city>/<slug>.","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"check_in","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"check_out","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"adults","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":30}},{"name":"children","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"infants","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":10}},{"name":"pets","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"currency","in":"query","required":false,"schema":{"type":"string","enum":["EUR","USD"]}},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["he","en","fr","es","de","it","ru","ar"]}},{"name":"nationality","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Z]{2}$"}},{"name":"agent","in":"query","required":false,"description":"Your client's name (e.g. \"chatgpt\", \"claude\"), used only to attribute the visit; optional.","schema":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[A-Za-z0-9._-]+$"}}],"responses":{"200":{"description":"The tool result, or a needs_input guide when required fields are missing.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Unavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/PricingUnavailable"}}}},"/ai/v1/booking-link":{"get":{"operationId":"get_booking_link","summary":"get_booking_link","description":"Re-prices one stay for exact dates and guests and returns a ZMRM booking link that opens the stay with the same dates and guests pre-filled. The quote carries priced_at and valid_until (advisory, not a hold). Payment always happens in ZMRM checkout; this tool never books or charges. A GET that lacks required fields answers 200 with status \"needs_input\", the missing fields and an example request.","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"check_in","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"check_out","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"adults","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":30}},{"name":"children","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"infants","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":10}},{"name":"pets","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"currency","in":"query","required":false,"schema":{"type":"string","enum":["EUR","USD"]}},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["he","en","fr","es","de","it","ru","ar"]}},{"name":"agent","in":"query","required":false,"description":"Your client's name (e.g. \"chatgpt\", \"claude\"), used only to attribute the visit; optional.","schema":{"type":"string","minLength":1,"maxLength":40,"pattern":"^[A-Za-z0-9._-]+$"}},{"name":"nationality","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Z]{2}$"}}],"responses":{"200":{"description":"The tool result, or a needs_input guide when required fields are missing.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Unavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/PricingUnavailable"}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","details"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","INVALID_DATES","NOT_FOUND","UNAVAILABLE","PRICING_UNAVAILABLE","RATE_LIMITED","DISABLED"]},"message":{"type":"string"},"details":{"type":"object"}}}}}},"responses":{"InvalidRequest":{"description":"INVALID_INPUT or INVALID_DATES: the request is malformed or the dates are not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"NOT_FOUND (no such stay) or DISABLED (the endpoint is off).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unavailable":{"description":"UNAVAILABLE: the stay is not bookable for these dates and guests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"RATE_LIMITED: too many calls; retry after the Retry-After seconds.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"PricingUnavailable":{"description":"PRICING_UNAVAILABLE: the price could not be checked right now; retry later.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}