CasafariMCP
Get started

Casafari is the AI agent-native real estate data intelligence platform. The most complete property index in Europe: a deduplicated, cleaned property graph of residential and commercial property, for sale and for rent, in 16 countries.The most complete property index in Europe: a deduplicated, cleaned property graph.

How the graph is built
Markdown Open in Claude Open in ChatGPT

Alerts · REST API

Create feed

POSThttps://api.casafari.com/alerts-api/feeds
Bearer token46 parameters

Send Authorization: Bearer $CASAFARI_TOKEN; see how to get a token.

Over MCP: no tool does this. MCP and REST compared.

Description

Create a new alert feed that delivers matching real estate events to your webhook URL.

Alert Delivery Format

Events are delivered as a POST request with a single JSON object body:

json
{
  "alert_id": 100042,
  "url": "https://www.casafari.com/listing/12345",
  "address": "Rua do Exemplo 12, Lisbon",
  "location": "Lisbon",
  "sale_status": "active",
  "sale_price": 250000,
  "sale_price_psqm": 2500.0,
  "sale_currency": "EUR",
  "rent_status": "none",
  "rent_price": 0,
  "rent_period": "none",
  "rent_price_psqm": 0.0,
  "rent_currency": "EUR",
  "thumbnails": [
    "https://cdn.example.com/thumb1.jpg"
  ],
  "matched_feeds": [
    {
      "feed_id": 42,
      "feed_name": "My Alert Feed"
    }
  ]
}

Your server must respond with HTTP 200. Any other status code is treated as a failure.

Before You Start: Configure Your Webhook

Feeds deliver to your per-user webhook URL — one URL for all feeds, managed separately:

  1. PUT /webhooks — set your delivery URL (it is probed with a GET and must answer 200)
  2. Create feeds — this endpoint returns 409 until the webhook is configured

Changing the URL via PUT /webhooks instantly affects all feeds, including already-queued alerts.

Retry Policy

If your server does not respond with HTTP 200 within 5 seconds, delivery is retried — 60 seconds after the first failure, then every 10 minutes — until the alert expires (typically 24h). Feeds are never disabled automatically.

Authentication of deliveries

Every delivery is signed with Standard Webhooks: each POST carries webhook-id, webhook-timestamp, and webhook-signature headers. Verify the HMAC-SHA256 signature over the raw request body using the secret from PUT /webhooks (rotate it via POST /webhooks/rotate-secret).

Request body

Content type application/json. Required. Type: object.

feed_namestringrequired
filtersobjectrequired
28 properties
location_idsinteger[]nullable
1–100 items
typesstring[]nullable
42 allowed valuesapartment studio duplex penthouse dachgeschosswohnung etagenwohnung erdgeschosswohnung country_house house palace townhouse villa country_estate chalet bungalow family_house reihenhaus reihenendhaus reihenmittelhaus einfamilienhaus zweifamilienhaus landwirtschaftliche_betriebe retail office industrial warehouse hotel building other_commercial restaurant werkstatt urban_plot rural_plot room parking garage other apartment_building office_building mix_use_building apartment_development house_development
at least 1 item
business_typestringrequired
sale rent
statuses(string | string)[]nullable
at least 1 item
alert_subtypesstring[]nullable
new price_increased price_decreased reserved delisted sold
custom_locationsobject[][]nullable
List of closed polygons of geo-points to search within. Each polygon must contain at least 4 points. First and last points must match in each polygon. Maximum 4 polygons allowed.
1–4 items4–25 items
2 properties
latitudenumberrequired
-90–90
longitudenumberrequired
-180–180
privatebooleannullable
price_rangeobjectnullable
2 properties
minintegernullable
1–2147483647
maxintegernullable
1–2147483647
price_psqm_rangeobjectnullable
2 properties
minintegernullable
1–2147483647
maxintegernullable
1–2147483647
bathrooms_rangeobjectnullable
2 properties
minintegernullable
1–15000
maxintegernullable
1–15000
bedrooms_rangeobjectnullable
2 properties
minintegernullable
0–15000
maxintegernullable
0–15000
total_area_rangeobjectnullable
2 properties
minintegernullable
1–1000000
maxintegernullable
1–1000000
new_developmentbooleannullable
bankbooleannullable
auctionbooleannullable
construction_year_rangeobjectnullable
2 properties
minintegernullable
1–3000
maxintegernullable
1–3000
plot_area_rangeobjectnullable
2 properties
minintegernullable
1–1000000
maxintegernullable
1–1000000
floorsstring[]nullable
no_floor ground middle top
at least 1 item
conditionsstring[]nullable
new used ruin very-good other
at least 1 item
orientationstringnullable
exterior interior
viewsstring[]nullable
A matching listing must have every requested view, not just one.
water landscape city golf park
at least 1 item
directionsstring[]nullable
A matching listing must face every requested direction, not just one.
north south east west
at least 1 item
characteristicsstring[]nullable
A matching listing must have every requested characteristic, not just one.
balcony elevator no_elevator garage garden parking storage swimming_pool terrace rental_license furniture rented_out life_annuity
at least 1 item
has_phonebooleannullable
has_emailbooleannullable
has_agency_namebooleannullable
ref_numbersstring[]nullable
1–100 items
listing_idsinteger[]nullable
1–100 items

