# Ask about a search you show

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

`POST https://platform.casafari.com/v1/claro/search/ask`

[Claro AI](/docs/claro) · [REST API](/docs/claro#rest-api). Send `Authorization: Bearer $CASAFARI_API_KEY`: a platform API key or OAuth access token, metered in platform tokens; see [platform sign-in](/docs/rest#platform-api-keys) and [Claro AI](/docs/claro#keys). On the platform this is `POST https://platform.casafari.com/v1/claro/search/ask`; `POST /v1/search/ask` is Claro's own path, which the platform adds `/claro` to. The platform forwards the call to Claro unchanged: Claro's `Claro-Version` header and its error bodies (`{"error":{"code","message"}}`, with `rate_limited` and `quota_reached` on a 429) pass through.

Over MCP: no tool does this; it is REST only. See [MCP and REST compared](/docs/parity#claro-ai).

## Description

A free question about a search you show your user ("why only 180?", "which has the longest frontage?"), answered by a model from that search and the read-only operations (get_premises, compare_premises, market_snapshot) on your account. Every number in the answer is checked against the search and those results, and a sentence with any other number is dropped (counted in `dropped`); a sentence naming a property portal is dropped; a link survives only when it is a `listing_url` from the data. `answer` is null when nothing survived. When the user asks to change the search, `change` is the change in plain words for POST /v1/search/refine and `answer` says what will change. Counted against the account's daily calls like a search.

## Request body

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

- `question` (string, required) at most 2000 characters.
- `search` (object, required): The search as you show it: a POST /v1/search answer (criteria, counts, notes, results), optionally with `prev` (the search it replaced: at, criteria, counts).
- `history` (object[], optional): The conversation so far, oldest first (the last 8 are read).
  - `role` (string, required) Values: `user`, `assistant`.
  - `text` (string, required)
- `lang` (string, optional): The language to answer in when the question's own language is unclear. Values: `en`, `de`, `es`.

## Example request

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

```bash
curl -X POST "https://platform.casafari.com/v1/claro/search/ask" \
  -H "Authorization: Bearer $CASAFARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "question": "<question>",
  "search": {}
}'
```

## Responses

### 200 The checked answer, or the change to apply

Type: `object`.

- `answer` (string, required): Markdown.
- `change` (string, required)
- `dropped` (object, required)
  - `numbers` (integer, optional)
  - `portals` (integer, optional)
  - `links` (integer, optional)
- `model` (string, required)
- `usage` (object, required)
  - `rounds` (integer, optional)
  - `input_tokens` (integer, optional)
  - `output_tokens` (integer, optional)
  - `ms` (integer, optional)

### 400 Invalid request

Type: `object`.

- `error` (object, optional)
  - `code` (string, required)
  - `message` (string, required)

### 401 Missing or invalid key

Type: `object`.

- `error` (object, optional)
  - `code` (string, required)
  - `message` (string, required)

### 403 No access

Type: `object`.

- `error` (object, optional)
  - `code` (string, required)
  - `message` (string, required)

### 429 Rate limited

Type: `object`.

- `error` (object, optional)
  - `code` (string, required)
  - `message` (string, required)

## Related pages

- [Search commercial premises (POST /v1/search)](/docs/rest/claro/search-premises)
- [Refine a search (POST /v1/search/refine)](/docs/rest/claro/refine-search)
- [Get one premises (GET /v1/premises/{id})](/docs/rest/claro/get-premises)
- [Compare premises (POST /v1/compare)](/docs/rest/claro/compare-premises)
- [Claro AI: all its MCP tools and REST operations](/docs/claro)
- [Connect Claro to an MCP client](/docs/claro/connect)
- [MCP vs REST API compared](/docs/parity)