{"openapi":"3.1.0","info":{"title":"First Chair Destinations agent API","version":"1","description":"Vacation homes in US mountain, ski, lake and coastal towns. Find homes, price a stay, read the terms, and hand the traveler a link to book on firstchair.com. Read-only: it cannot hold, book or pay; the traveler books in a browser from the link given.\n\nPrice contract: if stay.price is \"live\", stay.total is what the checkout charges at stay.as_of and book_at is the reservation page with the stay filled in; no quote or link call is needed. If stay.price is \"indicative\", call quote before stating a final price. Prices are US dollars; per_night and total_before_taxes include all fees and match the home's page; taxes are added at checkout.\n\nThe same tools are offered in the page through WebMCP, and the site map for agents is https://www.firstchair.com/llms.txt.","contact":{"name":"First Chair Destinations","url":"https://www.firstchair.com/contact"}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"example":{"code":"not_found","message":"no home with that id"},"properties":{"code":{"type":"string","enum":["bad_request","not_found","party_does_not_fit","stay_too_long","upstream","unavailable"],"description":"What went wrong, stable across versions: branch on this."},"message":{"type":"string","description":"One sentence for a person, saying what to change."}}}}},"Home":{"type":"object","required":["id","name","market","state","type","bedrooms","studio","baths","sleeps","children_allowed","pets_allowed","max_pets","min_renter_age","rating","reviews","ski_passes","nearest_lift","photo"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"market":{"type":"string"},"state":{"type":["string","null"]},"type":{"type":["string","null"]},"bedrooms":{"type":["integer","null"],"description":"0 with studio true is a studio; null means not in our listing."},"studio":{"type":"boolean"},"baths":{"type":["number","null"]},"sleeps":{"type":["integer","null"]},"children_allowed":{"type":"boolean"},"pets_allowed":{"type":"boolean"},"max_pets":{"type":["integer","null"],"description":"0 when pets are not allowed; null when allowed with no stated limit."},"min_renter_age":{"type":["integer","null"]},"rating":{"type":["number","null"]},"reviews":{"type":"integer"},"ski_passes":{"type":"object","required":["epic","ikon"],"properties":{"epic":{"type":"boolean"},"ikon":{"type":"boolean"}}},"nearest_lift":{"oneOf":[{"type":"object","required":["base","miles","measure"],"properties":{"base":{"type":"string"},"miles":{"type":"number"},"measure":{"type":"string"}}},{"type":"null"}]},"photo":{"type":["string","null"]}},"description":"A home as find and home return it. null means the fact is not in our listing."},"FindHome":{"allOf":[{"$ref":"#/components/schemas/Home"},{"type":"object","required":["stay","book_at"],"properties":{"stay":{"oneOf":[{"type":"object","required":["nights","total","price"],"properties":{"nights":{"type":"integer"},"per_night":{"type":["number","null"],"description":"Nightly rate with all fees, rounded to whole dollars as the home's page shows it."},"total_before_taxes":{"type":["number","null"],"description":"The stay with all fees, before taxes, to the cent."},"taxes":{"type":["number","null"]},"total":{"type":"number","description":"What the card is charged, US dollars."},"price_basis":{"type":"string","description":"How the figures relate, in one sentence."},"price":{"type":"string","enum":["live","indicative"],"description":"live: total is what the checkout charges at as_of. indicative: call quote before stating a final price."},"as_of":{"type":"string","format":"date-time","description":"Present when price is live."}}},{"type":"null"}],"description":"null when no dates were given."},"book_at":{"type":"string","format":"uri","description":"The reservation page with the stay and party filled in."}}}]},"FindResponse":{"type":"object","required":["as_of","place","stay","party","matched_homes","searched","page","showing","results","notes"],"properties":{"as_of":{"type":"string","format":"date-time"},"place":{"type":"string"},"stay":{"oneOf":[{"type":"object","required":["check_in","check_out","nights"],"properties":{"check_in":{"type":"string","format":"date"},"check_out":{"type":"string","format":"date"},"nights":{"type":"integer"}}},{"type":"null"}]},"party":{"type":"object","required":["adults","children","pets"],"properties":{"adults":{"type":"integer"},"children":{"type":"integer"},"pets":{"type":"integer"}}},"matched_homes":{"type":"integer"},"free_for_dates":{"type":["integer","null"]},"availability_checked":{"type":["boolean","null"]},"priced_homes":{"type":["integer","null"]},"bookable_homes":{"type":["integer","null"]},"still_pricing":{"type":["integer","null"],"description":"Homes still being priced when the answer went out; 0 is a complete answer."},"notice":{"type":"string","description":"Present when still_pricing is above 0."},"searched":{"type":"string","description":"What the place was read as."},"min_bedrooms":{"type":["integer","null"]},"home_type":{"type":["string","null"],"enum":["home","condo","townhouse",null]},"page":{"type":"integer"},"limit_note":{"type":"string","description":"Present when limit was capped at 16."},"showing":{"type":"object","required":["from","to","of"],"properties":{"from":{"type":"integer"},"to":{"type":"integer"},"of":{"type":"integer"}}},"results":{"type":"array","items":{"$ref":"#/components/schemas/FindHome"}},"notes":{"type":"string"}}},"QuoteResponse":{"oneOf":[{"type":"object","required":["as_of","home_id","stay","party","available","per_night","total_before_taxes","taxes","total","price_basis","payment_schedule","trip_protection","price","price_note","book_at"],"properties":{"as_of":{"type":"string","format":"date-time"},"home_id":{"type":"string"},"stay":{"type":"object","required":["check_in","check_out","nights"],"properties":{"check_in":{"type":"string","format":"date"},"check_out":{"type":"string","format":"date"},"nights":{"type":"integer"}}},"party":{"type":"object","required":["adults","children","pets"],"properties":{"adults":{"type":"integer"},"children":{"type":"integer"},"pets":{"type":"integer"}}},"available":{"const":true},"per_night":{"type":["number","null"],"description":"Nightly rate with all fees, rounded to whole dollars as the home's page shows it."},"total_before_taxes":{"type":["number","null"],"description":"The stay with all fees, before taxes, to the cent."},"taxes":{"type":["number","null"]},"total":{"type":"number","description":"What the card is charged, US dollars."},"price_basis":{"type":"string","description":"How the figures relate, in one sentence."},"payment_schedule":{"type":"array","items":{"type":"object","required":["due","amount","when"],"properties":{"due":{"type":"string","format":"date"},"amount":{"type":"number"},"when":{"type":"string","enum":["at_booking","later"]}}}},"trip_protection":{"oneOf":[{"type":"object","required":["premium","optional"],"properties":{"premium":{"type":"number"},"optional":{"const":true}}},{"type":"null"}]},"price":{"const":"live"},"price_note":{"type":"string"},"book_at":{"type":"string","format":"uri"}}},{"type":"object","required":["as_of","home_id","stay","party","available","reason"],"properties":{"as_of":{"type":"string","format":"date-time"},"home_id":{"type":"string"},"stay":{"type":"object","required":["check_in","check_out","nights"],"properties":{"check_in":{"type":"string","format":"date"},"check_out":{"type":"string","format":"date"},"nights":{"type":"integer"}}},"party":{"type":"object","required":["adults","children","pets"],"properties":{"adults":{"type":"integer"},"children":{"type":"integer"},"pets":{"type":"integer"}}},"available":{"const":false},"reason":{"type":"string"}}}],"discriminator":{"propertyName":"available"}},"HomeResponse":{"allOf":[{"$ref":"#/components/schemas/Home"},{"type":"object","required":["sqft","rooms","building","parking","amenities","house_rules","description","page","notes"],"properties":{"sqft":{"type":["integer","null"]},"rooms":{"oneOf":[{"type":"array","items":{"type":"object","required":["name","details"],"properties":{"name":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}},{"type":"null"}]},"building":{"type":["string","null"]},"parking":{"type":["string","null"]},"amenities":{"type":"array","items":{"type":"string"}},"house_rules":{"type":"array","items":{"type":"string"}},"description":{"type":["string","null"],"description":"Plain text, at most 2,000 characters."},"page":{"type":"string","format":"uri"},"notes":{"type":"string"}}}]},"TermsResponse":{"type":"object","required":["agreement","cancellation_policy","travel_insurance","max_stay_nights","longer_stays","contact","home","unit_specific_terms","notes"],"properties":{"agreement":{"type":"object","required":["title","updated","url"],"properties":{"title":{"type":"string"},"updated":{"type":["string","null"]},"url":{"type":"string","format":"uri"}}},"cancellation_policy":{"type":"array","items":{"type":"string"},"description":"Quoted from the agreement."},"travel_insurance":{"type":"array","items":{"type":"string"},"description":"Quoted from the agreement."},"max_stay_nights":{"type":["integer","null"]},"longer_stays":{"type":"string"},"contact":{"type":"object","required":["phone","phone_note","email","page"],"properties":{"phone":{"type":["string","null"]},"phone_note":{"type":["string","null"]},"email":{"type":["string","null"]},"page":{"type":"string","format":"uri"}}},"home":{"oneOf":[{"type":"object","required":["id","sleeps","children_allowed","pets_allowed","max_pets","min_renter_age","house_rules"],"properties":{"id":{"type":"string"},"sleeps":{"type":["integer","null"]},"children_allowed":{"type":"boolean"},"pets_allowed":{"type":"boolean"},"max_pets":{"type":["integer","null"]},"min_renter_age":{"type":["integer","null"]},"house_rules":{"type":"array","items":{"type":"string"}}}},{"type":"null"}],"description":"null when no home_id was given."},"unit_specific_terms":{"type":"string"},"notes":{"type":"string"}}},"LinkResponse":{"type":"object","required":["book_at","note"],"properties":{"book_at":{"type":"string","format":"uri"},"note":{"type":"string"}}}}},"tags":[{"name":"Find and price","description":"Homes for a stay, with the price the checkout charges."},{"name":"Homes","description":"One home's facts and the terms the traveler agrees to."},{"name":"Booking","description":"The reservation page for the traveler to open. Nothing here books or pays."}],"servers":[{"url":"https://www.firstchair.com/api/agent/v1"}],"paths":{"/find":{"get":{"operationId":"find","tags":["Find and price"],"summary":"Homes that can be booked for a stay, the first six priced live","description":"With dates, homes that can be booked for exactly those nights, cheapest first unless near_lifts is set; the first six shown carry the live checkout price and book_at. Without dates, homes to consider.","parameters":[{"name":"place","in":"query","required":true,"schema":{"type":"string"},"description":"A town, resort or mountain, e.g. steamboat, big-sky, teton-village."},{"name":"check_in","in":"query","required":false,"schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"check_out","in":"query","required":false,"schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"adults","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":40,"default":2},"description":"Guests 13 and over."},{"name":"children","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":30,"default":0},"description":"Guests aged 3 to 12."},{"name":"pets","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Dogs travelling with the party."},{"name":"min_bedrooms","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":20}},{"name":"max_total","in":"query","required":false,"schema":{"type":"number","exclusiveMinimum":0},"description":"Most the whole stay may cost, US dollars, taxes included."},{"name":"near_lifts","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"home_type","in":"query","required":false,"schema":{"type":"string","enum":["home","condo","townhouse"]},"description":"home: a whole house (a cabin or chalet is listed as a home). condo: a condo or apartment. Also read: cabin, house, chalet, apartment, townhome."},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["price","rating"],"default":"price"},"description":"rating: best-rated first, so those are the ones priced live."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":16,"default":6}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"Homes that can be booked for a stay, the first six priced live","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindResponse"}}}},"400":{"description":"A parameter could not be read; the error says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No home with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The stay cannot be priced as asked, e.g. longer than the online limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The booking system did not answer in time; try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/quote":{"get":{"operationId":"quote","tags":["Find and price"],"summary":"The live price the checkout will charge for one home and stay","description":"Nightly rate and total with all fees included, taxes, the amount charged, each payment with when it is taken (at_booking or later), and book_at. Stays of up to 29 nights.","parameters":[{"name":"home_id","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"A home's id, as find returns it."},{"name":"check_in","in":"query","required":true,"schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"check_out","in":"query","required":true,"schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"adults","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":40,"default":2},"description":"Guests 13 and over."},{"name":"children","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":30,"default":0},"description":"Guests aged 3 to 12."},{"name":"pets","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Dogs travelling with the party."}],"responses":{"200":{"description":"The live price the checkout will charge for one home and stay","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"400":{"description":"A parameter could not be read; the error says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No home with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The stay cannot be priced as asked, e.g. longer than the online limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The booking system did not answer in time; try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/home":{"get":{"operationId":"home","tags":["Homes"],"summary":"One home in full","description":"Rooms and beds, amenities, house rules, nearest lift, location and description.","parameters":[{"name":"home_id","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"A home's id, as find returns it."}],"responses":{"200":{"description":"One home in full","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HomeResponse"}}}},"400":{"description":"A parameter could not be read; the error says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No home with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The stay cannot be priced as asked, e.g. longer than the online limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The booking system did not answer in time; try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/terms":{"get":{"operationId":"terms","tags":["Homes"],"summary":"The rental agreement terms for a home","description":"Cancellation policy, travel insurance, stay limit, house limits and how to reach First Chair.","parameters":[{"name":"home_id","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"A home's id, as find returns it."}],"responses":{"200":{"description":"The rental agreement terms for a home","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TermsResponse"}}}},"400":{"description":"A parameter could not be read; the error says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No home with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The stay cannot be priced as asked, e.g. longer than the online limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The booking system did not answer in time; try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/link":{"get":{"operationId":"link","tags":["Booking"],"summary":"The reservation page with the stay filled in","description":"For the traveler to open and book. This does not book.","parameters":[{"name":"home_id","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"A home's id, as find returns it."},{"name":"check_in","in":"query","required":false,"schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"check_out","in":"query","required":false,"schema":{"type":"string","format":"date","description":"YYYY-MM-DD"}},{"name":"adults","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":40,"default":2},"description":"Guests 13 and over."},{"name":"children","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":30,"default":0},"description":"Guests aged 3 to 12."},{"name":"pets","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Dogs travelling with the party."}],"responses":{"200":{"description":"The reservation page with the stay filled in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkResponse"}}}},"400":{"description":"A parameter could not be read; the error says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No home with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The stay cannot be priced as asked, e.g. longer than the online limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The booking system did not answer in time; try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ask":{"get":{"operationId":"ask","tags":["Find and price"],"summary":"A trip question in plain words","description":"Reads place, dates, party, dogs and bedrooms from the question, says how each was read, and answers with the search it ran.","parameters":[{"name":"question","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"A trip question in plain words","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"A parameter could not be read; the error says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No home with that id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The stay cannot be priced as asked, e.g. longer than the online limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The booking system did not answer in time; try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable; try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}