> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aris247.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/listings/search

> Search MLS property listings with structured filters and natural language.

Search MLS property listings. Routes automatically to IDX Broker or the brokerage's custom database based on their integration type.

## Request

```bash theme={null}
curl -X POST \
  "https://dqgynnlsclfbqysauesf.supabase.co/functions/v1/api-router/v1/listings/search" \
  -H "Content-Type: application/json" \
  -H "X-ARIS-API-Key: aris_yourkey" \
  -d '{
    "city": "Austin",
    "state": "TX",
    "maxPrice": 500000,
    "minBeds": 3,
    "mode": "hybrid",
    "semanticQuery": "modern home with updated kitchen",
    "limit": 12
  }'
```

### Body parameters

<ParamField body="city" type="string">City name.</ParamField>
<ParamField body="state" type="string">Two-letter state code.</ParamField>
<ParamField body="zip" type="string">ZIP code.</ParamField>
<ParamField body="minPrice" type="number">Minimum listing price.</ParamField>
<ParamField body="maxPrice" type="number">Maximum listing price.</ParamField>
<ParamField body="minBeds" type="integer">Minimum bedrooms.</ParamField>
<ParamField body="maxBeds" type="integer">Maximum bedrooms.</ParamField>
<ParamField body="minBaths" type="number">Minimum bathrooms.</ParamField>
<ParamField body="maxBaths" type="number">Maximum bathrooms.</ParamField>
<ParamField body="minSqFt" type="integer">Minimum square footage.</ParamField>
<ParamField body="maxSqFt" type="integer">Maximum square footage.</ParamField>
<ParamField body="propertyType" type="string">`"Single Family"`, `"Condo"`, `"Townhouse"`, etc.</ParamField>
<ParamField body="hasPool" type="boolean">Filter for homes with a pool.</ParamField>
<ParamField body="isWaterfront" type="boolean">Filter for waterfront properties.</ParamField>
<ParamField body="hasGarage" type="boolean">Filter for homes with a garage.</ParamField>
<ParamField body="semanticQuery" type="string">Natural language query for ranking.</ParamField>

<ParamField body="mode" type="string" default="hybrid">
  Search mode: `structured_only`, `keyword`, `semantic`, or `hybrid`.
</ParamField>

<ParamField body="limit" type="integer" default="12">Max results (max 24).</ParamField>

### Search modes

| Mode              | Description                                         |
| ----------------- | --------------------------------------------------- |
| `structured_only` | Only hard filters, no ranking                       |
| `keyword`         | Full-text search boost on top of filters            |
| `semantic`        | Vector similarity ranking                           |
| `hybrid`          | Combines keyword and semantic ranking (recommended) |

## Response

```json theme={null}
{
  "listings": [
    {
      "listingId": "a12345",
      "address": "123 Main St, Austin, TX 78701",
      "city": "Austin",
      "state": "TX",
      "zip": "78701",
      "price": "450000",
      "beds": 3,
      "baths": 2,
      "sqft": "1850",
      "photos": ["https://..."],
      "daysOnMarket": 14,
      "description": "Beautiful 3-bed home with updated kitchen...",
      "status": "Active",
      "detailsUrl": "https://...",
      "videoUrls": [{"url": "https://...", "title": "Virtual Tour"}]
    }
  ],
  "total": 47,
  "returned": 12,
  "searchCriteria": {"city": "Austin", "maxPrice": 500000, "minBeds": 3}
}
```