{
  "openapi": "3.1.0",
  "info": {
    "title": "Zillow API",
    "version": "1.0.0",
    "description": "Real estate data API. Look up properties by URL, address, or zpid; search listings; extract multi-unit buildings; run async batches; receive results via signed webhooks.",
    "license": { "name": "Proprietary" },
    "contact": { "name": "Support", "url": "https://zillapi.com/" }
  },
  "servers": [
    { "url": "https://api.zillapi.com", "description": "Production" }
  ],
  "security": [{ "bearerAuth": [] }],
  "tags": [
    { "name": "Properties" },
    { "name": "Buildings" },
    { "name": "Listings" },
    { "name": "Search" },
    { "name": "Jobs" },
    { "name": "Webhooks" },
    { "name": "Account" }
  ],
  "paths": {
    "/v1/properties/by-url": {
      "get": {
        "tags": ["Properties"], "operationId": "getPropertyByUrl",
        "summary": "Look up a property by Zillow URL",
        "parameters": [
          { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["FOR_SALE","RECENTLY_SOLD","FOR_RENT"], "default": "FOR_SALE" } },
          { "name": "extract_units", "in": "query", "schema": { "type": "string", "enum": ["disabled","all","for_sale","recently_sold","for_rent","off_market"], "default": "disabled" } },
          { "name": "fields", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated dotted-path field projection." }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/PropertyOk" },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/Error" },
          "429": { "$ref": "#/components/responses/Error" },
          "502": { "$ref": "#/components/responses/Error" },
          "504": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/properties/by-address": {
      "get": {
        "tags": ["Properties"], "operationId": "getPropertyByAddress",
        "parameters": [
          { "name": "address", "in": "query", "required": true, "schema": { "type": "string", "minLength": 6 } },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["FOR_SALE","RECENTLY_SOLD","FOR_RENT"], "default": "FOR_SALE" } },
          { "name": "fields", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "$ref": "#/components/responses/PropertyOk" }, "default": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/properties/{zpid}": {
      "get": {
        "tags": ["Properties"], "operationId": "getPropertyByZpid",
        "parameters": [
          { "name": "zpid", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+$" } },
          { "name": "fields", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "$ref": "#/components/responses/PropertyCachedOk" }, "default": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/properties/{zpid}/photos":         { "get": { "tags":["Properties"], "operationId":"getPropertyPhotos",        "parameters":[{"name":"zpid","in":"path","required":true,"schema":{"type":"string"}}], "responses":{"200":{"$ref":"#/components/responses/SubResourceOk"}, "default": {"$ref":"#/components/responses/Error"}} } },
    "/v1/properties/{zpid}/price-history":  { "get": { "tags":["Properties"], "operationId":"getPropertyPriceHistory",  "parameters":[{"name":"zpid","in":"path","required":true,"schema":{"type":"string"}}], "responses":{"200":{"$ref":"#/components/responses/SubResourceOk"}, "default": {"$ref":"#/components/responses/Error"}} } },
    "/v1/properties/{zpid}/tax-history":    { "get": { "tags":["Properties"], "operationId":"getPropertyTaxHistory",    "parameters":[{"name":"zpid","in":"path","required":true,"schema":{"type":"string"}}], "responses":{"200":{"$ref":"#/components/responses/SubResourceOk"}, "default": {"$ref":"#/components/responses/Error"}} } },
    "/v1/properties/{zpid}/schools":        { "get": { "tags":["Properties"], "operationId":"getPropertySchools",       "parameters":[{"name":"zpid","in":"path","required":true,"schema":{"type":"string"}}], "responses":{"200":{"$ref":"#/components/responses/SubResourceOk"}, "default": {"$ref":"#/components/responses/Error"}} } },
    "/v1/properties/{zpid}/nearby":         { "get": { "tags":["Properties"], "operationId":"getPropertyNearby",        "parameters":[{"name":"zpid","in":"path","required":true,"schema":{"type":"string"}}], "responses":{"200":{"$ref":"#/components/responses/SubResourceOk"}, "default": {"$ref":"#/components/responses/Error"}} } },
    "/v1/properties/{zpid}/agent":          { "get": { "tags":["Properties"], "operationId":"getPropertyAgent",         "parameters":[{"name":"zpid","in":"path","required":true,"schema":{"type":"string"}}], "responses":{"200":{"$ref":"#/components/responses/AgentOk"},       "default": {"$ref":"#/components/responses/Error"}} } },
    "/v1/properties/{zpid}/zestimate":      { "get": { "tags":["Properties"], "operationId":"getPropertyZestimate",     "parameters":[{"name":"zpid","in":"path","required":true,"schema":{"type":"string"}}], "responses":{"200":{"$ref":"#/components/responses/ZestimateOk"},   "default": {"$ref":"#/components/responses/Error"}} } },
    "/v1/properties/{zpid}/open-houses":    { "get": { "tags":["Properties"], "operationId":"getPropertyOpenHouses",    "parameters":[{"name":"zpid","in":"path","required":true,"schema":{"type":"string"}}], "responses":{"200":{"$ref":"#/components/responses/SubResourceOk"}, "default": {"$ref":"#/components/responses/Error"}} } },
    "/v1/properties/{zpid}/facts":          { "get": { "tags":["Properties"], "operationId":"getPropertyFacts",         "parameters":[{"name":"zpid","in":"path","required":true,"schema":{"type":"string"}}], "responses":{"200":{"$ref":"#/components/responses/SubResourceOk"}, "default": {"$ref":"#/components/responses/Error"}} } },
    "/v1/properties/batch": {
      "post": {
        "tags": ["Properties"], "operationId": "createBatchPropertyJob",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchPropertyRequest" } } } },
        "responses": { "202": { "$ref": "#/components/responses/JobAccepted" }, "default": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/buildings/by-url": {
      "get": {
        "tags": ["Buildings"], "operationId": "getBuildingByUrl",
        "parameters": [
          { "name": "url", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "include_units", "in": "query", "schema": { "type": "string", "enum": ["all","for_sale","for_rent","recently_sold","off_market"], "default": "all" } },
          { "name": "sync", "in": "query", "schema": { "type": "boolean", "default": true } }
        ],
        "responses": {
          "200": { "description": "Building units returned synchronously",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "data": { "type": "object", "properties": { "units": { "type": "array", "items": { "type": "object" } } } },
                "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "include_units": { "type": "string" } } },
                "request_id": { "type": "string" }
              }
            } } }
          },
          "202": { "$ref": "#/components/responses/JobAccepted" },
          "default": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/listings/for-sale": { "post": { "tags":["Listings"], "operationId":"listingsForSale", "requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}}, "responses": { "200": {"$ref":"#/components/responses/SearchResultsOk"}, "202": {"$ref":"#/components/responses/JobAccepted"}, "default":{"$ref":"#/components/responses/Error"} } } },
    "/v1/listings/for-rent": { "post": { "tags":["Listings"], "operationId":"listingsForRent", "requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}}, "responses": { "200": {"$ref":"#/components/responses/SearchResultsOk"}, "202": {"$ref":"#/components/responses/JobAccepted"}, "default":{"$ref":"#/components/responses/Error"} } } },
    "/v1/listings/sold":     { "post": { "tags":["Listings"], "operationId":"listingsSold",    "requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}}, "responses": { "200": {"$ref":"#/components/responses/SearchResultsOk"}, "202": {"$ref":"#/components/responses/JobAccepted"}, "default":{"$ref":"#/components/responses/Error"} } } },
    "/v1/listings": {
      "get": {
        "tags": ["Listings"], "operationId": "listingsBbox",
        "parameters": [
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["for_sale","for_rent","sold"], "default": "for_sale" } },
          { "name": "bbox", "in": "query", "schema": { "type": "string" }, "description": "west,south,east,north" },
          { "name": "location", "in": "query", "schema": { "type": "string" } },
          { "name": "price_min", "in": "query", "schema": { "type": "integer" } },
          { "name": "price_max", "in": "query", "schema": { "type": "integer" } },
          { "name": "beds_min", "in": "query", "schema": { "type": "integer" } },
          { "name": "beds_max", "in": "query", "schema": { "type": "integer" } },
          { "name": "baths_min", "in": "query", "schema": { "type": "integer" } },
          { "name": "baths_max", "in": "query", "schema": { "type": "integer" } },
          { "name": "sqft_min", "in": "query", "schema": { "type": "integer" } },
          { "name": "sqft_max", "in": "query", "schema": { "type": "integer" } },
          { "name": "year_built_min", "in": "query", "schema": { "type": "integer" } },
          { "name": "year_built_max", "in": "query", "schema": { "type": "integer" } },
          { "name": "home_types", "in": "query", "schema": { "type": "string" }, "description": "comma-separated" },
          { "name": "days_on_zillow", "in": "query", "schema": { "type": "string", "enum": ["1","7","14","30","90","6m","12m","24m","36m"] } },
          { "name": "max_items", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 50 } },
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["json","csv","ndjson"], "default": "json" } }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/SearchResultsOk" },
          "default": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/search": {
      "post": {
        "tags": ["Search"], "operationId": "search",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } },
        "responses": {
          "200": { "$ref": "#/components/responses/SearchResultsOk" },
          "202": { "$ref": "#/components/responses/JobAccepted" },
          "default": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/search/with-details": {
      "post": {
        "tags": ["Search"], "operationId": "searchWithDetails",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchWithDetailsRequest" } } } },
        "responses": { "202": { "$ref": "#/components/responses/JobAccepted" }, "default": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/jobs": {
      "get": {
        "tags": ["Jobs"], "operationId": "listJobs",
        "parameters": [
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["queued","running","succeeded","failed","timed_out","aborted"] } },
          { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["search","batch_detail","chained_search_detail","building_units"] } },
          { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 500 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }
        ],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {
          "type": "object", "properties": {
            "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } },
            "meta": { "type": "object" }, "request_id": { "type": "string" }
          }
        } } } }, "default": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/jobs/{id}": {
      "get": {
        "tags": ["Jobs"], "operationId": "getJob",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {
          "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Job" }, "request_id": { "type": "string" } }
        } } } }, "default": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/jobs/{id}/results": {
      "get": {
        "tags": ["Jobs"], "operationId": "getJobResults",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 1000 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } },
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["json","csv","ndjson"], "default": "json" } }
        ],
        "responses": {
          "200": { "description": "Job results", "content": {
            "application/json": { "schema": {
              "type": "object", "properties": {
                "data": { "type": "array", "items": { "type": "object" } },
                "meta": { "type": "object", "properties": { "count": { "type": "integer" }, "total": { "type": "integer", "nullable": true }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } } },
                "request_id": { "type": "string" }
              }
            } },
            "application/x-ndjson": { "schema": { "type": "string" } },
            "text/csv": { "schema": { "type": "string" } }
          } },
          "409": { "$ref": "#/components/responses/Error" },
          "default": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/v1/webhooks": {
      "get": {
        "tags": ["Webhooks"], "operationId": "listWebhooks",
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {
          "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "request_id": { "type": "string" } }
        } } } } }
      },
      "post": {
        "tags": ["Webhooks"], "operationId": "createWebhook",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" } } } },
        "responses": { "201": { "description": "Created (secret returned once)", "content": { "application/json": { "schema": {
          "type": "object", "properties": {
            "data": { "$ref": "#/components/schemas/WebhookCreated" },
            "request_id": { "type": "string" }
          }
        } } } }, "default": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/webhooks/{id}": {
      "delete": {
        "tags": ["Webhooks"], "operationId": "revokeWebhook",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "204": { "description": "Revoked" }, "default": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/v1/webhooks/{id}/deliveries": {
      "get": {
        "tags": ["Webhooks"], "operationId": "listWebhookDeliveries",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }
        ],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {
          "type": "object", "properties": {
            "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } },
            "request_id": { "type": "string" }
          }
        } } } } }
      }
    },
    "/v1/me": {
      "get": {
        "tags": ["Account"], "operationId": "getMe",
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {
          "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Me" }, "request_id": { "type": "string" } }
        } } } } }
      }
    },
    "/v1/usage": {
      "get": {
        "tags": ["Account"], "operationId": "getUsage",
        "parameters": [
          { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 1000 } }
        ],
        "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": {
          "type": "object", "properties": {
            "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageRow" } },
            "request_id": { "type": "string" }
          }
        } } } } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key (zk_*)" }
    },
    "responses": {
      "Unauthorized": { "description": "Auth missing/invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } },
      "Error": { "description": "Standard error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } },
      "PropertyOk": {
        "description": "Single property", "content": { "application/json": { "schema": {
          "type": "object", "properties": {
            "data": { "$ref": "#/components/schemas/Property" },
            "request_id": { "type": "string" }
          }
        } } }
      },
      "PropertyCachedOk": {
        "description": "Single property with cache info", "content": { "application/json": { "schema": {
          "type": "object", "properties": {
            "data": { "$ref": "#/components/schemas/Property" },
            "cached": { "type": "boolean" },
            "fetched_at": { "type": "string", "format": "date-time" },
            "request_id": { "type": "string" }
          }
        } } }
      },
      "SubResourceOk": {
        "description": "Sub-resource (cache-served when fresh)",
        "content": { "application/json": { "schema": {
          "type": "object", "properties": {
            "data": {}, "meta": { "type": "object", "properties": { "cached": { "type": "boolean" } } }, "request_id": { "type": "string" }
          }
        } } }
      },
      "AgentOk": {
        "description": "Listing agent + broker contact",
        "content": { "application/json": { "schema": {
          "type": "object", "properties": {
            "data": {
              "type": "object", "properties": {
                "agentName": { "type": "string", "nullable": true },
                "agentEmail": { "type": "string", "nullable": true },
                "agentPhoneNumber": { "type": "string", "nullable": true },
                "agentLicenseNumber": { "type": "string", "nullable": true },
                "brokerName": { "type": "string", "nullable": true },
                "brokerPhoneNumber": { "type": "string", "nullable": true }
              }
            },
            "request_id": { "type": "string" }
          }
        } } }
      },
      "ZestimateOk": {
        "description": "Zestimate / rent zestimate",
        "content": { "application/json": { "schema": {
          "type": "object", "properties": {
            "data": {
              "type": "object", "properties": {
                "zestimate": { "type": "number", "nullable": true },
                "rent_zestimate": { "type": "number", "nullable": true },
                "tax_assessed_value": { "type": "number", "nullable": true },
                "last_sold_price": { "type": "number", "nullable": true },
                "currency": { "type": "string" }
              }
            },
            "request_id": { "type": "string" }
          }
        } } }
      },
      "JobAccepted": {
        "description": "Async job accepted",
        "content": { "application/json": { "schema": {
          "type": "object", "properties": {
            "data": { "type": "object", "properties": {
              "job_id": { "type": "string", "format": "uuid" },
              "status": { "type": "string" },
              "stage": { "type": "string", "nullable": true }
            } },
            "request_id": { "type": "string" }
          }
        } } }
      },
      "SearchResultsOk": {
        "description": "Search rows (sync)",
        "content": {
          "application/json": { "schema": {
            "type": "object", "properties": {
              "data": { "type": "array", "items": { "type": "object" } },
              "meta": { "type": "object", "properties": { "count": { "type": "integer" } } },
              "request_id": { "type": "string" }
            }
          } },
          "application/x-ndjson": { "schema": { "type": "string" } },
          "text/csv": { "schema": { "type": "string" } }
        }
      }
    },
    "schemas": {
      "ApiError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "details": {},
              "request_id": { "type": "string" }
            },
            "required": ["code","message"]
          }
        }
      },
      "Property": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "zpid": { "type": "string" },
          "address": { "type": "object" },
          "price": { "type": "number" },
          "bedrooms": { "type": "number" }, "bathrooms": { "type": "number" },
          "livingArea": { "type": "number" }, "yearBuilt": { "type": "integer" },
          "homeType": { "type": "string" }, "homeStatus": { "type": "string" },
          "latitude": { "type": "number" }, "longitude": { "type": "number" },
          "zestimate": { "type": "number", "nullable": true },
          "rentZestimate": { "type": "number", "nullable": true },
          "priceHistory": { "type": "array", "items": { "type": "object" } },
          "taxHistory": { "type": "array", "items": { "type": "object" } },
          "schools": { "type": "array", "items": { "type": "object" } },
          "responsivePhotos": { "type": "array", "items": { "type": "object" } },
          "photoCount": { "type": "integer" },
          "openHouseSchedule": { "type": "array", "items": { "type": "object" } },
          "resoFacts": { "type": "object" }
        }
      },
      "BatchPropertyRequest": {
        "type": "object",
        "properties": {
          "urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "maxItems": 500 },
          "addresses": { "type": "array", "items": { "type": "string" }, "maxItems": 500 },
          "propertyStatus": { "type": "string", "enum": ["FOR_SALE","RECENTLY_SOLD","FOR_RENT"], "default": "FOR_SALE" },
          "extractBuildingUnits": { "type": "string", "enum": ["disabled","all","for_sale","recently_sold","for_rent","off_market"], "default": "disabled" },
          "maxItems": { "type": "integer", "minimum": 1, "maximum": 5000 }
        }
      },
      "SearchFilters": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "enum": ["for_sale","for_rent","sold"] },
          "bbox": { "type": "object", "properties": { "west": { "type":"number"}, "south": {"type":"number"}, "east": {"type":"number"}, "north": {"type":"number"} } },
          "location": { "type": "string" },
          "price": { "type": "object", "properties": { "min": {"type":"integer"}, "max": {"type":"integer"} } },
          "beds":  { "type": "object", "properties": { "min": {"type":"integer"}, "max": {"type":"integer"} } },
          "baths": { "type": "object", "properties": { "min": {"type":"number"},  "max": {"type":"number"} } },
          "sqft":  { "type": "object", "properties": { "min": {"type":"integer"}, "max": {"type":"integer"} } },
          "lotSize": { "type": "object", "properties": { "min": {"type":"integer"}, "max": {"type":"integer"} } },
          "yearBuilt": { "type": "object", "properties": { "min": {"type":"integer"}, "max": {"type":"integer"} } },
          "daysOnZillow": { "type": "string", "enum": ["1","7","14","30","90","6m","12m","24m","36m"] },
          "homeTypes": { "type": "array", "items": { "type": "string", "enum": ["house","condo","townhouse","multi_family","manufactured","lot","apartment"] } },
          "hasPool": { "type": "boolean" },
          "hasGarage": { "type": "boolean" },
          "hasAirConditioning": { "type": "boolean" },
          "hasBasement": { "type": "boolean" },
          "isWaterfront": { "type": "boolean" }
        }
      },
      "SearchRequest": {
        "type": "object",
        "properties": {
          "filters": { "$ref": "#/components/schemas/SearchFilters" },
          "searchUrls": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": ["url"] } },
          "extractionMethod": { "type": "string", "enum": ["PAGINATION_WITH_ZOOM_IN","PAGINATION","MAP_MARKERS"], "default": "PAGINATION" },
          "maxItems": { "type": "integer", "minimum": 1 },
          "async": { "type": "boolean" }
        }
      },
      "SearchWithDetailsRequest": {
        "allOf": [
          { "$ref": "#/components/schemas/SearchRequest" },
          { "type": "object", "properties": {
            "propertyStatus": { "type": "string", "enum": ["FOR_SALE","RECENTLY_SOLD","FOR_RENT"], "default": "FOR_SALE" },
            "extractBuildingUnits": { "type": "string", "enum": ["disabled","all","for_sale","recently_sold","for_rent","off_market"], "default": "disabled" }
          } }
        ]
      },
      "Job": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "type": { "type": "string", "enum": ["search","batch_detail","chained_search_detail","building_units"] },
          "status": { "type": "string", "enum": ["queued","running","succeeded","failed","timed_out","aborted"] },
          "result_count": { "type": "integer", "nullable": true },
          "error": { "type": "string", "nullable": true },
          "chain_stage": { "type": "string", "nullable": true, "enum": ["search","detail", null] },
          "created_at": { "type": "string", "format": "date-time" },
          "started_at": { "type": "string", "format": "date-time", "nullable": true },
          "completed_at": { "type": "string", "format": "date-time", "nullable": true }
        }
      },
      "WebhookCreate": {
        "type": "object",
        "required": ["url"],
        "properties": {
          "url": { "type": "string", "format": "uri" },
          "events": { "type": "array", "items": { "type": "string", "enum": ["job.succeeded","job.failed","job.timed_out","job.aborted"] } },
          "description": { "type": "string" }
        }
      },
      "Webhook": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "url": { "type": "string", "format": "uri" },
          "events": { "type": "array", "items": { "type": "string" } },
          "active": { "type": "boolean" },
          "description": { "type": "string", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" },
          "revoked_at": { "type": "string", "format": "date-time", "nullable": true }
        }
      },
      "WebhookCreated": {
        "allOf": [
          { "$ref": "#/components/schemas/Webhook" },
          { "type": "object", "properties": { "secret": { "type": "string", "description": "Plaintext signing secret. Shown only once." } } }
        ]
      },
      "WebhookDelivery": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "job_id": { "type": "string", "format": "uuid", "nullable": true },
          "event": { "type": "string" },
          "attempt": { "type": "integer" },
          "status_code": { "type": "integer", "nullable": true },
          "delivered": { "type": "boolean" },
          "attempted_at": { "type": "string", "format": "date-time" },
          "response_preview": { "type": "string", "nullable": true }
        }
      },
      "Me": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "email": { "type": "string", "format": "email" },
          "plan_id": { "type": "string", "enum": ["free","starter","pro","scale"] },
          "current_period_start": { "type": "string", "format": "date-time" },
          "status": { "type": "string", "enum": ["active","suspended","closed"] },
          "plan": { "type": "object", "properties": { "id": { "type": "string" }, "monthly_quota": { "type": "integer" }, "rate_limit_per_minute": { "type": "integer" } } },
          "usage": { "type": "object", "properties": { "this_period": { "type": "integer" }, "remaining": { "type": "integer" } } }
        }
      },
      "UsageRow": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "endpoint": { "type": "string" },
          "actor": { "type": "string", "enum": ["detail","search"] },
          "units": { "type": "integer" },
          "status_code": { "type": "integer" },
          "apify_run_id": { "type": "string", "nullable": true },
          "created_at": { "type": "string", "format": "date-time" }
        }
      }
    }
  }
}