{
  "openapi": "3.1.0",
  "info": {
    "title": "Claro free search",
    "version": "1.0.0",
    "summary": "One free commercial premises search, then request access.",
    "description": "Casafari is the AI agent-native real estate data intelligence platform. Claro is Casafari’s AI search for commercial premises. Describe the site you need in plain words, or upload your expansion brief, and Claro checks every premises on the market against each criterion: met, not met or not stated, with the evidence behind each verdict. These two public endpoints need no key: one free search per visitor (3 a day per network), then a request for access that the Casafari team answers. Full access (REST API and MCP server, every result, dossiers, compare, location figures) comes with an account.",
    "contact": {
      "name": "Casafari",
      "url": "https://www.casafari.com/"
    }
  },
  "externalDocs": {
    "description": "Instructions for AI agents",
    "url": "https://expansion.casafari.com/llms.txt"
  },
  "tags": [
    {
      "name": "free-search",
      "description": "One free search per visitor (cookie cbx_trial) and 3 a day per network"
    },
    {
      "name": "access",
      "description": "Request access for a person, with their consent"
    }
  ],
  "servers": [
    {
      "url": "https://expansion.casafari.com"
    }
  ],
  "paths": {
    "/api/try": {
      "get": {
        "operationId": "getFreeSearch",
        "tags": [
          "free-search"
        ],
        "description": "Send the cbx_trial cookie from the earlier POST to read that search back.",
        "security": [
          {},
          {
            "trialCookie": []
          }
        ],
        "summary": "Whether this visitor has used the free search, and its results if so",
        "responses": {
          "200": {
            "description": "State",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "used": {
                      "type": "boolean"
                    },
                    "registered": {
                      "type": "boolean"
                    },
                    "search": {
                      "$ref": "#/components/schemas/TrialView"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "runFreeSearch",
        "tags": [
          "free-search"
        ],
        "security": [
          {},
          {
            "trialCookie": []
          }
        ],
        "summary": "Run the one free search",
        "description": "Describe the premises in plain words in any language, or send the brief as a file. A search that matches nothing does not use the free search.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "brief"
                ],
                "properties": {
                  "brief": {
                    "type": "string",
                    "maxLength": 1500
                  },
                  "lang": {
                    "type": "string",
                    "enum": [
                      "en",
                      "es"
                    ]
                  }
                }
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "brief": {
                    "type": "string"
                  },
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "pdf, png, jpg, jpeg, webp, heic, docx, doc, xlsx, xls, pptx, ppt, txt, md, csv, rtf, odt; 10 MB"
                  },
                  "lang": {
                    "type": "string",
                    "enum": [
                      "en",
                      "es"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The search",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrialView"
                }
              }
            }
          },
          "400": {
            "description": "The brief is missing or too long",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "The free search is used (code used or network): request access",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "The brief or file could not be read",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Busy; retry in a minute",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/register": {
      "post": {
        "operationId": "requestAccess",
        "tags": [
          "access"
        ],
        "description": "Sends the person's request to the Casafari team, who reply to them. Only with the person's consent and their own answers. The free search's brief travels with it when the cbx_trial cookie is sent.",
        "summary": "Request access for a person (with their consent)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "firstname",
                  "lastname",
                  "email",
                  "phone",
                  "company",
                  "company_size",
                  "countries",
                  "sector",
                  "datasets",
                  "sources",
                  "consent"
                ],
                "properties": {
                  "firstname": {
                    "type": "string"
                  },
                  "lastname": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "Work email"
                  },
                  "phone": {
                    "type": "string",
                    "description": "With country code"
                  },
                  "company": {
                    "type": "string"
                  },
                  "company_size": {
                    "type": "string",
                    "enum": [
                      "1-5",
                      "6-10",
                      "11-50",
                      "51-200",
                      "201-500",
                      "501-1000",
                      ">1000"
                    ]
                  },
                  "countries": {
                    "type": "string",
                    "description": "Countries the company operates in"
                  },
                  "sector": {
                    "type": "string",
                    "enum": [
                      "retail",
                      "fitness",
                      "qsr",
                      "coffee",
                      "health",
                      "franchise",
                      "agent",
                      "other"
                    ],
                    "description": "What the company opens"
                  },
                  "datasets": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "string",
                      "enum": [
                        "premises",
                        "footfall",
                        "demographics",
                        "income",
                        "places"
                      ]
                    },
                    "description": "The data that matters to the project"
                  },
                  "sources": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "string",
                      "enum": [
                        "linkedin",
                        "webinar",
                        "event",
                        "facebook",
                        "instagram",
                        "press",
                        "friend",
                        "other"
                      ]
                    },
                    "description": "How the person heard about Casafari"
                  },
                  "consent": {
                    "type": "boolean",
                    "const": true,
                    "description": "The person lets Casafari store and process their personal data to reply about Casafari Business Expansion: https://www.casafari.com/privacy-policy/"
                  },
                  "lang": {
                    "type": "string",
                    "enum": [
                      "en",
                      "es"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request sent",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid fields",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "errors": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Not sent; use the form on the page",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "code",
                        "message"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "trialCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "cbx_trial",
        "description": "Set by the first successful POST /api/try. Send it back on later calls: the free search is one per visitor and 3 a day per network; a second POST answers 402 code \"used\"."
      }
    },
    "schemas": {
      "TrialView": {
        "type": "object",
        "properties": {
          "search_id": {
            "type": "string"
          },
          "brief": {
            "type": "string"
          },
          "chips": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "locked": {
                  "type": "boolean"
                }
              }
            }
          },
          "counts": {
            "type": "object",
            "properties": {
              "matching": {
                "type": "integer"
              },
              "all_criteria_stated": {
                "type": "integer"
              },
              "some_not_stated": {
                "type": "integer"
              }
            }
          },
          "results": {
            "type": "array",
            "maxItems": 6,
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Opaque premises id (pm_...)."
                },
                "title": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "type": {
                  "type": "string"
                },
                "city": {
                  "type": "string"
                },
                "district": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "area_m2": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "rent_eur_month": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "sale_eur": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "for_rent": {
                  "type": "boolean"
                },
                "for_sale": {
                  "type": "boolean"
                },
                "photo": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Casafari thumbnail."
                },
                "point": {
                  "type": [
                    "object",
                    "null"
                  ],
                  "properties": {
                    "lat": {
                      "type": "number"
                    },
                    "lon": {
                      "type": "number"
                    },
                    "precision": {
                      "type": "string",
                      "enum": [
                        "exact",
                        "approximate"
                      ]
                    }
                  }
                },
                "checks": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "label": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "met",
                          "not_met",
                          "not_stated"
                        ]
                      },
                      "evidence": {
                        "type": "string",
                        "description": "The listing's own words or the data figure behind the verdict."
                      }
                    },
                    "required": [
                      "label",
                      "status"
                    ]
                  }
                },
                "fit": {
                  "type": [
                    "object",
                    "null"
                  ],
                  "properties": {
                    "fit": {
                      "type": "string",
                      "enum": [
                        "good",
                        "partial",
                        "poor"
                      ]
                    },
                    "reason": {
                      "type": "string"
                    },
                    "quote": {
                      "type": "string"
                    }
                  }
                },
                "excerpt": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "agency": {
                  "type": [
                    "object",
                    "null"
                  ],
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "url": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The agency's own listing page."
                    }
                  }
                },
                "also_listed_by": {
                  "type": "integer"
                }
              }
            }
          },
          "more": {
            "type": "integer",
            "description": "Matches not shown; they open with access."
          },
          "location_locked": {
            "type": "boolean"
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}