{"openapi":"3.1.0","info":{"title":"Stay Hozho Agent API","version":"1.0.0","description":"Agent-safe property discovery, live availability, quotes, and secure checkout handoff for HÓZHÓ Scottsdale. This API never accepts card data and does not let agents finalize reservations.","contact":{"name":"HÓZHÓ Scottsdale","email":"info@stayhozho.com"}},"servers":[{"url":"https://stayhozho.com/api/v1","description":"Production"}],"externalDocs":{"description":"Agent integration guide","url":"https://stayhozho.com/developers/agents"},"paths":{"/health":{"get":{"operationId":"getAgentApiHealth","summary":"Get service status and safety boundaries","responses":{"200":{"description":"Service status"}}}},"/properties":{"get":{"operationId":"listProperties","summary":"Browse the public Stay Hozho catalog","parameters":[{"name":"query","in":"query","schema":{"type":"string","maxLength":160}},{"name":"guests","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":1}},{"name":"bedrooms","in":"query","schema":{"type":"integer","minimum":0}},{"name":"amenity","in":"query","description":"Repeat this parameter or provide comma-separated amenities.","schema":{"type":"array","items":{"type":"string"}}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":20,"default":10}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated property results without live availability","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/properties/{property_id}":{"get":{"operationId":"getProperty","summary":"Get complete public details for one property","parameters":[{"name":"property_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Property details","content":{"application/json":{"schema":{"type":"object","required":["property"],"properties":{"property":{"$ref":"#/components/schemas/Property"}}}}}},"404":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/search":{"post":{"operationId":"searchProperties","summary":"Search properties and optionally check exact live availability","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"Available and unconfirmed matches. Confirmed unavailable properties are omitted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/quotes":{"post":{"operationId":"getQuote","summary":"Get an exact Guesty-backed quote or clearly labeled preview","description":"A confirmed quote may create a temporary quote in Guesty. It never charges a card or creates a reservation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StayRequest"}}}},"responses":{"200":{"description":"Confirmed quote or preview estimate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/checkout-sessions":{"post":{"operationId":"createCheckoutSession","summary":"Create a short-lived human-reviewed checkout link","description":"The returned link expires after 15 minutes. Opening it does not book or charge anything.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/StayRequest"},{"type":"object","properties":{"quote_id":{"type":"string","maxLength":200}}}]}}}},"responses":{"201":{"description":"Secure checkout handoff","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSession"}}}},"400":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}},"StayRequest":{"type":"object","additionalProperties":false,"required":["property_id","check_in","check_out","guests"],"properties":{"property_id":{"type":"string"},"check_in":{"type":"string","format":"date"},"check_out":{"type":"string","format":"date"},"guests":{"type":"integer","minimum":1,"maximum":100}}},"SearchRequest":{"type":"object","additionalProperties":false,"properties":{"check_in":{"type":"string","format":"date"},"check_out":{"type":"string","format":"date"},"guests":{"type":"integer","minimum":1,"maximum":100,"default":1},"bedrooms":{"type":"integer","minimum":0,"maximum":50},"amenities":{"type":"array","maxItems":20,"items":{"type":"string"}},"query":{"type":"string","maxLength":160},"limit":{"type":"integer","minimum":1,"maximum":20,"default":10},"cursor":{"type":"string"}}},"Image":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"thumbnail_url":{"type":"string","format":"uri"},"caption":{"type":"string"}}},"Property":{"type":"object","required":["id","slug","name","canonical_url","summary","bedrooms","bathrooms","beds","sleeps","amenities","images","location","stay_rules","source_updated_at"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"canonical_url":{"type":"string","format":"uri"},"summary":{"type":"string"},"description":{"type":"string"},"property_type":{"type":"string"},"room_type":{"type":"string"},"bedrooms":{"type":"number"},"bathrooms":{"type":"number"},"beds":{"type":"number"},"sleeps":{"type":"number"},"amenities":{"type":"array","items":{"type":"string"}},"hero_image":{"type":"string","format":"uri"},"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"video_url":{"type":"string","format":"uri"},"location":{"type":"object","properties":{"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"}}},"stay_rules":{"type":"object","properties":{"minimum_nights":{"type":"number"},"maximum_nights":{"type":"number"},"check_in_time":{"type":"string"},"check_out_time":{"type":"string"},"house_rules":{"type":"string"},"notes":{"type":"string"}}},"source_updated_at":{"type":"string","format":"date-time"}}},"SearchResponse":{"type":"object","required":["results","total","next_cursor","query","warnings"],"properties":{"results":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Property"},{"type":"object","required":["availability"],"properties":{"availability":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["available","unavailable","unknown","not_checked"]},"check_in":{"type":"string","format":"date"},"check_out":{"type":"string","format":"date"},"checked_at":{"type":"string","format":"date-time"}}}}}]}},"total":{"type":"integer"},"next_cursor":{"type":["string","null"]},"query":{"type":"object"},"warnings":{"type":"array","items":{"type":"string"}}}},"Quote":{"type":"object","required":["property_id","property_name","check_in","check_out","guests","total","currency","price_type","checkout_ready","breakdown","property_url","checked_at","notice"],"properties":{"quote_id":{"type":"string"},"rate_plan_id":{"type":"string"},"property_id":{"type":"string"},"property_name":{"type":"string"},"check_in":{"type":"string","format":"date"},"check_out":{"type":"string","format":"date"},"guests":{"type":"integer"},"total":{"type":"number"},"currency":{"type":"string"},"price_type":{"type":"string","enum":["confirmed_quote","preview_estimate"]},"checkout_ready":{"type":"boolean"},"breakdown":{"type":"array","items":{"type":"object","required":["title","amount"],"properties":{"title":{"type":"string"},"amount":{"type":"number"}}}},"property_url":{"type":"string","format":"uri"},"checked_at":{"type":"string","format":"date-time"},"notice":{"type":"string"}}},"CheckoutSession":{"type":"object","required":["checkout_url","expires_at","property_id","property_name","check_in","check_out","guests","requires_human_payment","notice"],"properties":{"checkout_url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"},"property_id":{"type":"string"},"property_name":{"type":"string"},"check_in":{"type":"string","format":"date"},"check_out":{"type":"string","format":"date"},"guests":{"type":"integer"},"requires_human_payment":{"type":"boolean","const":true},"notice":{"type":"string"}}}}}}