Claro AI · FAQ
Claro API and MCP: developer FAQ
Answers to what developers, product managers and AI agent builders ask about Claro AI. Every answer links the page that documents it.
What are the base URLs for the Claro API and how do I authenticate?
You reach Claro via the platform's live host: https://platform.casafari.com/v1/claro for REST and https://platform.casafari.com/mcp/claro for MCP. The OpenAPI file is at https://platform.casafari.com/v1/claro/openapi.json, calls are metered in "platform tokens", and the Claro-Version header and Claro's error bodies pass through to the client. You authenticate with a platform API key or OAuth, sent as Authorization: Bearer $CASAFARI_API_KEY.
How do I discover the OAuth protected resource for Claro?
An unauthenticated call to the platform routes answers 401 with a "WWW-Authenticate" header whose "resource_metadata" names the "protected-resource" metadata. This indicates the resource is protected by the platform's OAuth flow, requiring the bearer token in your header.
How do I check the Claro service status and data vintages?
The endpoint "/v1/claro/health" is free, costs "0 tokens", and requires your platform key on the platform (never the direct host, never keyless). On 21 October 2026, GET /v1/claro/health reports 232,069 active premises across Spain, with Location Intelligence vintages: Footfall estimates 2024 and MB Research sociodemographics 2024.
How do I get access to the Claro API?
You create a platform API key in your account on platform.casafari.com/console or sign in with the platform's OAuth; you never hold a Claro pk_ key. The platform terms apply.
How is the Claro MCP server configured and how does it transport data?
Claro MCP uses "Streamable HTTP" for JSON responses and is "stateless", with serverInfo.name as "casafari-claro". It functions as one of the platform's MCP servers under "/mcp/claro", and "The old gateway mcp.casafari.com is the legacy gateway", still answering and moving to the platform; Claro was never on it.
How should I handle missing data in the response?
Missing data is returned as "not_stated", never "no", so your client must not turn a missing value into false. This ensures that you can distinguish between a property that lacks a feature and one that explicitly excludes it.
What is the difference between matching and all_criteria_stated counts?
Search responses provide exact counts including "matching" (premises that match the search) and "all_criteria_stated" (those for which every criterion is stated). Properties that do not meet a hard criterion are excluded, while those that do not state a non-hard criterion remain in the results.
What format are the premises IDs?
Ids are opaque "pm_" tokens that carry no readable meaning and are the same on every door; use them exactly as given in search results. Never parse these IDs, as Casafari's internal identifiers do not appear.
How does pagination work for Claro searches?
You use a "limit" up to "200" per page and the "next_cursor" returned by the API, which you send back as "cursor" to retrieve the subsequent page. Search results are stable for the search's "24 hours", ensuring pages never repeat or skip a premises.
When does the model assessment run for search results?
The read-through tool "check" runs against the brief for top results but is forced off above "50" results a page and on later pages. This optimization ensures performance for large result sets.
Can I perform a search using keywords only?
Yes, you can use "criteria.keywords" without an AI model by sending keywords and/or exclude_keywords with "check": false. This performs a literal text search across the property advertisements for the specified phrases.
What happens if I lack location data access?
If your account has no location data access, a search that asks for a location criterion refuses it and names it in "not_applied" rather than ignoring it. Figures are left out of the results.
How do I interpret location figures and sources?
Figures like footfall and demographics include "location_sources" providing the unit, source, and vintage of the data, and "explain_location" returns location and "location_sources" with the same names as search; "figures" is deprecated and will be removed in a future version. Footfall is an index for comparing places, not people a day.
How do I handle 429 rate limit responses?
A 429 response returns "rate_limited" if calls are too frequent or "quota_reached" if a daily limit like "live_location_points_daily" is used up, and the platform's "tokens" are metered before the request reaches Claro. You must wait and retry based on the limit window.
How is the API versioned?
Every response carries a "Claro-Version" header, and changes within v1 are dated additive changes; a changelog page is not on the hub yet.
What are the usage terms for premises data?
You must link only the "agency" page, show Casafari "thumbnails" only, and publish an "excerpt" of the advertisement text rather than the full description. Never name or link a property portal and never name a private seller.
What is the direct Claro host?
The direct route expansion.casafari.com remains only for Casafari's own products and for pilot customers who already hold a key. Never present it as the public route.
How do I use Claro in AI assistants?
Connectors in "claude.ai" and "ChatGPT" connect through the platform's "OAuth". The platform handles the authentication, allowing your agent to interact securely with Claro tools.
How do I use the embeddable search box?
You use "pub_" keys for the embeddable search box at "/v1/embed/*", limited to 50 results; how a platform organization gets a pub_ key and whether the box is served through the platform is "not published yet".
What is the geographic coverage of Claro?
Claro, Casafari's business expansion search agent, provides commercial premises across Spain, with 232,069 active premises reported on 21 October 2026, and a separate set of Germany, commercial plots found with search_plots.