> ## Documentation Index > Fetch the complete documentation index at: https://anyhouse.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Listings > Fetch property listings from the AnyHouse platform. The set of listings returned depends on your API key. ## Overview The Listings API returns **published property listings** (for sale or rent) from the AnyHouse platform. **Which listings you get depends on your API key:** * **AnyHouse API key** — Returns **all** published listings (full catalog). Used by the AnyHouse app and main website. * **Platform API key** — Returns only listings from **agencies connected to your platform**. Used by partners (e.g. whitelabel sites, portals) that show a subset of inventory. Authentication is required via **Bearer token** or **X-Api-Key** header. Without a valid key, the request returns `401 Unauthorized`. *** ## Endpoint **GET** ``` /api/listings ``` Example request: ``` GET https://anyhouse.app/api/listings ``` *** ## Authentication You must send an API key with every request. You can use **either** of the following methods. Use the standard Authorization header. Use your partner API key. ### Option 1 — Bearer Token ```bash theme={null} Authorization: Bearer YOUR_API_KEY ``` ### Option 2 — X-Api-Key Header ```bash theme={null} X-Api-Key: YOUR_API_KEY ``` ### How the API key affects results | API key type | Scope | Listings returned | | ---------------- | -------- | --------------------------------------------------- | | **AnyHouse key** | All | Every published listing on the platform | | **Platform key** | Platform | Only listings from agencies linked to your platform | Contact AnyHouse to obtain an AnyHouse API key or to register your platform and receive a platform-specific key. *** ## Query Parameters All parameters are optional. Use them to filter and paginate results. | Parameter | Type | Description | | ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | `buy` or `rent`. Filters by listing type. | | `min_price` | number | Minimum price (in the currency used with `rate`). | | `max_price` | number | Maximum price (in the currency used with `rate`). | | `min_bedrooms` | number | Minimum number of bedrooms. | | `min_bathrooms` | number | Minimum number of bathrooms. | | `min_size` | number | Minimum size in m². | | `listing_type` | number | Property category ID (e.g. 1 = Apartment, 2 = Villa). See [Listing Types](/listing-types) for all IDs. | | `new_build` | string | Filter by new build. | | `specifications` | string | Comma-separated amenity/feature IDs (e.g. `4,6,13` for Pool, Beachfront, Sea view). See [Specifications](/specifications) for all IDs. | | `search` | string | Free-text search. | | `north_west` | string | North-west corner of map bounds (e.g. `lat,lng`). | | `south_east` | string | South-east corner of map bounds (required if `north_west` is set). | | `move_in_date` | string | Move-in date (ISO date). | | `currency` | string | Currency code for display. | | `rate` | number | Exchange rate (e.g. to convert prices). Default `1`. | | `limit` | number | Number of results per page (default `100`, max `100`). | | `cursor` | string | Pagination cursor from the previous response. | | `order_by` | string | `newest` (default) or `popular`. | | `agency` | string | When `true`, disables “show all promoted” behavior. | *** ## Example Request ```bash theme={null} curl -X GET "https://anyhouse.app/api/listings?type=buy&min_bedrooms=2&limit=20" \ -H "X-Api-Key: YOUR_API_KEY" ``` *** ## Success Response The response is a JSON object with a `data` array of listing objects and pagination cursors. ```json theme={null} { "data": [ { "id": "abc-123", "title": "Ocean View 2BR in Punta Cana", "title_en": "Ocean View 2BR in Punta Cana", "description": "Spacious 2 bedroom with terrace and sea view.", "location": "Punta Cana", "city": "Punta Cana", "country": "Dominican Republic", "buy_price_dollars": 185000, "rent_price_dollars": null, "bedrooms": 2, "bathrooms": 2, "size_m2": 95, "listing_type_id": 1, "status": "available", "uri": "ocean-view-2br-punta-cana", "images": [...], "agency": { "id": "agency-uuid", "company_name": "Example Realty", "logo": "https://..." }, "published": true, "created_at": "2026-01-15T10:00:00Z", "updated_at": "2026-02-20T14:30:00Z" } ], "cursor": "eyJ...", "next_cursor": "eyJ..." } ``` ### Pagination * Use the `cursor` or `next_cursor` value from the response as the `cursor` query parameter in the next request to get the following page. * When there are no more results, `cursor` and `next_cursor` may be `null` or omitted. *** ## Error Responses ### 401 — Unauthorized Missing or invalid API key. ```json theme={null} { "message": "Unauthorized. Listings API requires an API key (Bearer token or X-Api-Key header)." } ``` Or, when a key is sent but not valid: ```json theme={null} { "message": "Unauthorized." } ``` ### 422 — Validation Error Invalid query parameters (e.g. invalid `listing_type`, invalid geo format). ```json theme={null} { "message": "The given data was invalid.", "errors": { "listing_type": ["The selected listing type is invalid."], "south_east": ["The south east field is required when north west is present."] } } ``` *** ## Related reference * **[Listing Types](/listing-types)** — IDs and labels for the `listing_type` parameter (Apartment, Villa, Land, etc.). * **[Specifications](/specifications)** — IDs and labels for the `specifications` parameter (Pool, Beachfront, Gym, etc.). *** ## When to Use This Endpoint Use **GET /api/listings** when: * You are building an app or website that displays AnyHouse property inventory. * You have an **AnyHouse API key** and want the full catalog, or a **platform API key** and want only your platform’s listings. * You need to filter by type (buy/rent), price, bedrooms, location, or search, and paginate with cursors.