> ## 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. # Search MLS property listings > Searches live MLS listings for a brokerage. Routes automatically to IDX Broker or the brokerage's custom database depending on their integration type. Supports both structured filters (price, beds, city) and semantic/ natural-language queries via hybrid search mode. **Search modes:** - `structured_only` — only apply hard filters, no ranking - `keyword` — full-text search boost on top of filters - `semantic` — vector similarity ranking - `hybrid` — combines keyword and semantic ranking (default) ## OpenAPI ````yaml openapi.yaml post /v1/listings/search openapi: 3.1.0 info: title: ARIS API version: 1.0.0 description: > The ARIS API provides programmatic access to the AI real estate assistant engine, MLS listing search, widget configuration, and lead management. ## Authentication All requests must include your developer API key in the `X-ARIS-API-Key` header. Obtain a key from the ARIS dashboard under **Settings → Developer Keys**. ``` X-ARIS-API-Key: your-api-key ``` Your API key is scoped to your brokerage. The `brokerageId` field in request bodies must match the brokerage associated with your key. ## Base URL ``` https://dqgynnlsclfbqysauesf.supabase.co/functions/v1/api-router ``` ## Rate Limits Requests are subject to your plan's monthly credit allowance. Each `/v1/chat` request consumes credits proportional to token usage. Listing search and config endpoints do not consume credits. ## Streaming The `/v1/chat` endpoint returns a Server-Sent Events (SSE) stream in OpenAI-compatible delta format. Each event is: ``` data: {"choices":[{"delta":{"content":"..."},"index":0}]} ``` The stream ends with: ``` data: [DONE] ``` servers: - url: https://dqgynnlsclfbqysauesf.supabase.co/functions/v1/api-router description: Production security: - ApiKeyAuth: [] paths: /v1/listings/search: post: summary: Search MLS property listings description: | Searches live MLS listings for a brokerage. Routes automatically to IDX Broker or the brokerage's custom database depending on their integration type. Supports both structured filters (price, beds, city) and semantic/ natural-language queries via hybrid search mode. **Search modes:** - `structured_only` — only apply hard filters, no ranking - `keyword` — full-text search boost on top of filters - `semantic` — vector similarity ranking - `hybrid` — combines keyword and semantic ranking (default) operationId: searchListings requestBody: required: true content: application/json: schema: type: object required: - brokerageId properties: brokerageId: type: string example: 550e8400-e29b-41d4-a716-446655440000 city: type: string example: Austin state: type: string example: TX zip: type: string example: '78701' minPrice: type: number example: 200000 maxPrice: type: number example: 500000 minBeds: type: integer example: 3 maxBeds: type: integer example: 5 minBaths: type: number example: 2 maxBaths: type: number minSqFt: type: integer example: 1500 maxSqFt: type: integer propertyType: type: string example: Single Family statuses: type: array items: type: string default: - Active example: - Active - Coming Soon hasPool: type: boolean isWaterfront: type: boolean hasGarage: type: boolean minYearBuilt: type: integer example: 2000 maxDaysOnMarket: type: integer example: 30 semanticQuery: type: string description: Natural language query for semantic/hybrid ranking. example: modern open floor plan with updated kitchen keywords_must: type: array items: type: string description: Terms that must appear in the listing description. example: - pool - granite keywords_not: type: array items: type: string description: Terms to exclude from results. example: - fixer upper mode: type: string enum: - structured_only - keyword - semantic - hybrid default: hybrid limit: type: integer default: 12 maximum: 24 example: 12 example: brokerageId: 550e8400-e29b-41d4-a716-446655440000 city: Austin state: TX maxPrice: 500000 minBeds: 3 mode: hybrid semanticQuery: modern home with updated kitchen limit: 12 responses: '200': description: Listing search results. content: application/json: schema: type: object properties: listings: type: array items: $ref: '#/components/schemas/Listing' total: type: integer description: Total number of listings matching the criteria. returned: type: integer description: >- Number of listings in this response (may be less than total due to limit). searchCriteria: $ref: '#/components/schemas/SearchCriteria' message: type: string nullable: true description: >- Optional message explaining empty results or fallback behavior. '400': description: Missing required fields. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: Listing: type: object description: A normalized MLS property listing. properties: listingId: type: string description: Unique listing identifier from the MLS. example: a12345 address: type: string example: 123 Main St, Austin, TX 78701 city: type: string example: Austin state: type: string example: TX zip: type: string example: '78701' price: oneOf: - type: string - type: number description: Listing price. May be a formatted string or numeric value. example: '450000' beds: type: number example: 3 baths: type: number example: 2 sqft: oneOf: - type: string - type: number example: '1850' photos: type: array items: type: string format: uri description: Array of photo URLs, ordered with primary photo first. daysOnMarket: type: integer example: 14 description: type: string nullable: true description: Listing remarks, truncated to 200 characters. status: type: string example: Active detailsUrl: type: string format: uri nullable: true description: Full-detail listing URL on the IDX Broker-hosted page. videoUrls: type: array nullable: true items: type: object properties: url: type: string format: uri title: type: string nullable: true description: Video tour URLs attached to this listing, if any. SearchCriteria: type: object description: Echo of the search parameters that were applied. additionalProperties: true ErrorResponse: type: object required: - error properties: error: type: string description: Human-readable error message. example: brokerageId is required securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-ARIS-API-Key ````