REST API: a real estate API for AI agents and apps

The same data as the MCP tools, over HTTP: an API for AI agents whose code makes fixed requests, and for any app. To let a model choose the calls instead, use the MCP servers, or call them from the OpenAI API or the Claude API. The REST API is the platform's: https://platform.casafari.com/v1/<product>, one base per product, signed with the platform API key from your console and billed in tokens, the same key and the same tokens as the MCP servers. This reference is generated from the platform's own OpenAPI files (version 2026-10-31.1, vendored 2026-11-02): 37 operations in 9 sections, 7 of them products. Operations are grouped by product, the same way the MCP tools are; MCP and REST compared shows where the two overlap and where they do not. Casafari clients with a contract also keep the existing API at https://api.casafari.com (39 operations, bearer token), documented after the platform's.

#Platform API keys

A first call, with the key in an environment variable ($CASAFARI_API_KEY in every example on this site is a placeholder, never a credential): Comparables, the platform's default product.

curl -X POST "https://platform.casafari.com/v1/comparables/search" \
  -H "Authorization: Bearer $CASAFARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "operation": "sale",
  "comparables_types": [
    "apartment"
  ],
  "bedrooms": 3,
  "total_area": 95,
  "comparables_count": 5,
  "location_boundary": {
    "circle": {
      "target_point": {
        "address": "Calle de Serrano 50, Madrid, Spain"
      },
      "distance": 1
    }
  }
}'

Most products take a location_id: get it first from GET /v1/locations/search (free). GET /v1/account (free) shows your plan and the tokens left.

#Download the OpenAPI description

For Postman (Import → Link, paste the URL), Insomnia, code generators or an agent's tool loader. The platform's files are its own, one per product, public and served by the platform itself; the hub keeps a copy of each (vendored 2026-11-02, version 2026-10-31.1), which these pages are generated from.

