# REST API

> **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. Every property is one record with its full price and market history. [How the property graph is built](/docs/property-graph).

The same data as the MCP tools, over HTTP. This reference is generated from the API's public OpenAPI description (OpenAPI 3.1.0, API version 0.1.0): 35 paths and 39 operations, snapshot taken 2026-10-08. Operations are grouped by product, the same way the MCP tools are; [MCP and REST compared](/docs/parity) shows where the two overlap and where they do not.

## Base URL and authentication

| | |
|---|---|
| Base URL | `https://api.casafari.com` |
| Format | JSON requests and responses |
| Authentication | A bearer token (JWT) that you get with your account's email and password. REST does not use OAuth; that is for [MCP](/docs/authentication). |
| OpenAPI description | [https://docs.api.casafari.com/openapi.json](https://docs.api.casafari.com/openapi.json) (public, no sign-in needed) |
| Interactive docs | [https://docs.api.casafari.com/](https://docs.api.casafari.com/) |

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](https://www.casafari.com/auth.md) covers both ways of signing in.

### Get a token

1. Call [`POST /login`](/docs/rest/authentication/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`](/docs/rest/authentication/refresh-token) with the refresh token as the bearer. A `401` from it means the refresh token has expired: log in again.

```bash
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 on this site is a placeholder, never a credential):

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

## Operations by product

### [Properties](/docs/rest/properties)

- [`POST /api/v1/properties/match-by-listings`](/docs/rest/properties/get-property-by-listing-ids-v1): Get property by listing IDs (v1). Returns a mapping properties IDs to listing IDs.
- [`POST /api/v1/properties/search`](/docs/rest/properties/search-properties-v1): Search properties (v1)
- [`GET /api/v1/properties/search/{property_id}`](/docs/rest/properties/get-property-by-id-v1): Get property by ID (v1). Returns a property object.
- [`POST /api/v1/properties/smart-links`](/docs/rest/properties/create-a-smart-link-beta-v1): 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`](/docs/rest/properties/search-properties-v2): Search properties (v2)

### [Comparables & Valuation](/docs/rest/comparables-valuation)

- [`POST /api/v1/comparables/search`](/docs/rest/comparables-valuation/search-comparables-v1): Search comparables (v1). Returns comparable properties by the given parameters.
- [`POST /api/v2/comparables/ai-builder`](/docs/rest/comparables-valuation/initialize-an-ai-builder-session-v2): 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`](/docs/rest/comparables-valuation/search-comparables-v2): Search comparables (v2). Returns comparable properties by the given parameters.
- [`POST /api/v1/valuation/comparables-prices`](/docs/rest/comparables-valuation/search-estimated-prices-v1): Search estimated prices (v1). Returns estimated prices by the given parameters.

### [Area Insights](/docs/rest/area-insights)

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

### [Alerts](/docs/rest/alerts)

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

### [References](/docs/rest/references)

- [`GET /api/v1/references/agencies`](/docs/rest/references/get-agencies-v1): Get agencies (v1). Returns a list of all possible agencies with user restrictions.
- [`GET /api/v1/references/agents`](/docs/rest/references/get-agents-v1): Get agents (v1). Returns a list of all possible agents with user restrictions.
- [`GET /api/v1/references/conditions`](/docs/rest/references/get-conditions-v1): Get conditions (v1). Returns a list of all possible estate conditions.
- [`GET /api/v1/references/features`](/docs/rest/references/get-features-v1): Get features (v1). Returns a list of all possible property features.
- [`POST /api/v1/references/locations`](/docs/rest/references/get-locations-v1): Get locations (v1). Returns a list of all possible locations with user restrictions.
- [`GET /api/v1/references/locations/by-coordinates`](/docs/rest/references/get-location-by-passed-coordinates-v1): Get location by passed coordinates (v1). Returns a location for the given coordinates with user restrictions.
- [`POST /api/v1/references/locations/typeahead`](/docs/rest/references/get-locations-typeahead-suggestions-scoped-by-country-code-v1): 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`](/docs/rest/references/get-sources-v1): Get sources (v1). Returns a list of all domains for the requested location.
- [`GET /api/v1/references/types`](/docs/rest/references/get-types-v1): Get types (v1). Returns a list of all possible estate types.
- [`POST /api/v1/references/zipcode-boundary`](/docs/rest/references/get-zipcode-boundary-by-zipcode-and-country-code-v1): Get zipcode boundary by zipcode and country code (v1). Get zipcode boundary by zipcode and country code.

### [Authentication](/docs/rest/authentication)

- [`POST /login`](/docs/rest/authentication/login): Login
- [`GET /refresh-token`](/docs/rest/authentication/refresh-token): Refresh Token

## Status codes

Every operation documents its own responses. Across the description:

| Status | Meaning | Operations that can return it |
|---|---|---|
| `200` | OK | 38 |
| `201` | Created | 1 |
| `204` | No Content | 5 |
| `400` | Bad Request | 15 |
| `401` | Unauthorized | 25 |
| `403` | Forbidden | 25 |
| `404` | Not Found | 8 |
| `409` | Conflict | 1 |
| `422` | Validation Error | 13 |

## Read this reference as Markdown

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

## Questions about this

- [What is the difference between Casafari MCP and the Casafari REST API?](/docs/faq/mcp-vs-rest-api)
- [How does authentication work on Casafari MCP? Does it use OAuth scopes?](/docs/faq/how-authentication-works)
- [How do I authenticate with the Casafari REST API?](/docs/faq/rest-authentication)
- [How do I build on the Casafari REST API?](/docs/faq/build-on-rest)