Example request

Placeholders only: replace the token and the values with your own.

curl
curl -X POST "https://api.casafari.com/alerts-api/feeds" \
  -H "Authorization: Bearer $CASAFARI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "feed_name": "<feed_name>",
  "filters": {
    "business_type": "sale"
  }
}'

Responses

200 Successful Response

Type: object.

Show the response shape (47 fields)
feed_idintegerrequired
feed_namestringrequired
filtersobjectrequired
28 properties
location_idsinteger[]nullable
1–100 items
typesstring[]nullable
42 allowed valuesapartment studio duplex penthouse dachgeschosswohnung etagenwohnung erdgeschosswohnung country_house house palace townhouse villa country_estate chalet bungalow family_house reihenhaus reihenendhaus reihenmittelhaus einfamilienhaus zweifamilienhaus landwirtschaftliche_betriebe retail office industrial warehouse hotel building other_commercial restaurant werkstatt urban_plot rural_plot room parking garage other apartment_building office_building mix_use_building apartment_development house_development
at least 1 item
business_typestringrequired
sale rent
statuses(string | string)[]nullable
at least 1 item
alert_subtypesstring[]nullable
new price_increased price_decreased reserved delisted sold
custom_locationsobject[][]nullable
List of closed polygons of geo-points to search within. Each polygon must contain at least 4 points. First and last points must match in each polygon. Maximum 4 polygons allowed.
1–4 items4–25 items
2 properties
latitudenumberrequired
-90–90
longitudenumberrequired
-180–180
privatebooleannullable
price_rangeobjectnullable
2 properties
minintegernullable
1–2147483647
maxintegernullable
1–2147483647
price_psqm_rangeobjectnullable
2 properties
minintegernullable
1–2147483647
maxintegernullable
1–2147483647
bathrooms_rangeobjectnullable
2 properties
minintegernullable
1–15000
maxintegernullable
1–15000
bedrooms_rangeobjectnullable
2 properties
minintegernullable
0–15000
maxintegernullable
0–15000
total_area_rangeobjectnullable
2 properties
minintegernullable
1–1000000
maxintegernullable
1–1000000
new_developmentbooleannullable
bankbooleannullable
auctionbooleannullable
construction_year_rangeobjectnullable
2 properties
minintegernullable
1–3000
maxintegernullable
1–3000
plot_area_rangeobjectnullable
2 properties
minintegernullable
1–1000000
maxintegernullable
1–1000000
floorsstring[]nullable
no_floor ground middle top
at least 1 item
conditionsstring[]nullable
new used ruin very-good other
at least 1 item
orientationstringnullable
exterior interior
viewsstring[]nullable
A matching listing must have every requested view, not just one.
water landscape city golf park
at least 1 item
directionsstring[]nullable
A matching listing must face every requested direction, not just one.
north south east west
at least 1 item
characteristicsstring[]nullable
A matching listing must have every requested characteristic, not just one.
balcony elevator no_elevator garage garden parking storage swimming_pool terrace rental_license furniture rented_out life_annuity
at least 1 item
has_phonebooleannullable
has_emailbooleannullable
has_agency_namebooleannullable
ref_numbersstring[]nullable
1–100 items
listing_idsinteger[]nullable
1–100 items

409 Webhook is not configured.

Type: object.

Show the response shape (1 fields)
detailstringrequired
Example from the API description
JSON
{
  "detail": "No webhook configured. Set your delivery URL via PUT /webhooks first."
}

422 Validation Error

Type: object.

Show the response shape (6 fields)
detailobject[]
5 properties
loc(string | integer)[]required
msgstringrequired
typestringrequired
inputany
ctxobject

Questions about this

Esc

Tip: add .md to any URL to read it as Markdown.