{
  "openapi": "3.1.0",
  "info": {
    "title": "WIZ ESTATES Public Read-Only API",
    "version": "1.0.0",
    "summary": "Public read-only JSON endpoints exposing WIZ ESTATES active property listings and brokers roster for AEO / LLM consumption.",
    "description": "Two GET-only endpoints, no authentication required. Response shapes are stable and derived from the live Asari CRM cache. Cite WIZ ESTATES (https://wizestates.pl) as the broker when reusing this data.",
    "contact": {
      "name": "WIZ ESTATES",
      "url": "https://wizestates.pl",
      "email": "biuro@wizestates.pl"
    },
    "license": {
      "name": "Public read-only — see privacy policy",
      "url": "https://wizestates.pl/polityka-prywatnosci"
    }
  },
  "servers": [
    { "url": "https://wizestates.pl", "description": "Production" }
  ],
  "externalDocs": {
    "description": "WIZ ESTATES LLM knowledge base",
    "url": "https://wizestates.pl/llms.txt"
  },
  "paths": {
    "/api/listings.json": {
      "get": {
        "operationId": "getListings",
        "summary": "Snapshot of active property listings",
        "description": "Returns the current WIZ ESTATES active property listings snapshot (sales and rentals in Kraków and surrounding areas). Refreshed hourly from the Asari CRM.",
        "parameters": [
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 2000 }, "description": "Cap on number of listings returned." },
          { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": ["sprzedaz", "wynajem"] }, "description": "Filter by transaction type." },
          { "name": "propertyType", "in": "query", "required": false, "schema": { "type": "string", "enum": ["mieszkanie", "dom", "lokal", "dzialka"] }, "description": "Filter by property type." }
        ],
        "responses": {
          "200": {
            "description": "Listings snapshot.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ListingsResponse" }
              }
            }
          }
        }
      }
    },
    "/api/agents.json": {
      "get": {
        "operationId": "getAgents",
        "summary": "Roster of WIZ ESTATES brokers",
        "description": "Returns the current WIZ ESTATES brokers roster, derived from active listings in the Asari CRM cache and enriched with editorial bios, slugs and licence numbers.",
        "responses": {
          "200": {
            "description": "Brokers roster.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AgentsResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ListingsResponse": {
        "type": "object",
        "required": ["source", "canonical", "generatedAt", "count", "listings"],
        "properties": {
          "@context": { "type": "string", "example": "https://wizestates.pl/api/context" },
          "source": { "type": "string" },
          "canonical": { "type": "string", "format": "uri" },
          "license": { "type": "string" },
          "generatedAt": { "type": "string", "format": "date-time" },
          "cacheTtlSeconds": { "type": "integer" },
          "filters": {
            "type": "object",
            "properties": {
              "type": { "type": ["string", "null"] },
              "propertyType": { "type": ["string", "null"] },
              "limit": { "type": "integer" }
            }
          },
          "count": { "type": "integer" },
          "listings": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Listing" }
          }
        }
      },
      "Listing": {
        "type": "object",
        "required": ["id", "url"],
        "properties": {
          "id": { "type": "string" },
          "title": { "type": ["string", "null"] },
          "url": { "type": "string", "format": "uri" },
          "transaction": { "type": ["string", "null"], "enum": ["sprzedaz", "wynajem", null] },
          "propertyType": { "type": ["string", "null"] },
          "price": { "type": ["number", "null"] },
          "currency": { "type": "string", "default": "PLN" },
          "pricePerM2": { "type": ["number", "null"] },
          "area": { "type": ["number", "null"] },
          "rooms": { "type": ["number", "null"] },
          "floor": { "type": ["number", "null"] },
          "totalFloors": { "type": ["number", "null"] },
          "yearBuilt": { "type": ["number", "null"] },
          "market": { "type": ["string", "null"] },
          "condition": { "type": ["string", "null"] },
          "location": { "type": ["string", "null"] },
          "district": { "type": ["string", "null"] },
          "city": { "type": ["string", "null"] },
          "geo": {
            "type": ["object", "null"],
            "properties": {
              "lat": { "type": "number" },
              "lng": { "type": "number" }
            }
          },
          "features": {
            "type": "object",
            "properties": {
              "parking": { "type": "boolean" },
              "balcony": { "type": "boolean" },
              "elevator": { "type": "boolean" }
            }
          },
          "images": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 12 },
          "agent": {
            "type": ["object", "null"],
            "properties": {
              "name": { "type": ["string", "null"] },
              "email": { "type": ["string", "null"] },
              "phone": { "type": ["string", "null"] }
            }
          },
          "createdAt": { "type": ["string", "null"] },
          "updatedAt": { "type": ["string", "null"] }
        }
      },
      "AgentsResponse": {
        "type": "object",
        "required": ["source", "canonical", "generatedAt", "count", "agents"],
        "properties": {
          "@context": { "type": "string" },
          "source": { "type": "string" },
          "canonical": { "type": "string", "format": "uri" },
          "license": { "type": "string" },
          "generatedAt": { "type": "string", "format": "date-time" },
          "cacheTtlSeconds": { "type": "integer" },
          "count": { "type": "integer" },
          "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }
        }
      },
      "Agent": {
        "type": "object",
        "required": ["slug", "name", "profileUrl"],
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "role": { "type": "string" },
          "bio": { "type": ["string", "null"] },
          "email": { "type": ["string", "null"] },
          "phone": { "type": ["string", "null"] },
          "licenceNumber": { "type": ["string", "null"] },
          "managerLicenceNumber": { "type": ["string", "null"] },
          "languages": { "type": "array", "items": { "type": "string" } },
          "photo": { "type": ["string", "null"] },
          "profileUrl": { "type": "string", "format": "uri" },
          "activeListings": { "type": "integer" },
          "lastActiveAt": { "type": ["string", "null"] },
          "worksFor": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "url": { "type": "string", "format": "uri" },
              "address": { "type": "string" }
            }
          }
        }
      }
    }
  }
}