# Grounded property tool for an AI assistant

> **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).

**For Builders of AI agents and assistants.** Expose Casafari's describe search, property read and resolve as tools; the agent learns them from /openapi.json and /llms.txt and handles 402 and 429.

> How do I stop my LLM assistant inventing homes and give it real property records to search?

## Why does the assistant hallucinate properties?

Asked for "a 3-bedroom flat in Porto with a terrace under 400k", an LLM with no grounded tool invents addresses and prices. It needs a tool that accepts words rather than a rigid filter schema, returns one record per real property and fails with errors it can act on.

## How does it work step by step?

1. **Teach the schema.** Load [/openapi.json](https://developers.casafari.com/openapi.json) for request and response shapes and [/llms.txt](https://developers.casafari.com/llms.txt) for the documentation; every hub page is also available as Markdown (.md). Property Sourcing is REST only, with no MCP tools.
2. **Tool 1, locate.** `GET /v1/locations/search` turns "Porto" into `location_ids`.
3. **Tool 2, search by words.** `POST /v1/property-sourcing/searches/describe` with up to 20 `tags` taken from the prompt (for example "3 bedrooms", "terrace") or the prompt as `description`, plus `location_ids` and an optional `price` range; each result carries `matched_tags` the assistant can quote.
4. **Tool 3, details.** `GET /v1/property-sourcing/properties/{property_id}?expand=listings,history` grounds any answer about price history, energy rating, condition or where the home is advertised.
5. **Tool 4, pasted links.** `POST /v1/property-sourcing/properties/resolve` maps a URL, agency reference or listing id the user pastes to its `prop_…` id.
6. **Handle errors.** Responses are RFC 9457 problem+json: on 429 `request_limit_reached`, wait for the named window; on 402 `payment_required`, show the human the `upgrade_url`.

```bash
curl -X POST https://platform.casafari.com/v1/property-sourcing/searches/describe \
  -H "Authorization: Bearer $CASAFARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"location_ids": [12345], "tags": ["3 bedrooms", "terrace"], "price": {"max": 400000}, "page_size": 25}'
```

The exact shape of the `price` range is in [/openapi.json](https://developers.casafari.com/openapi.json).

## What do you get?

Answers grounded in the deduplicated, cleaned property graph: `id`, `type`, `operation`, `price` (null when on request), `bedrooms`, `living_area_sqm`, `location`, `first_seen`, `listings_count` and `matched_tags` per property, with ids the assistant can cite across turns. For "homes likely to sell near this point" in Spain, France, Italy, Germany, Greece and Andorra, add [High Potential Seller Leads](https://developers.casafari.com/docs/seller-leads) as a fifth tool; see [Compliant seller-prospecting workflow for an AI agent](https://developers.casafari.com/docs/seller-leads/use-cases/compliant-seller-prospecting-workflow-for-an-ai-agent).

## What are the limits?

Authenticate with a platform API key (`cf_sk_…`) or an OAuth access token as `Authorization: Bearer` or `X-API-Key` ([Platform API keys](https://developers.casafari.com/docs/rest#platform-api-keys)). Guards: Free 10 distinct places a day, 10 requests a minute, 2 concurrent; Agent (EUR 70 a month) and pay as you go 50 places, 20 a minute, 3 concurrent. Describe pages cost 100 units, property reads 10, resolves 25. The API returns no seller contact details, so the assistant must never present any.

## Related use cases

- [Deduplicated buyer shortlist from a plain-language brief](https://developers.casafari.com/docs/property-sourcing/use-cases/deduplicated-buyer-shortlist-from-a-brief)
- [Price-per-sqm value screen across European markets](https://developers.casafari.com/docs/property-sourcing/use-cases/price-per-sqm-value-screen-across-markets)
- [Resolve client-forwarded links to one property record](https://developers.casafari.com/docs/property-sourcing/use-cases/resolve-client-forwarded-links)
- [Shared-mandate and competitor mapping for an office](https://developers.casafari.com/docs/property-sourcing/use-cases/shared-mandate-and-competitor-mapping)
- [How do I build property search into my application with the Casafari REST API?](https://developers.casafari.com/docs/use-cases/property-search-api-for-your-app)
- [Property Sourcing FAQ](https://developers.casafari.com/docs/property-sourcing/faq)