AGENT DOCUMENTATIONPreview

For AI agents: Preview: contract may change. The MCP endpoint is coming soon.

get_listing

.md

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.

json

{
  "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.

json

{
  "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#

FieldTypeNotes
idstringSee JSON Schema
json

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false
}

Output schema#

FieldTypeNotes
idstringSee JSON Schema
statusstringavailable has unit detail. leased has an empty units list.
propertyobjectSee JSON Schema
rent_minintegerUSD cents
rent_maxintegerUSD cents
beds_minnumberSee JSON Schema
checked_atstringSee JSON Schema
listing_urlstringSee JSON Schema
share_urlstringSee JSON Schema
unitsarraySee JSON Schema
feesobjectSee JSON Schema
policiesarraySee JSON Schema
amenitiesarraySee JSON Schema
photosarraySee JSON Schema
nearby_transitarraySee JSON Schema
json

{
  "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.

json

{
  "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.

json

{
  "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.