{"openapi":"3.1.0","info":{"title":"HomesIDX API","version":"1.0.0","description":"California Regional MLS (CRMLS) listings for CRMLS participants and subscribers. Every response carries attribution and the MLS disclaimer; display them per https://kb.crmls.org/knowledgebase/idx-standards-of-practice/.","termsOfService":"https://www.homesidx.com/terms"},"servers":[{"url":"https://www.homesidx.com"}],"security":[{"apiKey":[]}],"paths":{"/v1/listings":{"get":{"operationId":"searchListings","summary":"Search listings","parameters":[{"name":"city","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"postal_code","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{5}$"}},{"name":"county","in":"query","required":false,"schema":{"type":"string","minLength":1}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"property_type","in":"query","required":false,"schema":{"type":"string"}},{"name":"price_min","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"price_max","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"beds_min","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"baths_min","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"sqft_min","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"year_built_min","in":"query","required":false,"schema":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},{"name":"pool","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}},{"name":"bbox","in":"query","required":false,"schema":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?(,-?\\d+(\\.\\d+)?){3}$"}},{"name":"lat","in":"query","required":false,"schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"lng","in":"query","required":false,"schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"radius_miles","in":"query","required":false,"schema":{"type":"number","exclusiveMinimum":0,"maximum":100}},{"name":"modified_since","in":"query","required":false,"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"agent_mls_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"office_mls_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["newest","price_asc","price_desc","updated"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Publishable key used from an unregistered origin, or secret key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Burst limit (100 / 10 s) or monthly quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/listings/{key}":{"get":{"operationId":"getListing","summary":"Get one listing with all displayable photos","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Publishable key used from an unregistered origin, or secret key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Burst limit (100 / 10 s) or monthly quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/listings/{key}/media":{"get":{"operationId":"getListingMedia","summary":"Photo list for a listing","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Media","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Publishable key used from an unregistered origin, or secret key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found"},"429":{"description":"Burst limit (100 / 10 s) or monthly quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/media/{key}/{order}":{"get":{"operationId":"getPhoto","summary":"Photo bytes (public, CDN-cached)","security":[],"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}},{"name":"order","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Image","content":{"image/jpeg":{},"image/webp":{},"image/svg+xml":{}}},"404":{"description":"Not found"}}}},"/v1/health":{"get":{"operationId":"health","summary":"Feed status","security":[],"responses":{"200":{"description":"Status"}}}},"/mcp":{"post":{"operationId":"mcp","summary":"MCP endpoint (Streamable HTTP, JSON-RPC 2.0). Secret keys only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"JSON-RPC response"},"202":{"description":"Notification accepted"},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Publishable key used from an unregistered origin, or secret key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Burst limit (100 / 10 s) or monthly quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Secret key mk_live_... (server) or publishable key pk_live_... (browser; Origin must match a registered site URL)."}},"schemas":{"Listing":{"type":"object","properties":{"listing_key":{"type":"string"},"listing_id":{"nullable":true,"type":"string"},"source":{"type":"string"},"status":{"type":"string"},"property_type":{"nullable":true,"type":"string"},"property_sub_type":{"nullable":true,"type":"string"},"price":{"type":"object","properties":{"list":{"nullable":true,"type":"number"},"original":{"nullable":true,"type":"number"},"close":{"nullable":true,"type":"number"}},"required":["list","original","close"],"additionalProperties":false},"address":{"type":"object","properties":{"full":{"nullable":true,"type":"string"},"street_number":{"nullable":true,"type":"string"},"street_name":{"nullable":true,"type":"string"},"unit":{"nullable":true,"type":"string"},"city":{"nullable":true,"type":"string"},"state":{"nullable":true,"type":"string"},"postal_code":{"nullable":true,"type":"string"},"county":{"nullable":true,"type":"string"}},"required":["full","street_number","street_name","unit","city","state","postal_code","county"],"additionalProperties":false},"location":{"type":"object","properties":{"lat":{"nullable":true,"type":"number"},"lng":{"nullable":true,"type":"number"}},"required":["lat","lng"],"additionalProperties":false},"details":{"type":"object","properties":{"beds":{"nullable":true,"type":"number"},"baths":{"nullable":true,"type":"number"},"baths_full":{"nullable":true,"type":"number"},"baths_half":{"nullable":true,"type":"number"},"living_area_sqft":{"nullable":true,"type":"number"},"lot_size_sqft":{"nullable":true,"type":"number"},"year_built":{"nullable":true,"type":"number"},"stories":{"nullable":true,"type":"number"},"garage_spaces":{"nullable":true,"type":"number"},"pool":{"nullable":true,"type":"boolean"},"hoa_fee":{"nullable":true,"type":"number"},"days_on_market":{"nullable":true,"type":"number"}},"required":["beds","baths","baths_full","baths_half","living_area_sqft","lot_size_sqft","year_built","stories","garage_spaces","pool","hoa_fee","days_on_market"],"additionalProperties":false},"remarks":{"nullable":true,"type":"string"},"dates":{"type":"object","properties":{"listed":{"nullable":true,"type":"string"},"on_market":{"nullable":true,"type":"string"},"closed":{"nullable":true,"type":"string"},"status_changed":{"nullable":true,"type":"string"},"mls_updated":{"type":"string"}},"required":["listed","on_market","closed","status_changed","mls_updated"],"additionalProperties":false},"attribution":{"type":"object","properties":{"listing_agent":{"type":"object","properties":{"name":{"nullable":true,"type":"string"},"mls_id":{"nullable":true,"type":"string"},"license":{"nullable":true,"type":"string"},"phone":{"nullable":true,"type":"string"},"email":{"nullable":true,"type":"string"}},"required":["name","mls_id","license","phone","email"],"additionalProperties":false},"listing_office":{"type":"object","properties":{"name":{"nullable":true,"type":"string"},"mls_id":{"nullable":true,"type":"string"},"phone":{"nullable":true,"type":"string"}},"required":["name","mls_id","phone"],"additionalProperties":false},"co_listing_agent":{"nullable":true,"type":"string"},"co_listing_office":{"nullable":true,"type":"string"},"idx_contact_info":{"nullable":true,"type":"string"},"label":{"type":"string"}},"required":["listing_agent","listing_office","co_listing_agent","co_listing_office","idx_contact_info","label"],"additionalProperties":false},"photos_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"media":{"type":"array","items":{"type":"object","properties":{"order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"url":{"type":"string"},"width":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"height":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"description":{"nullable":true,"type":"string"}},"required":["order","url","width","height","description"],"additionalProperties":false}}},"required":["listing_key","listing_id","source","status","property_type","property_sub_type","price","address","location","details","remarks","dates","attribution","photos_count","media"],"additionalProperties":false},"Media":{"type":"object","properties":{"order":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"url":{"type":"string"},"width":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"height":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"description":{"nullable":true,"type":"string"}},"required":["order","url","width","height","description"],"additionalProperties":false},"Attribution":{"type":"object","properties":{"source":{"type":"string"},"displaying_broker":{"type":"string"},"mls_disclaimer":{"type":"string"},"display_rules":{"type":"string"}},"required":["source","displaying_broker","mls_disclaimer","display_rules"],"additionalProperties":false},"Meta":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"next_cursor":{"nullable":true,"type":"string"},"generated_at":{"type":"string"},"data_last_updated":{"nullable":true,"type":"string"}},"required":["generated_at","data_last_updated"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"issues":{"type":"array","items":{}}},"required":["error"],"additionalProperties":false},"SearchResponse":{"type":"object","required":["data","meta","attribution"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"meta":{"$ref":"#/components/schemas/Meta"},"attribution":{"$ref":"#/components/schemas/Attribution"}}},"ListingResponse":{"type":"object","required":["data","meta","attribution"],"properties":{"data":{"$ref":"#/components/schemas/Listing"},"meta":{"$ref":"#/components/schemas/Meta"},"attribution":{"$ref":"#/components/schemas/Attribution"}}},"MediaResponse":{"type":"object","required":["data","meta","attribution"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"meta":{"$ref":"#/components/schemas/Meta"},"attribution":{"$ref":"#/components/schemas/Attribution"}}}}}}