{"openapi":"3.1.0","info":{"title":"Mashvisor (BYOK) API","version":"0.1.0","description":"Mashvisor (BYOK) lets an AI assistant read your own Mashvisor data through the Mashvisor API with a key you supply (Mashvisor API key). Read-only: 12 tools (list_cities, list_neighborhoods, list_top_markets, get_city_investment_performance, search_listings, get_top_neighborhoods, get_neighborhood_overview, list_neighborhood_schools, get_neighborhood_crime, get_rental_rates, get_city_summary,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-mashvisor.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-mashvisor/docs"},"termsOfService":"https://connectorbay.com/byok-mashvisor/terms"},"servers":[{"url":"https://byok-mashvisor.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-mashvisor/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_cities":{"post":{"operationId":"list_cities","summary":"List the city names Mashvisor covers in one US state, with the total count. Page size is at most 10. Use for \"Which citi","description":"List the city names Mashvisor covers in one US state, with the total count. Page size is at most 10. Use for \"Which cities in Florida does Mashvisor cover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"description":"Two-letter US state code, for example CA or FL.","maxLength":2,"title":"State","type":"string"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"items":{"anyOf":[{"maximum":10,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Items per page (1 to 10).","title":"Items"}},"required":["state"],"title":"list_citiesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_neighborhoods":{"post":{"operationId":"list_neighborhoods","summary":"List the neighborhoods (MLS areas) of one US city with id, coordinates, county and whether it is a village. Use the ids ","description":"List the neighborhoods (MLS areas) of one US city with id, coordinates, county and whether it is a village. Use the ids with the neighborhood tools. Use for \"Which neighborhoods does Los Angeles have in Mashvisor\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"description":"Two-letter US state code, for example CA or FL.","maxLength":200,"title":"State","type":"string"},"city":{"description":"City name, for example Los Angeles.","maxLength":200,"title":"City","type":"string"}},"required":["state","city"],"title":"list_neighborhoodsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_top_markets":{"post":{"operationId":"list_top_markets","summary":"List the top cities or metro areas of one US state by number of active homes for sale. Use for \"What are the biggest hou","description":"List the top cities or metro areas of one US state by number of active homes for sale. Use for \"What are the biggest housing markets in Georgia by homes for sale\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"description":"Two-letter US state code, for example CA or FL.","maxLength":2,"title":"State","type":"string"},"items":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":5,"description":"How many markets to return.","title":"Items"}},"required":["state"],"title":"list_top_marketsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_city_investment_performance":{"post":{"operationId":"get_city_investment_performance","summary":"Get median investment metrics for one US city: median price, price per square foot, counts of investment, Airbnb and tra","description":"Get median investment metrics for one US city: median price, price per square foot, counts of investment, Airbnb and traditional rental properties, occupancy, cash on cash return, cap rate and rental rates by bedroom count. Use for \"What is the median price and rental yield in Los Angeles\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"description":"Two-letter US state code, for example CA or FL.","maxLength":200,"title":"State","type":"string"},"city":{"description":"City name, for example Los Angeles.","maxLength":200,"title":"City","type":"string"}},"required":["state","city"],"title":"get_city_investment_performanceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_listings":{"post":{"operationId":"search_listings","summary":"Search active for-sale listings in one US city with optional filters for bedrooms, bathrooms, price, size, property type","description":"Search active for-sale listings in one US city with optional filters for bedrooms, bathrooms, price, size, property type and foreclosures. Returns address, price, beds, baths, status, days on market and open house times. Use for \"Which 3 bedroom homes under 900000 are for sale in San Francisco\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"description":"Two-letter US state code, for example CA or FL.","maxLength":2,"title":"State","type":"string"},"city":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"City name. Required unless zip_code is given.","title":"City"},"zip_code":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Zip code, used instead of city.","title":"Zip Code"},"beds":{"anyOf":[{"maximum":10,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Minimum number of bedrooms.","title":"Beds"},"baths":{"anyOf":[{"maximum":10,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Minimum number of bathrooms.","title":"Baths"},"min_price":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Minimum listing price.","title":"Min Price"},"max_price":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Maximum listing price.","title":"Max Price"},"min_sqft":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Minimum square footage.","title":"Min Sqft"},"property_type":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Property type, for example Single Family Residential or Apartment.","title":"Property Type"},"foreclosure":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include foreclosed properties.","title":"Foreclosure"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Results per page (1 to 100).","title":"Page Limit"}},"required":["state"],"title":"search_listingsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_top_neighborhoods":{"post":{"operationId":"get_top_neighborhoods","summary":"List the top neighborhoods of one US city by occupancy rate, with Airbnb listing counts, typical home value, return on i","description":"List the top neighborhoods of one US city by occupancy rate, with Airbnb listing counts, typical home value, return on investment, cap rate and rental income for Airbnb and traditional rentals. Use for \"Which Miami Beach neighborhoods have the highest occupancy\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"description":"Two-letter US state code, for example CA or FL.","maxLength":2,"title":"State","type":"string"},"city":{"description":"City name, for example Miami Beach.","maxLength":200,"title":"City","type":"string"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"items":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":5,"description":"How many neighborhoods to return.","title":"Items"}},"required":["state","city"],"title":"get_top_neighborhoodsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_neighborhood_overview":{"post":{"operationId":"get_neighborhood_overview","summary":"Get a neighborhood overview with walk, transit and bike scores, median price, price per square foot, average days on mar","description":"Get a neighborhood overview with walk, transit and bike scores, median price, price per square foot, average days on market, sales counts, Airbnb and traditional rental metrics. State is required. Use for \"Give me the investment overview of neighborhood 268201 in California\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Mashvisor neighborhood id, from list_neighborhoods.","title":"Id","type":"integer"},"state":{"description":"Two-letter US state code of the neighborhood.","maxLength":2,"title":"State","type":"string"}},"required":["id","state"],"title":"get_neighborhood_overviewArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_neighborhood_schools":{"post":{"operationId":"list_neighborhood_schools","summary":"List the schools serving one neighborhood with name, address, type (public or private), grade levels and rating. Use for","description":"List the schools serving one neighborhood with name, address, type (public or private), grade levels and rating. Use for \"Which schools serve neighborhood 123706 in Florida\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Mashvisor neighborhood id, from list_neighborhoods.","title":"Id","type":"integer"},"state":{"description":"Two-letter US state code of the neighborhood.","maxLength":2,"title":"State","type":"string"}},"required":["id","state"],"title":"list_neighborhood_schoolsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_neighborhood_crime":{"post":{"operationId":"get_neighborhood_crime","summary":"Get aggregate crime statistics for one neighborhood: population, incident count, crime severity index and incident types","description":"Get aggregate crime statistics for one neighborhood: population, incident count, crime severity index and incident types with counts and ratios, within one mile of the neighborhood centre over the last year. State is required. Use for \"How safe is neighborhood 268201 in California\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Mashvisor neighborhood id, from list_neighborhoods.","title":"Id","type":"integer"},"state":{"description":"Two-letter US state code of the neighborhood.","maxLength":2,"title":"State","type":"string"}},"required":["id","state"],"title":"get_neighborhood_crimeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_rental_rates":{"post":{"operationId":"get_rental_rates","summary":"Estimate monthly rental rates by bedroom count for a neighborhood, city or zip code, for traditional long term rentals o","description":"Estimate monthly rental rates by bedroom count for a neighborhood, city or zip code, for traditional long term rentals or Airbnb, with sample counts, min, max, average and median. State is required. Use for \"What do 2 bedroom apartments rent for in neighborhood 51492 in Oklahoma\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"description":"Two-letter US state code, for example CA or FL.","maxLength":2,"title":"State","type":"string"},"city":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"City name.","title":"City"},"neighborhood":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Neighborhood id.","title":"Neighborhood"},"zip_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Zip code.","title":"Zip Code"},"source":{"anyOf":[{"enum":["airbnb","traditional"],"type":"string"},{"type":"null"}],"default":"traditional","description":"Which rentals to estimate.","title":"Source"}},"required":["state"],"title":"get_rental_ratesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_city_summary":{"post":{"operationId":"get_city_summary","summary":"Get a summary of one US city: active neighborhoods, investment properties, Airbnb and traditional listings, average pric","description":"Get a summary of one US city: active neighborhoods, investment properties, Airbnb and traditional listings, average price, price per square foot, days on market, occupancy, nightly price and return on investment. Use for \"Summarise the Chicago housing and rental market\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"description":"Two-letter US state code, for example CA or FL.","maxLength":200,"title":"State","type":"string"},"city":{"description":"City name, for example Los Angeles.","maxLength":200,"title":"City","type":"string"}},"required":["state","city"],"title":"get_city_summaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_listing_price_trends":{"post":{"operationId":"get_listing_price_trends","summary":"Get average and median listing prices and price per square foot for one zip code, optionally by bedroom count and proper","description":"Get average and median listing prices and price per square foot for one zip code, optionally by bedroom count and property type. Use for \"What is the median listing price in zip code 95118\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"description":"Two-letter US state code, for example CA or FL.","maxLength":2,"title":"State","type":"string"},"zip_code":{"description":"Zip code, for example 95118.","maxLength":200,"title":"Zip Code","type":"string"},"beds":{"anyOf":[{"maximum":4,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Bedrooms, 0 to 4.","title":"Beds"},"property_type":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Single Family Residential, Townhouse, Condo/Coop, Multi Family or Other.","title":"Property Type"}},"required":["state","zip_code"],"title":"get_listing_price_trendsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}