{"openapi":"3.1.0","info":{"title":"Reallyo Listings API","version":"1.0.0","description":"Create and manage rental and sale listings on Reallyo, which publishes them to the listing portals. Every listing is identified by YOUR external_id, so sending one again updates it and retries are safe. Listings are checked before anything is published; the response says what was wrong and what to do next. Paid Reallyo plans only. An MCP server with the same operations is at /mcp."},"servers":[{"url":"https://listings-api.reallyo.com"}],"security":[{"bearer":[]}],"paths":{"/v1/me":{"get":{"summary":"Your account, plan limit and usage","responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"The account has no API access (paid plans only)."},"404":{"description":"No such listing."},"422":{"description":"The body is not a valid listing; error.details lists each field."},"429":{"description":"Rate limit (per key, per minute)."}}}},"/v1/listings":{"get":{"summary":"List your API listings","parameters":[{"name":"state","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":500}},{"name":"after","in":"query","schema":{"type":"string"},"description":"next_after from the previous page"}],"responses":{"200":{"description":"A page of listings","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"The account has no API access (paid plans only)."},"404":{"description":"No such listing."},"422":{"description":"The body is not a valid listing; error.details lists each field."},"429":{"description":"Rate limit (per key, per minute)."}}}},"/v1/listings/{external_id}":{"get":{"summary":"Get one listing and its state","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9._:\\-]+$","description":"YOUR id for the unit (e.g. your property-management unit id). Sending the same id again updates the same listing, so retries are safe."}}],"responses":{"200":{"description":"The listing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingView"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"The account has no API access (paid plans only)."},"404":{"description":"No such listing."},"422":{"description":"The body is not a valid listing; error.details lists each field."},"429":{"description":"Rate limit (per key, per minute)."}}},"put":{"summary":"Create or replace a listing","description":"Idempotent. Fields you omit return to their defaults.","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9._:\\-]+$","description":"YOUR id for the unit (e.g. your property-management unit id). Sending the same id again updates the same listing, so retries are safe."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Listing"}}}},"responses":{"200":{"description":"Stored; see state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingView"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"The account has no API access (paid plans only)."},"404":{"description":"No such listing."},"422":{"description":"The body is not a valid listing; error.details lists each field."},"429":{"description":"Rate limit (per key, per minute)."}}},"patch":{"summary":"Change some fields","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9._:\\-]+$","description":"YOUR id for the unit (e.g. your property-management unit id). Sending the same id again updates the same listing, so retries are safe."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"status":{"type":"string","enum":["available","coming_soon","pending","rented","sold","draft"]},"offer_type":{"type":"string","enum":["rent","sale"]},"title":{"description":"Optional. Generated from the address and size when omitted.","type":"string","maxLength":150},"description":{"type":"string","maxLength":10000},"address":{"type":"object","properties":{"street_number":{"type":"string","maxLength":20},"street":{"type":"string","minLength":1,"maxLength":120,"description":"Street name, e.g. \"East 39th Street\"."},"unit":{"type":"string","maxLength":20},"city":{"type":"string","minLength":1,"maxLength":80},"state_code":{"type":"string","minLength":2,"maxLength":2,"description":"Two-letter US state code, e.g. \"NY\"."},"postcode":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$","description":"US ZIP code."},"neighborhood":{"type":"string","maxLength":80},"hide_street_number":{"type":"boolean"}}},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"price":{"description":"Monthly rent (rent) or asking price (sale), in USD. Required for \"available\".","type":"number","exclusiveMinimum":0,"maximum":100000000},"bedrooms":{"description":"0 for a studio.","type":"integer","minimum":0,"maximum":50},"bathrooms":{"description":"Half baths as .5, e.g. 1.5.","type":"number","minimum":0,"maximum":50,"multipleOf":0.5},"square_feet":{"type":"integer","exclusiveMinimum":0,"maximum":1000000},"property_type":{"type":"string","enum":["apartment","assisted living","barn","bungalow","cabin","castle","co-op","condo","cottage","detached house","duplex","farm","flat","fourplex","high-rise","house","houseboat","land","loft","maisonette","manufactured","mid-rise","mobile","multi-family home","penthouse","semi-detached house","senior housing","single-family home","studio","terraced house","townhouse","triplex","villa","windmill"]},"year_built":{"type":"integer","minimum":1700,"maximum":2100},"available_from":{"anyOf":[{"type":"string","const":"now"},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"A calendar date, YYYY-MM-DD."}]},"lease_term":{"type":"string","enum":["1_year","6_months","monthly","rent_to_own","variable"]},"pets":{"type":"object","properties":{"cats":{"type":"boolean"},"small_dogs":{"type":"boolean"},"large_dogs":{"type":"boolean"}}},"furnished":{"type":"boolean"},"smoking_allowed":{"type":"boolean"},"utilities_included":{"type":"array","items":{"type":"string","enum":["Water","Sewage","Garbage","Electricity","Gas","Internet","Cable","Heat"]}},"photos":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"A publicly reachable JPEG, PNG, GIF or WebP, up to 15 MB."},"caption":{"default":"","type":"string","maxLength":200}},"required":["url"]}},"videos":{"maxItems":10,"type":"array","items":{"type":"string","format":"uri"}},"mls_number":{"type":"string","maxLength":40},"syndicate":{"type":"boolean"}},"description":"Only the fields you send change."}}}},"responses":{"200":{"description":"Stored; see state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingView"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"The account has no API access (paid plans only)."},"404":{"description":"No such listing."},"422":{"description":"The body is not a valid listing; error.details lists each field."},"429":{"description":"Rate limit (per key, per minute)."}}},"delete":{"summary":"Take a listing down","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9._:\\-]+$","description":"YOUR id for the unit (e.g. your property-management unit id). Sending the same id again updates the same listing, so retries are safe."}}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingView"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"The account has no API access (paid plans only)."},"404":{"description":"No such listing."},"422":{"description":"The body is not a valid listing; error.details lists each field."},"429":{"description":"Rate limit (per key, per minute)."}}}},"/v1/listings/validate":{"post":{"summary":"Check a listing without storing it","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"external_id":{"type":"string"},"listing":{"$ref":"#/components/schemas/Listing"}},"required":["listing"]}}}},"responses":{"200":{"description":"Check result","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"The account has no API access (paid plans only)."},"404":{"description":"No such listing."},"422":{"description":"The body is not a valid listing; error.details lists each field."},"429":{"description":"Rate limit (per key, per minute)."}}}},"/v1/listings/bulk":{"post":{"summary":"Create or update many listings","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"listings":{"minItems":1,"type":"array","items":{"type":"object","properties":{"status":{"default":"available","description":"\"available\" goes live on the portals (counts towards your plan limit). \"rented\"/\"sold\" take it off the market; \"draft\" keeps it private.","type":"string","enum":["available","coming_soon","pending","rented","sold","draft"]},"offer_type":{"default":"rent","type":"string","enum":["rent","sale"]},"title":{"description":"Optional. Generated from the address and size when omitted.","type":"string","maxLength":150},"description":{"default":"","description":"The listing text renters see. Required for \"available\".","type":"string","maxLength":10000},"address":{"type":"object","properties":{"street_number":{"default":"","description":"House or building number, e.g. \"222\".","type":"string","maxLength":20},"street":{"type":"string","minLength":1,"maxLength":120,"description":"Street name, e.g. \"East 39th Street\"."},"unit":{"default":"","description":"Apartment or unit, e.g. \"16B\". Empty for a whole house.","type":"string","maxLength":20},"city":{"type":"string","minLength":1,"maxLength":80},"state_code":{"type":"string","minLength":2,"maxLength":2,"description":"Two-letter US state code, e.g. \"NY\"."},"postcode":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$","description":"US ZIP code."},"neighborhood":{"default":"","type":"string","maxLength":80},"hide_street_number":{"default":false,"description":"Publish the street without the house number. realtor.com and apartments.com refuse such listings.","type":"boolean"}},"required":["street","city","state_code","postcode"],"description":"The property address. US only."},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"price":{"description":"Monthly rent (rent) or asking price (sale), in USD. Required for \"available\".","type":"number","exclusiveMinimum":0,"maximum":100000000},"bedrooms":{"description":"0 for a studio.","type":"integer","minimum":0,"maximum":50},"bathrooms":{"description":"Half baths as .5, e.g. 1.5.","type":"number","minimum":0,"maximum":50,"multipleOf":0.5},"square_feet":{"type":"integer","exclusiveMinimum":0,"maximum":1000000},"property_type":{"default":"apartment","type":"string","enum":["apartment","assisted living","barn","bungalow","cabin","castle","co-op","condo","cottage","detached house","duplex","farm","flat","fourplex","high-rise","house","houseboat","land","loft","maisonette","manufactured","mid-rise","mobile","multi-family home","penthouse","semi-detached house","senior housing","single-family home","studio","terraced house","townhouse","triplex","villa","windmill"]},"year_built":{"type":"integer","minimum":1700,"maximum":2100},"available_from":{"default":"now","description":"\"now\", or the date the property becomes available.","anyOf":[{"type":"string","const":"now"},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"A calendar date, YYYY-MM-DD."}]},"lease_term":{"default":"1_year","description":"Rentals only.","type":"string","enum":["1_year","6_months","monthly","rent_to_own","variable"]},"pets":{"default":{"cats":false,"small_dogs":false,"large_dogs":false},"description":"Rentals only. Which pets are allowed.","type":"object","properties":{"cats":{"default":false,"type":"boolean"},"small_dogs":{"default":false,"type":"boolean"},"large_dogs":{"default":false,"type":"boolean"}}},"furnished":{"default":false,"description":"Rentals only.","type":"boolean"},"smoking_allowed":{"default":false,"description":"Rentals only.","type":"boolean"},"utilities_included":{"default":[],"description":"Rentals only.","type":"array","items":{"type":"string","enum":["Water","Sewage","Garbage","Electricity","Gas","Internet","Cable","Heat"]}},"photos":{"default":[],"description":"In display order; the first is the cover. At least one is required for \"available\". We copy each photo to our CDN — your URL only has to work when you send it.","maxItems":50,"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"A publicly reachable JPEG, PNG, GIF or WebP, up to 15 MB."},"caption":{"default":"","type":"string","maxLength":200}},"required":["url"]}},"videos":{"default":[],"description":"YouTube, Vimeo or Wistia links. Others are dropped.","maxItems":10,"type":"array","items":{"type":"string","format":"uri"}},"mls_number":{"default":"","type":"string","maxLength":40},"syndicate":{"default":true,"description":"Send to the listing portals when live. false keeps it on Reallyo only.","type":"boolean"},"external_id":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9._:\\-]+$","description":"YOUR id for the unit (e.g. your property-management unit id). Sending the same id again updates the same listing, so retries are safe."}},"required":["address","external_id"]},"description":"Up to 250 listings."},"mode":{"default":"upsert","description":"\"upsert\" changes only the listings sent. \"replace\" also takes every other listing you created through the API off the market (status \"rented\") — use it to send your whole current inventory.","type":"string","enum":["upsert","replace"]}},"required":["listings"]}}}},"responses":{"200":{"description":"Per-listing results","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"The account has no API access (paid plans only)."},"404":{"description":"No such listing."},"422":{"description":"The body is not a valid listing; error.details lists each field."},"429":{"description":"Rate limit (per key, per minute)."}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Authorization: Bearer rly_live_…"}},"schemas":{"Listing":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"status":{"default":"available","description":"\"available\" goes live on the portals (counts towards your plan limit). \"rented\"/\"sold\" take it off the market; \"draft\" keeps it private.","type":"string","enum":["available","coming_soon","pending","rented","sold","draft"]},"offer_type":{"default":"rent","type":"string","enum":["rent","sale"]},"title":{"description":"Optional. Generated from the address and size when omitted.","type":"string","maxLength":150},"description":{"default":"","description":"The listing text renters see. Required for \"available\".","type":"string","maxLength":10000},"address":{"type":"object","properties":{"street_number":{"default":"","description":"House or building number, e.g. \"222\".","type":"string","maxLength":20},"street":{"type":"string","minLength":1,"maxLength":120,"description":"Street name, e.g. \"East 39th Street\"."},"unit":{"default":"","description":"Apartment or unit, e.g. \"16B\". Empty for a whole house.","type":"string","maxLength":20},"city":{"type":"string","minLength":1,"maxLength":80},"state_code":{"type":"string","minLength":2,"maxLength":2,"description":"Two-letter US state code, e.g. \"NY\"."},"postcode":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$","description":"US ZIP code."},"neighborhood":{"default":"","type":"string","maxLength":80},"hide_street_number":{"default":false,"description":"Publish the street without the house number. realtor.com and apartments.com refuse such listings.","type":"boolean"}},"required":["street","city","state_code","postcode"],"description":"The property address. US only."},"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180},"price":{"description":"Monthly rent (rent) or asking price (sale), in USD. Required for \"available\".","type":"number","exclusiveMinimum":0,"maximum":100000000},"bedrooms":{"description":"0 for a studio.","type":"integer","minimum":0,"maximum":50},"bathrooms":{"description":"Half baths as .5, e.g. 1.5.","type":"number","minimum":0,"maximum":50,"multipleOf":0.5},"square_feet":{"type":"integer","exclusiveMinimum":0,"maximum":1000000},"property_type":{"default":"apartment","type":"string","enum":["apartment","assisted living","barn","bungalow","cabin","castle","co-op","condo","cottage","detached house","duplex","farm","flat","fourplex","high-rise","house","houseboat","land","loft","maisonette","manufactured","mid-rise","mobile","multi-family home","penthouse","semi-detached house","senior housing","single-family home","studio","terraced house","townhouse","triplex","villa","windmill"]},"year_built":{"type":"integer","minimum":1700,"maximum":2100},"available_from":{"default":"now","description":"\"now\", or the date the property becomes available.","anyOf":[{"type":"string","const":"now"},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"A calendar date, YYYY-MM-DD."}]},"lease_term":{"default":"1_year","description":"Rentals only.","type":"string","enum":["1_year","6_months","monthly","rent_to_own","variable"]},"pets":{"default":{"cats":false,"small_dogs":false,"large_dogs":false},"description":"Rentals only. Which pets are allowed.","type":"object","properties":{"cats":{"default":false,"type":"boolean"},"small_dogs":{"default":false,"type":"boolean"},"large_dogs":{"default":false,"type":"boolean"}}},"furnished":{"default":false,"description":"Rentals only.","type":"boolean"},"smoking_allowed":{"default":false,"description":"Rentals only.","type":"boolean"},"utilities_included":{"default":[],"description":"Rentals only.","type":"array","items":{"type":"string","enum":["Water","Sewage","Garbage","Electricity","Gas","Internet","Cable","Heat"]}},"photos":{"default":[],"description":"In display order; the first is the cover. At least one is required for \"available\". We copy each photo to our CDN — your URL only has to work when you send it.","maxItems":50,"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"A publicly reachable JPEG, PNG, GIF or WebP, up to 15 MB."},"caption":{"default":"","type":"string","maxLength":200}},"required":["url"]}},"videos":{"default":[],"description":"YouTube, Vimeo or Wistia links. Others are dropped.","maxItems":10,"type":"array","items":{"type":"string","format":"uri"}},"mls_number":{"default":"","type":"string","maxLength":40},"syndicate":{"default":true,"description":"Send to the listing portals when live. false keeps it on Reallyo only.","type":"boolean"}},"required":["address"],"description":"A listing. Sending it again replaces it entirely — fields you omit return to their defaults."},"ListingView":{"type":"object","properties":{"external_id":{"type":"string"},"reallyo_listing_id":{"type":["integer","null"]},"state":{"type":"string","enum":["rejected","queued","held","live","saved","parked","failed","removed"]},"status":{"type":"string"},"revision":{"type":"integer"},"checks":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/Issue"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/Issue"}}}},"message":{"type":["string","null"]},"next":{"type":"string","description":"What to do next, in plain words."},"updated_at":{"type":"string","format":"date-time"},"published_at":{"type":["string","null"],"format":"date-time"}}},"Issue":{"type":"object","properties":{"field":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}