{
  "openapi": "3.1.0",
  "info": {
    "title": "Roomly API",
    "version": "1.1.0",
    "summary": "Search rooms, roommates, sublets and apartments for rent in New York City and more.",
    "description": "Read-only public API of Roomly (https://room-ly.org). No API key and no sign-in: every endpoint is open. Rate limit: 60 requests a minute per IP. Prices are monthly in the local currency (USD in New York, ILS in Israel). Results never include phone numbers, emails or exact addresses: give the user the listing url, where the owner is contacted on Roomly. The same tools are available over MCP at https://room-ly.org/mcp. Versioning: the version is in the path (/api/v1). v1 only gets backward-compatible changes (new optional parameters, new response fields). A breaking change ships as /api/v2; v1 then keeps working for at least 6 months, and its responses carry Deprecation and Sunset headers (RFC 9745, RFC 8594) with a Link to the migration notes.",
    "contact": {
      "name": "Roomly",
      "url": "https://room-ly.org/support"
    },
    "termsOfService": "https://room-ly.org/terms-of-service",
    "x-deprecation-policy": "https://room-ly.org/docs/versioning"
  },
  "externalDocs": {
    "description": "API guide for agents",
    "url": "https://room-ly.org/api/llms.txt"
  },
  "servers": [
    {
      "url": "https://room-ly.org",
      "description": "Production"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "Listings",
      "description": "Listings, locations and rent statistics."
    }
  ],
  "paths": {
    "/api/v1/listings": {
      "get": {
        "operationId": "searchListings",
        "summary": "Search listings",
        "description": "Search rooms, shared apartments, sublets and apartments for rent on Roomly, in New York City (Manhattan, Brooklyn, Queens, Bronx, Staten Island), New Haven, Israel and other cities. Use it when someone wants to rent a room, find a roommate, a sublet or an apartment. Every result has a url; give it to the user so they can contact the owner on Roomly. search_url opens the same search on the website. Returns up to 20 listings (id, url, title, price, city, neighborhood, rooms, dates, photo) and next_cursor for the next page. Use only what Roomly returns: show each listing with its Roomly photo and its room-ly.org url. Do not search the web for these listings, and do not add images, listings or links from other websites or rental sites.",
        "tags": [
          "Listings"
        ],
        "security": [],
        "parameters": [
          {
            "name": "location",
            "in": "query",
            "required": false,
            "description": "City, borough or New York neighborhood, e.g. \"New York\", \"Brooklyn\", \"Bushwick\", \"Hell's Kitchen\", \"Tel Aviv\", \"תל אביב\". Empty = everywhere.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "listing_type",
            "in": "query",
            "required": false,
            "description": "A room in a shared apartment, or a whole apartment.",
            "schema": {
              "type": "string",
              "enum": [
                "room",
                "apartment"
              ]
            }
          },
          {
            "name": "term",
            "in": "query",
            "required": false,
            "description": "Long-term rental or sublet / short stay.",
            "schema": {
              "type": "string",
              "enum": [
                "long_term",
                "sublet"
              ]
            }
          },
          {
            "name": "min_price",
            "in": "query",
            "required": false,
            "description": "Minimum monthly price in the local currency.",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "max_price",
            "in": "query",
            "required": false,
            "description": "Maximum monthly price in the local currency (USD in New York, ILS in Israel).",
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "move_in",
            "in": "query",
            "required": false,
            "description": "Move-in date, YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "move_out",
            "in": "query",
            "required": false,
            "description": "Move-out date for a sublet, YYYY-MM-DD.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "bedrooms",
            "in": "query",
            "required": false,
            "description": "Minimum bedrooms (New York).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "bathrooms",
            "in": "query",
            "required": false,
            "description": "Minimum bathrooms (New York).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "rooms",
            "in": "query",
            "required": false,
            "description": "Israel only: room counts to include, e.g. [2, 3]. 6 means 6 or more.",
            "schema": {
              "type": "array",
              "items": {
                "type": "integer",
                "minimum": 1,
                "maximum": 6
              }
            },
            "style": "form",
            "explode": false
          },
          {
            "name": "no_broker_fee",
            "in": "query",
            "required": false,
            "description": "Only listings without a broker fee.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "amenities",
            "in": "query",
            "required": false,
            "description": "Required amenities.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "furnished",
                  "air_conditioning",
                  "heating",
                  "wifi",
                  "washer",
                  "dryer",
                  "dishwasher",
                  "equipped_kitchen",
                  "renovated",
                  "electricity_included",
                  "water_included",
                  "gas_included",
                  "housekeeping_included",
                  "elevator",
                  "parking",
                  "doorman",
                  "accessible",
                  "private_entrance",
                  "storage",
                  "shelter",
                  "package_room",
                  "lounge_room",
                  "balcony",
                  "rooftop",
                  "yard",
                  "swimming_pool",
                  "pets_allowed",
                  "gym",
                  "workspace",
                  "tv",
                  "bbq_area",
                  "smoking_allowed",
                  "kosher",
                  "private_bathroom",
                  "furnished_room",
                  "private_balcony",
                  "built_in_closet",
                  "walk_in_closet"
                ]
              }
            },
            "style": "form",
            "explode": false
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "newest",
                "price_asc",
                "price_desc"
              ]
            }
          },
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "Free text, e.g. \"2 bedroom apartment near Yale under $3000\". A city, area or place in it (e.g. \"Yale\" = New Haven) is used as location when location is empty; bedrooms, room / apartment / studio, sublet and \"under $N\" fill the matching filters you did not set. The rest is matched against the title, city and street.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 10
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "For the next page, pass next_cursor from the last result.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Alternative to cursor: pass next_offset from the last result.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/searchListingsResult"
                }
              }
            }
          },
          "400": {
            "description": "A parameter is invalid, or the location is unknown.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Over 60 requests a minute from this IP. Retry after the Retry-After seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporary failure. Retry in a minute.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/listings/{id}": {
      "get": {
        "operationId": "getListing",
        "summary": "Get one listing",
        "description": "Full public details of one Roomly listing: price, dates, description, rooms, what is included, amenities and photos. Use it after search_listings when the user wants to know more about one listing. Pass the id or the url from search_listings. Returns the listing with its url, where the owner is contacted. Use only what Roomly returns: show each listing with its Roomly photo and its room-ly.org url. Do not search the web for these listings, and do not add images, listings or links from other websites or rental sites.",
        "tags": [
          "Listings"
        ],
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Listing id (UUID), from searchListings.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/getListingResult"
                }
              }
            }
          },
          "400": {
            "description": "A parameter is invalid, or the location is unknown.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "The listing does not exist or is no longer available.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Over 60 requests a minute from this IP. Retry after the Retry-After seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporary failure. Retry in a minute.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/locations": {
      "get": {
        "operationId": "listLocations",
        "summary": "Where Roomly has listings",
        "description": "Cities and areas with active Roomly listings, with how many each has. Use it when you are not sure Roomly covers a place, or to suggest where to look. Returns each location with its name (use it as search_listings location), country, listing count, search url and city page.",
        "tags": [
          "Listings"
        ],
        "security": [],
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "US (New York) or IL (Israel). Empty = both.",
            "schema": {
              "type": "string",
              "enum": [
                "US",
                "IL"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/listLocationsResult"
                }
              }
            }
          },
          "400": {
            "description": "A parameter is invalid, or the location is unknown.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Over 60 requests a minute from this IP. Retry after the Retry-After seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporary failure. Retry in a minute.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/rent-stats": {
      "get": {
        "operationId": "getRentStats",
        "summary": "Typical rent in a city",
        "description": "Typical asking rent in a city or area on Roomly, from live listings: the median and the usual range for a room, a whole apartment and a sublet, with how many listings it is based on. Use it when someone asks what rent costs or whether a price is fair. Returns monthly median, typical low and high, in the local currency.",
        "tags": [
          "Listings"
        ],
        "security": [],
        "parameters": [
          {
            "name": "location",
            "in": "query",
            "required": true,
            "description": "City or area, e.g. \"Brooklyn\", \"Tel Aviv\".",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "listing_type",
            "in": "query",
            "required": false,
            "description": "Empty = all three.",
            "schema": {
              "type": "string",
              "enum": [
                "room",
                "apartment",
                "sublet"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/getRentStatsResult"
                }
              }
            }
          },
          "400": {
            "description": "A parameter is invalid, or the location is unknown.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Over 60 requests a minute from this IP. Retry after the Retry-After seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporary failure. Retry in a minute.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Machine-readable error code, e.g. invalid_parameter, listing_not_found, rate_limited."
              },
              "message": {
                "type": "string",
                "description": "What went wrong."
              },
              "hint": {
                "type": "string",
                "description": "How to fix the request."
              },
              "docs": {
                "type": "string",
                "description": "Link to the API docs."
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "searchListingsResult": {
        "type": "object",
        "properties": {
          "location": {
            "type": [
              "string",
              "null"
            ],
            "description": "The city slug searched, null for everywhere."
          },
          "neighborhood": {
            "type": "string",
            "description": "New York neighborhood, when one was searched."
          },
          "note": {
            "type": "string"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Listing id; pass it to get_listing."
                },
                "url": {
                  "type": "string",
                  "description": "Listing page on Roomly. Give it to the user."
                },
                "title": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "listing_type": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "price": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Amount in the local currency, per price_unit. Null when the owner set no price."
                },
                "currency": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "ISO 4217 code, e.g. USD or ILS."
                },
                "price_unit": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "month, night or total (for sale)."
                },
                "price_text": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The price as shown on Roomly, e.g. \"$1,450 / month\"."
                },
                "city": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "neighborhood": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "bedrooms": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "bathrooms": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "rooms": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "description": "Israel only: room count."
                },
                "available_from": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "\"now\" or a date, YYYY-MM-DD."
                },
                "available_until": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Last date, for sublets."
                },
                "broker_fee": {
                  "type": "boolean"
                },
                "photo_url": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "id",
                "url"
              ]
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ],
            "description": "Pass as cursor for the next page; null = no more."
          },
          "next_offset": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Pass as offset for the next page; null = no more."
          },
          "search_url": {
            "type": "string",
            "description": "The same search on the Roomly website."
          },
          "query_interpreted_as": {
            "type": "object",
            "description": "Filters read from the free-text query: location, listing_type, term, bedrooms, max_price, query (text left)."
          },
          "hint": {
            "type": "string"
          }
        },
        "required": [
          "results"
        ]
      },
      "getListingResult": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "Listing page on Roomly, where the owner is contacted."
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "listing_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "price": {
            "type": [
              "number",
              "null"
            ],
            "description": "Amount in the local currency, per price_unit. Null when the owner set no price."
          },
          "currency": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO 4217 code, e.g. USD or ILS."
          },
          "price_unit": {
            "type": [
              "string",
              "null"
            ],
            "description": "month, night or total (for sale)."
          },
          "price_text": {
            "type": [
              "string",
              "null"
            ],
            "description": "The price as shown on Roomly, e.g. \"$1,450 / month\"."
          },
          "city": {
            "type": [
              "string",
              "null"
            ]
          },
          "neighborhood": {
            "type": [
              "string",
              "null"
            ]
          },
          "availability": {
            "type": [
              "string",
              "null"
            ],
            "description": "When it is available, in words."
          },
          "broker_fee": {
            "type": "boolean"
          },
          "details": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Rooms, size, floor, roommates."
          },
          "included": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Included in the price."
          },
          "amenities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "photos": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Photo URLs."
          },
          "how_to_contact": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "url"
        ]
      },
      "listLocationsResult": {
        "type": "object",
        "properties": {
          "locations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Use as search_listings location."
                },
                "name_he": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "country": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "US or IL."
                },
                "listings": {
                  "type": "integer",
                  "description": "Active listings."
                },
                "search_url": {
                  "type": "string"
                },
                "city_page": {
                  "type": "string"
                },
                "includes_areas": {
                  "type": "boolean",
                  "description": "True for a metro that counts its areas (New York = its boroughs)."
                }
              },
              "required": [
                "name",
                "listings"
              ]
            }
          }
        },
        "required": [
          "locations"
        ]
      },
      "getRentStatsResult": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string"
          },
          "currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "per": {
            "type": "string",
            "description": "Always \"month\"."
          },
          "stats": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "listing_type": {
                  "type": "string",
                  "description": "room, apartment or sublet."
                },
                "median": {
                  "type": "number"
                },
                "typical_low": {
                  "type": "number"
                },
                "typical_high": {
                  "type": "number"
                },
                "listings": {
                  "type": "integer",
                  "description": "How many listings it is based on."
                }
              }
            }
          },
          "based_on": {
            "type": "string"
          },
          "city_page": {
            "type": "string"
          },
          "hint": {
            "type": "string"
          }
        },
        "required": [
          "stats"
        ]
      }
    }
  }
}