Both APIs in one file, every path on its own server (the platform's first), with the examples the existing API's description lacks filled in from real calls: /openapi.json covers every product; per product, /docs/rest/property-sourcing/openapi.json, /docs/rest/seller-leads/openapi.json, /docs/rest/private-sellers/openapi.json, /docs/rest/comparables-valuation/openapi.json, /docs/rest/comparables-with-transactions/openapi.json, /docs/rest/area-insights/openapi.json, /docs/rest/alerts/openapi.json, /docs/rest/references/openapi.json, /docs/rest/parcel-zoning/openapi.json, /docs/rest/locations/openapi.json, /docs/rest/account/openapi.json.

#Operations by product

#Property Sourcing

• POST /v1/property-sourcing/searches: Search properties. Costs 50 tokens a call.
• GET /v1/property-sourcing/searches/{cursor}: Next page of a search. Costs 50 tokens a call.
• GET /v1/property-sourcing/properties/{property_id}: Get a property. Costs 10 tokens a call.
• GET /v1/property-sourcing/properties/{property_id}/closing-prices: Registered sale prices around a property. Costs 5 tokens a call.
• POST /v1/property-sourcing/properties/resolve: Resolve a link or reference to its property. Costs 25 tokens a call.

Existing API (contract clients):

• POST /api/v1/properties/match-by-listings: Get property by listing IDs (v1). Returns a mapping properties IDs to listing IDs.
• POST /api/v1/properties/search: Search properties (v1)
• GET /api/v1/properties/search/{property_id}: Get property by ID (v1). Returns a property object.
• POST /api/v1/properties/smart-links: Create a smart link (BETA) (v1). Generates a smart link that provides detailed property information with customizable components, branding, and user/company information overrides.
• POST /api/v2/properties/search: Search properties (v2)

#High Potential Seller Leads

• GET /v1/seller-leads: List seller leads. Costs 100 tokens a call.
• GET /v1/seller-leads/{lead_id}: Get a seller lead. Costs 10 tokens a call.

#Private Seller Leads

• POST /v1/private-sellers/search: Search private-seller listings by place and date. Costs 10 tokens a call.
• GET /v1/private-sellers/listings/{id}: One private-seller listing. Costs 1 token a call.
• GET /v1/private-sellers/coverage: Countries with private-seller listings and their counts. Free (uses no tokens).

#Comparables & Valuation

• POST /v1/comparables/search: Value a property with comparables. Costs 25 tokens a call.

Existing API (contract clients):

• POST /api/v1/comparables/search: Search comparables (v1). Returns comparable properties by the given parameters.
• POST /api/v2/comparables/ai-builder: Initialize an AI Builder session (v2). Initializes an AI Builder session from a saved CMA (valuation) and returns the generated report ID along with the URL of the AI Builder session.
• POST /api/v2/comparables/search: Search comparables (v2). Returns comparable properties by the given parameters.
• POST /api/v1/valuation/comparables-prices: Search estimated prices (v1). Returns estimated prices by the given parameters.

#Comparables with Transactions

• POST /v1/comparables-transactions/search: Value a property with comparables and registered closing prices. Costs 65 tokens a call.

#Area Insights

• POST /v1/area-insights/analysis: Market analysis of an area. Costs 25 tokens a call.
• POST /v1/area-insights/distributions/properties: Property type distribution in an area. Costs 25 tokens a call.
• POST /v1/area-insights/distributions/prices: Price distribution in an area. Costs 25 tokens a call.
• POST /v1/area-insights/distributions/bedrooms: Bedrooms distribution in an area. Costs 25 tokens a call.
• POST /v1/area-insights/distributions/time-on-market: Time on market distribution in an area. Costs 25 tokens a call.
• POST /v1/area-insights/time-series: Price and activity time series for an area. Costs 25 tokens a call.
• POST /v1/area-insights/heatmap: Heatmap of an area by district. Costs 25 tokens a call.
• POST /v1/area-insights/sales/time-series: Registered sale price trend in an area, week by week. Costs 10 tokens a call.
• POST /v1/area-insights/sales/average-prices: Average registered sale prices by location. Costs 10 tokens a call.
• POST /v1/area-insights/sales/count-by-type: Number of registered sales by property type. Costs 10 tokens a call.

Existing API (contract clients):

• POST /market-analytics-api/time-series: Time Series. Returns time series data for the real estate market.
• POST /market-analytics-api/distributions/bedrooms: Bedrooms Distribution. Returns property distribution based on the number of bedrooms.
• POST /market-analytics-api/distributions/prices: Price Distribution. Returns the number of properties distributed across price ranges.
• POST /market-analytics-api/distributions/properties: Properties Distribution. Returns the properties lightweight data sample and distribution quartiles.
• POST /market-analytics-api/distributions/time-on-market: Time On Market Distribution. Returns time on market (days and months) distribution by price ranges.
• POST /market-analytics-api/analysis: Analysis. Market analysis based on the requested property parameters.

#New Market Leads

• GET /api/v1/listing-alerts/feeds: Get feeds list (v1). Returns all alerts feeds for currently authenticated user.
• POST /api/v1/listing-alerts/feeds: Create feed (v1). Create alerts feed for currently authenticated user.
• GET /api/v1/listing-alerts/feeds/{id}: Get alerts by feed (v1). Returns paginated list of alerts (by feed ID) for currently authenticated user.
• DELETE /api/v1/listing-alerts/feeds/{id}: Delete feed (v1). Delete alerts feed (by feed ID) for currently authenticated user.
• PUT /api/v1/listing-alerts/feeds/{id}/update: Update feed (v1). Update alerts feed by id.
• POST /api/v1/listing-alerts/search: Search alerts (v1). Returns paginated list of alerts (by requested parameters) for currently authenticated user.
• GET /alerts-api/feeds: List feeds. Returns a paginated list of feeds, sorted newest first.
• POST /alerts-api/feeds: Create feed. Create a new alert feed that delivers matching real estate events to your webhook URL.
• GET /alerts-api/feeds/{feed_id}: Get feed. Returns the feed configuration in the same format as it was originally created.
• DELETE /alerts-api/feeds/{feed_id}: Delete feed. Permanently removes the feed.
• PUT /alerts-api/webhooks: Set webhook URL. Sets (or replaces) the delivery URL for all your alert feeds.
• POST /alerts-api/webhooks/rotate-secret: Rotate signing secret. Issues a new current signing secret.

#References

• GET /api/v1/references/agencies: Get agencies (v1). Returns a list of all possible agencies with user restrictions.
• GET /api/v1/references/agents: Get agents (v1). Returns a list of all possible agents with user restrictions.
• GET /api/v1/references/conditions: Get conditions (v1). Returns a list of all possible estate conditions.
• GET /api/v1/references/features: Get features (v1). Returns a list of all possible property features.
• POST /api/v1/references/locations: Get locations (v1). Returns a list of all possible locations with user restrictions.
• GET /api/v1/references/locations/by-coordinates: Get location by passed coordinates (v1). Returns a location for the given coordinates with user restrictions.
• POST /api/v1/references/locations/typeahead: Get locations typeahead suggestions scoped by country code (v1). Returns location typeahead suggestions within the given country (ES or PT).
• GET /api/v1/references/sources: Get sources (v1). Returns a list of all domains for the requested location.
• GET /api/v1/references/types: Get types (v1). Returns a list of all possible estate types.
• POST /api/v1/references/zipcode-boundary: Get zipcode boundary by zipcode and country code (v1). Get zipcode boundary by zipcode and country code.

#Parcel Zoning

• GET /v1/parcel-zoning/es/parcels/{cadastral_ref}: Zoning and buildable area of a parcel by cadastral reference. Costs 5 tokens a call.
• GET /v1/parcel-zoning/es/parcels: Zoning and buildable area of the parcel at a point. Costs 5 tokens a call.
• GET /v1/parcel-zoning/de/parcels/{cadastral_ref}: Zoning and buildable area of a German parcel by Flurstückskennzeichen. Costs 5 tokens a call.
• GET /v1/parcel-zoning/de/parcels: Zoning and buildable area of the German parcel at a point. Costs 5 tokens a call.
• GET /v1/parcel-zoning/coverage: Regions covered, with parcel counts and data dates. Free (uses no tokens).
• GET /v1/parcel-zoning/health: Service status. Free (uses no tokens).

#Location Lookup

• GET /v1/locations/search: Search locations by name or postcode. Free (uses no tokens).
• GET /v1/locations/{location_id}: Get a location with its parents. Free (uses no tokens).
• GET /v1/locations/{location_id}/children: List the child locations of a location. Free (uses no tokens).
• GET /v1/locations/by-coordinates: Find the locations that contain a point. Free (uses no tokens).

#Account and sign-up

• GET /v1/account: Account status: plan, tokens and limits. Free (uses no tokens).
• GET /v1/account/payment-links/{payment_link_id}: Status of a payment link. Free (uses no tokens).
• GET /v1/signups/terms: Read the current terms
• POST /v1/signups: Start a sign-up. Emails a 6-digit code to the person.
• POST /v1/signups/{signup_id}/verify: Finish a sign-up with the emailed code. Returns the account and an API key, shown once.

#Authentication

• POST /login: Login
• GET /refresh-token: Refresh Token

#The existing API (contract clients)

Already a Casafari API customer? Your token keeps working, and the existing API's reference is now on this site. Log in to your API account to see your token.

Casafari clients with a contract also have the existing REST API at https://api.casafari.com, documented at docs.api.casafari.com, which signs in with an email and password and a bearer token. The platform does not replace it: a contract client keeps it as it is, and signs up on the platform as well for the platform's products (with a contract, Casafari sets the account up on the Custom plan). New users need only the platform. Its operations are listed under each product after the platform's, under "Existing API (contract clients)": Property Sourcing, Comparables & Valuation, Area Insights, New Market Leads, References; New Market Leads and References have no platform operation yet. This part is generated from its public OpenAPI description (OpenAPI 3.1.0, API version 0.1.0, snapshot taken 2026-10-08): 39 operations, sign-in included.

The API description says about the token:

The API endpoints require an authentication token to be provided with each request. The token must be sent via the Authorization HTTP header, containing the keyword Bearer followed by your authentication token.

The public description lists the base catalogue. What your account can call depends on its subscription, and the interactive docs show your account's own list after you sign in. For agents, auth.md covers both ways of signing in.

#Get a token

1. Call POST /login with your account's email and password. The response has an access_token and a refresh_token.
2. Send Authorization: Bearer <access_token> with every other request.
3. When the access token expires, call GET /refresh-token with the refresh token as the bearer. A 401 from it means the refresh token has expired: log in again.

curl -X POST "https://api.casafari.com/login" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "<email>",
  "password": "<password>"
}'

Then, with the token in an environment variable ($CASAFARI_TOKEN in every example of the existing API on this site is a placeholder, never a credential):

curl "https://api.casafari.com/api/v1/references/types" \
  -H "Authorization: Bearer $CASAFARI_TOKEN"

#Status codes

Every operation documents its own responses. Across both descriptions:

#Read this reference as Markdown

Add .md to any page's URL, or send Accept: text/markdown. /llms.txt lists every operation next to every MCP tool.

#Questions about this

• What is Casafari MCP?
• Which address do I use: api.casafari.com or platform.casafari.com (mcp.casafari.com is the legacy gateway)?
• I already have Casafari MCP or API access. Does anything change for me?
• How do I get an API key and make my first call?
• Can I read these docs as Markdown, and is there an llms.txt?