For AI agents: Preview: contract may change. The MCP endpoint is coming soon.
get_listing
A field that is missing is unknown, not false. A leased listing has no units. The input and output schemas below are generated from the checked-in preview contract.
Purpose#
Inspect one listing, including property details and available unit evidence.
When to use / when not to use#
Use when a renter wants detail on one known listing. Do not treat unknown fields as promises.
Access#
Preview: contract may change. Planned open access without an API key. The endpoint is coming soon.
Annotations#
readOnlyHint: true, idempotentHint: true, openWorldHint: false (preview).
Example request#
Illustrative preview only. This is not a callable endpoint.
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "get_listing",
"arguments": {
"id": "listing-id"
}
}
}
Example response#
Illustrative shape only. Listing IDs, values, and URLs below are examples.
{
"id": "listing-id",
"status": "available",
"property": {
"name": "Example property",
"address": "Example address"
},
"units": [
{
"id": "unit-id",
"rent": 295000,
"beds": 2,
"baths": 1
}
],
"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"
}
Input schema#
| Field | Type | Notes |
|---|---|---|
id | string | See JSON Schema |
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
}
},
"required": [
"id"
],
"additionalProperties": false
}
Output schema#
| Field | Type | Notes |
|---|---|---|
id | string | See JSON Schema |
status | string | available has unit detail. leased has an empty units list. |
property | object | See JSON Schema |
rent_min | integer | USD cents |
rent_max | integer | USD cents |
beds_min | number | See JSON Schema |
checked_at | string | See JSON Schema |
listing_url | string | See JSON Schema |
share_url | string | See JSON Schema |
units | array | See JSON Schema |
fees | object | See JSON Schema |
policies | array | See JSON Schema |
amenities | array | See JSON Schema |
photos | array | See JSON Schema |
nearby_transit | array | See JSON Schema |
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"available",
"leased"
],
"description": "available has unit detail. leased has an empty units list."
},
"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"
},
"units": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"rent": {
"type": "integer",
"minimum": 0,
"description": "USD cents"
},
"beds": {
"type": "number"
},
"baths": {
"type": "number"
},
"available_at": {
"type": "string",
"format": "date"
}
}
}
},
"fees": {
"type": "object",
"properties": {
"application": {
"type": "integer",
"minimum": 0,
"description": "USD cents"
},
"deposit": {
"type": "integer",
"minimum": 0,
"description": "USD cents"
},
"pet_rent": {
"type": "integer",
"minimum": 0,
"description": "USD cents"
},
"pet_deposit": {
"type": "integer",
"minimum": 0,
"description": "USD cents"
},
"parking": {
"type": "integer",
"minimum": 0,
"description": "USD cents"
},
"utilities": {
"type": "integer",
"minimum": 0,
"description": "USD cents"
}
}
},
"policies": {
"type": "array",
"items": {
"type": "string"
}
},
"amenities": {
"type": "array",
"items": {
"type": "string"
}
},
"photos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"alt": {
"type": "string"
}
},
"required": [
"url",
"alt"
]
},
"maxItems": 20
},
"nearby_transit": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"status",
"checked_at",
"units"
],
"oneOf": [
{
"properties": {
"status": {
"const": "available"
}
},
"required": [
"status",
"property",
"listing_url",
"share_url"
],
"type": "object"
},
{
"properties": {
"status": {
"const": "leased"
},
"units": {
"maxItems": 0
}
},
"type": "object",
"required": [
"status"
]
}
]
}
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. |
| NOT_FOUND | id | The ID is unknown, merged into another listing, or outside the metros that Fairway serves. Fairway does not follow a merged ID. |
If the service times out or cannot read its data, the result has isError: true and { "error": ... } with listing_timeout or listing_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#
Check checked_at before describing availability. Link to the Fairway listing. Keep renter preferences and ranking in your own context.