For AI agents: Preview: contract may change. The MCP endpoint is coming soon.
search_listings
Start with the renter's housing request in query. Fairway interprets supported criteria as filters and reports what it applied. The worked examples below are illustrative; the input and output schemas follow them and come from the checked-in preview contract.
Purpose#
Find rental listings in SF Bay Area from the renter's housing request.
When to use / when not to use#
Use for a new rental search. Send the housing request, not personal details.
Access#
Preview: contract may change. Planned open access without an API key. The endpoint is coming soon.
Annotations#
readOnlyHint: true, openWorldHint: false (preview).
Example request#
Illustrative preview only. This is not a callable endpoint.
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "search_listings",
"arguments": {
"query": "2BR near BART under $3,000, dog friendly, on a quiet street"
}
}
}
Pin a value with filters when it must override what Fairway reads from the query:
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "search_listings",
"arguments": {
"query": "2BR near BART under $3,000, dog friendly",
"filters": {
"rent_max": 280000
}
}
}
}
Example response#
Illustrative shape only. Listing IDs, values, and URLs below are examples.
{
"applied_filters": {
"beds_min": 2,
"rent_max": 300000,
"pets": "dog"
},
"not_applied": [
"quiet street"
],
"listings": [
{
"id": "example-listing-1",
"status": "available",
"property": {
"name": "Example home",
"address": "Example address"
},
"rent_min": 295000,
"beds_min": 2,
"checked_at": "2026-10-30T00:00:00Z",
"listing_url": "https://fairwayrent.ai/property/ca/menlo-park/example",
"share_url": "https://fairwayrent.ai/property/ca/menlo-park/example"
}
],
"pagination": {
"has_next_page": false,
"limit": 25
},
"checked_at_range": {
"oldest": "2026-10-30T00:00:00Z",
"newest": "2026-10-30T00:00:00Z"
},
"map_url": "https://www.fairwayrent.ai/map?l=example-listing-1"
}
Input schema#
| Field | Type | Notes |
|---|---|---|
query | string | The renter's housing request in their own words, such as a two-bedroom near transit under their stated budget that allows dogs. Fairway turns it into filters. Send the housing request, not personal details. |
filters | object | Optional structured fields. Any field here overrides what Fairway took from the query. |
bbox | object | A map box in degrees. If neither filters.area nor query names a metro, Fairway searches the metro that contains the center of the box. |
near | object | A point and radius in meters. For now Fairway searches the box that contains this circle. If neither filters.area nor query names a metro, Fairway searches the metro that contains the point. |
pagination | object | See JSON Schema |
{
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 1,
"description": "The renter's housing request in their own words, such as a two-bedroom near transit under their stated budget that allows dogs. Fairway turns it into filters. Send the housing request, not personal details.",
"maxLength": 1000
},
"filters": {
"type": "object",
"description": "Optional structured fields. Any field here overrides what Fairway took from the query.",
"properties": {
"beds_min": {
"type": "number",
"minimum": 0,
"maximum": 20
},
"beds_max": {
"type": "number",
"minimum": 0,
"maximum": 20
},
"baths_min": {
"type": "number",
"minimum": 0,
"maximum": 20
},
"rent_min": {
"type": "integer",
"minimum": 0,
"description": "USD cents",
"maximum": 10000000
},
"rent_max": {
"type": "integer",
"minimum": 0,
"description": "USD cents",
"maximum": 10000000
},
"pets": {
"type": "string",
"enum": [
"dog",
"cat",
"none"
]
},
"move_in_by": {
"type": "string",
"format": "date"
},
"amenities": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"maxItems": 32
},
"area": {
"type": "string",
"description": "City, neighborhood, or area to search.",
"minLength": 1,
"maxLength": 200
}
},
"additionalProperties": false
},
"bbox": {
"type": "object",
"description": "A map box in degrees. If neither filters.area nor query names a metro, Fairway searches the metro that contains the center of the box.",
"properties": {
"north": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"south": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"east": {
"type": "number",
"minimum": -180,
"maximum": 180
},
"west": {
"type": "number",
"minimum": -180,
"maximum": 180
}
},
"required": [
"north",
"south",
"east",
"west"
],
"additionalProperties": false
},
"near": {
"type": "object",
"description": "A point and radius in meters. For now Fairway searches the box that contains this circle. If neither filters.area nor query names a metro, Fairway searches the metro that contains the point.",
"properties": {
"lat": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"lng": {
"type": "number",
"minimum": -180,
"maximum": 180
},
"radius_m": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 50000
}
},
"required": [
"lat",
"lng",
"radius_m"
],
"additionalProperties": false
},
"pagination": {
"type": "object",
"properties": {
"cursor": {
"type": "string",
"minLength": 1,
"maxLength": 4096
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 25,
"default": 25,
"description": "Listings per page. Calls without an API key get at most 5."
}
},
"additionalProperties": false
}
},
"additionalProperties": false,
"required": [
"query"
]
}
Output schema#
| Field | Type | Notes |
|---|---|---|
applied_filters | object | Filters Fairway applied from the query and any explicit filters overrides. |
not_applied | array | Parts of the query that did not become a filter, such as quiet street. The agent may use these for its own ranking. |
listings | array | See JSON Schema |
pagination | object | See JSON Schema |
checked_at_range | object | See JSON Schema |
map_url | string | See JSON Schema |
{
"type": "object",
"properties": {
"applied_filters": {
"type": "object",
"description": "Filters Fairway applied from the query and any explicit filters overrides.",
"properties": {
"beds_min": {
"type": "number",
"minimum": 0
},
"beds_max": {
"type": "number",
"minimum": 0
},
"baths_min": {
"type": "number",
"minimum": 0
},
"rent_min": {
"type": "integer",
"minimum": 0,
"description": "USD cents"
},
"rent_max": {
"type": "integer",
"minimum": 0,
"description": "USD cents"
},
"pets": {
"type": "string",
"enum": [
"dog",
"cat",
"none"
]
},
"move_in_by": {
"type": "string",
"format": "date"
},
"amenities": {
"type": "array",
"items": {
"type": "string"
}
},
"area": {
"type": "string",
"description": "City, neighborhood, or area to search."
}
},
"additionalProperties": false
},
"not_applied": {
"type": "array",
"description": "Parts of the query that did not become a filter, such as quiet street. The agent may use these for its own ranking.",
"items": {
"type": "string"
}
},
"listings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"const": "available"
},
"property": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"address": {
"type": "string"
},
"coordinates": {
"type": "object",
"properties": {
"lat": {
"type": "number"
},
"lng": {
"type": "number"
}
}
}
}
},
"rent_min": {
"type": "integer",
"minimum": 0,
"description": "USD cents"
},
"rent_max": {
"type": "integer",
"minimum": 0,
"description": "USD cents"
},
"beds_min": {
"type": "number"
},
"checked_at": {
"type": "string",
"format": "date-time"
},
"listing_url": {
"type": "string",
"format": "uri"
},
"share_url": {
"type": "string",
"format": "uri"
}
},
"required": [
"id",
"status",
"property",
"checked_at",
"listing_url",
"share_url"
]
}
},
"pagination": {
"type": "object",
"properties": {
"cursor": {
"type": "string"
},
"has_next_page": {
"type": "boolean"
},
"total_count": {
"type": "integer",
"minimum": 0,
"description": "Estimate, not exact"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 25,
"description": "Listings per page for this call."
}
},
"required": [
"has_next_page",
"limit"
]
},
"checked_at_range": {
"type": "object",
"properties": {
"oldest": {
"type": "string",
"format": "date-time"
},
"newest": {
"type": "string",
"format": "date-time"
}
}
},
"map_url": {
"type": "string",
"format": "uri"
}
},
"required": [
"applied_filters",
"not_applied",
"listings",
"pagination",
"checked_at_range",
"map_url"
]
}
Errors#
These codes come from the MCP service in development. They can change before launch.
A request error is a tool result with isError: true. Its structuredContent has the HTTP status, a code, and the path of the field at fault. The same JSON is also the text content of the result.
{
"status": 400,
"code": "UNKNOWN_FIELD",
"path": "filters.radius"
}
| Code | Path | Meaning |
| --- | --- | --- |
| UNKNOWN_FIELD | The unknown field | The request has a field that the schema does not list. Remove it. |
| MALFORMED_REQUEST | The invalid field | A field has the wrong type or is out of range. Fix the value. |
| UNKNOWN_AMENITY | filters.amenities.<index> | The amenity is not in the filter vocabulary. Remove it or put it in query. |
| CONFLICTING_CRITERIA | near or a filter | The request sends both bbox and near, or a minimum is above its maximum. |
| AREA_REQUIRED | filters.area | Neither the request nor query names an area. Send filters.area, bbox, or near. |
| AREA_UNRESOLVED | filters.area | Fairway cannot find the named area. Ask the renter for a city or neighborhood. |
| UNSUPPORTED_METRO | filters.area, bbox, or near | The area is outside the metros that Fairway serves. |
| METRO_NOT_ADMITTED | filters.area, bbox, or near | Fairway serves the metro, but agent search does not cover it yet. |
| NO_SEARCH_SCOPE | scope | Fairway could not build a search area from the request. |
| UNSUPPORTED_CRITERION | The criterion | Search cannot apply this criterion. Remove it or put it in query. |
| SEARCH_TOO_BROAD | filters | The search matches too much inventory. Add an area or narrower filters. |
| CURSOR_EXPIRED | pagination.cursor | The cursor is no longer valid. Run the search again without cursor. |
If the service times out or cannot read its data, the result has isError: true and { "error": ... } with search_timeout or search_unavailable. Retry later with the same request.
Rate limits and API key problems are not tool results. They are JSON-RPC errors. error.data.error names the problem, and error.code is the number below for that name. A rate-limit error also has error.data.retry_after in seconds and a Retry-After header. Wait that long before you retry.
{
"rate_limited": -31001,
"invalid_api_key": -31002,
"insufficient_scope": -31003
}
Notes for agents#
Send the renter’s housing request as they said it, without personal details. Use filters only to pin a value. Rank on not_applied and your own context. Check checked_at before describing availability and link to the Fairway listing.