@vepler/sdk 1.9.10 → 1.10.0

package/openapi.json

@@ -1 +1,908 @@
-{"openapi":"3.1.0","info":{"version":"0.0.1","title":"Vepler API","description":"Vepler tRPC and REST API service"},"components":{"schemas":{"ListingResponse":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"nullable":true}},"required":["success"]},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"required":["success","message"]},"ListingsResponse":{"type":"object","properties":{"success":{"type":"boolean"},"result":{"type":"array","items":{"nullable":true}},"totalSize":{"type":"number"},"size":{"type":"number"}},"required":["success","result"]},"IngestResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"listingId":{"type":"string"}},"required":["success","message"]}},"parameters":{}},"paths":{"/listings/source/{provider}/{key}":{"get":{"summary":"Get listing by source","operationId":"getListingBySource","description":"Retrieve a listing by its provider and key","tags":["Listings"],"parameters":[{"schema":{"type":"string","description":"Listing provider (e.g., rightmove, zoopla)","example":"rightmove"},"required":true,"description":"Listing provider (e.g., rightmove, zoopla)","in":"path","name":"provider"},{"schema":{"type":"string","description":"Provider-specific listing key","example":"160155512"},"required":true,"description":"Provider-specific listing key","in":"path","name":"key"},{"schema":{"type":"boolean","description":"Force aggregation of listing data","example":false},"required":false,"description":"Force aggregation of listing data","in":"query","name":"forceAggregate"}],"responses":{"200":{"description":"Listing found successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingResponse"}}}},"404":{"description":"Listing not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/listings/{id}":{"get":{"summary":"Get listing by ID","operationId":"getListingById","description":"Retrieve a listing by its internal ID","tags":["Listings"],"parameters":[{"schema":{"type":"string","description":"Internal listing ID","example":"listing_01234567890"},"required":true,"description":"Internal listing ID","in":"path","name":"id"},{"schema":{"type":"boolean","description":"Force aggregation of listing data","example":false},"required":false,"description":"Force aggregation of listing data","in":"query","name":"forceAggregate"}],"responses":{"200":{"description":"Listing found successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingResponse"}}}},"404":{"description":"Listing not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/listings/locationId/{locationId}":{"get":{"summary":"Get listings by location ID","operationId":"getListingsByLocationId","description":"Retrieve listings for one or more location IDs (comma-separated)","tags":["Listings"],"parameters":[{"schema":{"type":"string","description":"Location ID(s), comma-separated for multiple","example":"123456,789012"},"required":true,"description":"Location ID(s), comma-separated for multiple","in":"path","name":"locationId"},{"schema":{"type":"boolean","description":"Force aggregation of listing data","example":false},"required":false,"description":"Force aggregation of listing data","in":"query","name":"forceAggregate"}],"responses":{"200":{"description":"Listings retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingsResponse"}}}},"400":{"description":"Invalid location ID format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/listings/":{"post":{"summary":"Ingest a listing","operationId":"ingestListingWithSlash","description":"Ingest a new listing or update an existing one (trailing slash variant)","tags":["Listings"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"locationId":{"type":"string","nullable":true},"provider":{"type":"string"},"key":{"type":"string"},"currency":{"type":"string","default":"GBP"},"price":{"type":"number","minimum":0,"exclusiveMinimum":true},"priceHistory":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date-time"},"price":{"type":"number","minimum":0,"exclusiveMinimum":true},"oldPrice":{"type":"number","nullable":true,"minimum":0,"exclusiveMinimum":true},"amount":{"type":"number","nullable":true},"percent":{"type":"number","nullable":true},"direction":{"type":"string","enum":["up","down","initial","same"]}},"required":["date","price"]}},"propertyType":{"type":"string"},"subPropertyType":{"type":"string","nullable":true},"isRetirement":{"type":"boolean"},"isNewBuild":{"type":"boolean"},"isSharedOwnership":{"type":"boolean"},"isAuction":{"type":"boolean"},"type":{"type":"string","enum":["sale","rent"]},"status":{"type":"string","enum":["live","removed","sold","under_offer","reserved","sstc"]},"category":{"type":"string","enum":["residential","commercial"],"default":"residential"},"spatial":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["Point"]},"coordinates":{"type":"array","items":{"type":"number"}}},"required":["type","coordinates"]},"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"address":{"type":"object","properties":{"propertyNumber":{"type":"string","nullable":true},"country":{"type":"string"},"postcode":{"type":"string"},"outcode":{"type":"string"},"incode":{"type":"string"},"street":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"region":{"type":"string","nullable":true},"district":{"type":"string","nullable":true},"originalAddress":{"type":"string"}},"required":["postcode","originalAddress"]},"displayAddress":{"type":"string"},"publishedDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"}]},"removedDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"},{"nullable":true}]},"removedDateSource":{"type":"string","enum":["portal","feed","scraper","manual"]},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"caption":{"type":"string"},"order":{"type":"number"},"type":{"type":"string","enum":["photo","floorplan","epc","brochure"]}},"required":["url"]},"default":[]},"energyRatingImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"caption":{"type":"string"},"order":{"type":"number"},"type":{"type":"string","enum":["photo","floorplan","epc","brochure"]}},"required":["url"]},"default":[]},"floorPlanImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"caption":{"type":"string"},"order":{"type":"number"},"type":{"type":"string","enum":["photo","floorplan","epc","brochure"]}},"required":["url"]},"default":[]},"brochureImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"caption":{"type":"string"},"order":{"type":"number"},"type":{"type":"string","enum":["photo","floorplan","epc","brochure"]}},"required":["url"]},"default":[]},"features":{"type":"array","nullable":true,"items":{"type":"object","properties":{"featureId":{"type":"string"},"value":{"type":"string"}},"required":["featureId","value"]}},"narratives":{"type":"array","nullable":true,"items":{"type":"object","properties":{"type":{"type":"string","enum":["DESCRIPTION","BULLET","DISCLAIMER","KEYFEATURES","ROOMDESCRIPTION","MEASUREMENT_DISCLAIMER","TAG"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"nullable":true}]}},"required":["type","content"]}},"meta":{"nullable":true},"forceUpdate":{"type":"boolean"}},"required":["provider","key","price","propertyType","type","status","address","publishedDate"]}}}},"responses":{"200":{"description":"Listing ingested successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestResponse"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/listings":{"post":{"summary":"Ingest a listing","operationId":"ingestListing","description":"Ingest a new listing or update an existing one","tags":["Listings"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"locationId":{"type":"string","nullable":true},"provider":{"type":"string"},"key":{"type":"string"},"currency":{"type":"string","default":"GBP"},"price":{"type":"number","minimum":0,"exclusiveMinimum":true},"priceHistory":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date-time"},"price":{"type":"number","minimum":0,"exclusiveMinimum":true},"oldPrice":{"type":"number","nullable":true,"minimum":0,"exclusiveMinimum":true},"amount":{"type":"number","nullable":true},"percent":{"type":"number","nullable":true},"direction":{"type":"string","enum":["up","down","initial","same"]}},"required":["date","price"]}},"propertyType":{"type":"string"},"subPropertyType":{"type":"string","nullable":true},"isRetirement":{"type":"boolean"},"isNewBuild":{"type":"boolean"},"isSharedOwnership":{"type":"boolean"},"isAuction":{"type":"boolean"},"type":{"type":"string","enum":["sale","rent"]},"status":{"type":"string","enum":["live","removed","sold","under_offer","reserved","sstc"]},"category":{"type":"string","enum":["residential","commercial"],"default":"residential"},"spatial":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["Point"]},"coordinates":{"type":"array","items":{"type":"number"}}},"required":["type","coordinates"]},"lat":{"type":"number","minimum":-90,"maximum":90},"lng":{"type":"number","minimum":-180,"maximum":180},"address":{"type":"object","properties":{"propertyNumber":{"type":"string","nullable":true},"country":{"type":"string"},"postcode":{"type":"string"},"outcode":{"type":"string"},"incode":{"type":"string"},"street":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"region":{"type":"string","nullable":true},"district":{"type":"string","nullable":true},"originalAddress":{"type":"string"}},"required":["postcode","originalAddress"]},"displayAddress":{"type":"string"},"publishedDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"}]},"removedDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"},{"nullable":true}]},"removedDateSource":{"type":"string","enum":["portal","feed","scraper","manual"]},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"caption":{"type":"string"},"order":{"type":"number"},"type":{"type":"string","enum":["photo","floorplan","epc","brochure"]}},"required":["url"]},"default":[]},"energyRatingImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"caption":{"type":"string"},"order":{"type":"number"},"type":{"type":"string","enum":["photo","floorplan","epc","brochure"]}},"required":["url"]},"default":[]},"floorPlanImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"caption":{"type":"string"},"order":{"type":"number"},"type":{"type":"string","enum":["photo","floorplan","epc","brochure"]}},"required":["url"]},"default":[]},"brochureImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"caption":{"type":"string"},"order":{"type":"number"},"type":{"type":"string","enum":["photo","floorplan","epc","brochure"]}},"required":["url"]},"default":[]},"features":{"type":"array","nullable":true,"items":{"type":"object","properties":{"featureId":{"type":"string"},"value":{"type":"string"}},"required":["featureId","value"]}},"narratives":{"type":"array","nullable":true,"items":{"type":"object","properties":{"type":{"type":"string","enum":["DESCRIPTION","BULLET","DISCLAIMER","KEYFEATURES","ROOMDESCRIPTION","MEASUREMENT_DISCLAIMER","TAG"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"nullable":true}]}},"required":["type","content"]}},"meta":{"nullable":true},"forceUpdate":{"type":"boolean"}},"required":["provider","key","price","propertyType","type","status","address","publishedDate"]}}}},"responses":{"200":{"description":"Listing ingested successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestResponse"}}}},"400":{"description":"Invalid request data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/listings/query":{"post":{"summary":"Query listings","operationId":"queryListings","description":"Query listings with various filters","tags":["Listings"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"locationIds":{"type":"array","items":{"type":"string"}},"providers":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["live","archived","removed"]},"limit":{"type":"number","minimum":1,"maximum":100,"default":25},"offset":{"type":"number","minimum":0,"default":0},"orderBy":{"type":"string","enum":["publishedDate","price","updatedAt"]},"order":{"type":"string","enum":["asc","desc"],"default":"desc"}}}}}},"responses":{"200":{"description":"Query executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingsResponse"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/listings/source/query":{"post":{"summary":"Query listings by source","operationId":"queryListingsBySource","description":"Query multiple listings by provider and keys","tags":["Listings"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string"},"keys":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":500}},"required":["provider","keys"]}}}},"responses":{"200":{"description":"Query executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingsResponse"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
+{
+  "openapi": "3.1.0",
+  "info": {
+    "version": "0.0.1",
+    "title": "Vepler API",
+    "description": "Vepler tRPC and REST API service"
+  },
+  "components": {
+    "schemas": {
+      "ListingResponse": {
+        "type": "object",
+        "properties": {
+          "success": { "type": "boolean" },
+          "result": { "nullable": true }
+        },
+        "required": ["success"]
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "properties": {
+          "success": { "type": "boolean", "enum": [false] },
+          "message": { "type": "string" },
+          "errors": { "type": "array", "items": { "type": "string" } }
+        },
+        "required": ["success", "message"]
+      },
+      "ListingsResponse": {
+        "type": "object",
+        "properties": {
+          "success": { "type": "boolean" },
+          "result": { "type": "array", "items": { "nullable": true } },
+          "totalSize": { "type": "number" },
+          "size": { "type": "number" }
+        },
+        "required": ["success", "result"]
+      },
+      "IngestResponse": {
+        "type": "object",
+        "properties": {
+          "success": { "type": "boolean" },
+          "message": { "type": "string" },
+          "listingId": { "type": "string" }
+        },
+        "required": ["success", "message"]
+      }
+    },
+    "parameters": {}
+  },
+  "paths": {
+    "/listings/source/{provider}/{key}": {
+      "get": {
+        "summary": "Get listing by source",
+        "operationId": "getListingBySource",
+        "description": "Retrieve a listing by its provider and key",
+        "tags": ["Listings"],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "description": "Listing provider (e.g., rightmove, zoopla)",
+              "example": "rightmove"
+            },
+            "required": true,
+            "description": "Listing provider (e.g., rightmove, zoopla)",
+            "in": "path",
+            "name": "provider"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "description": "Provider-specific listing key",
+              "example": "160155512"
+            },
+            "required": true,
+            "description": "Provider-specific listing key",
+            "in": "path",
+            "name": "key"
+          },
+          {
+            "schema": {
+              "type": "boolean",
+              "description": "Force aggregation of listing data",
+              "example": false
+            },
+            "required": false,
+            "description": "Force aggregation of listing data",
+            "in": "query",
+            "name": "forceAggregate"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Listing found successfully",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ListingResponse" }
+              }
+            }
+          },
+          "404": {
+            "description": "Listing not found",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/listings/{id}": {
+      "get": {
+        "summary": "Get listing by ID",
+        "operationId": "getListingById",
+        "description": "Retrieve a listing by its internal ID",
+        "tags": ["Listings"],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "description": "Internal listing ID",
+              "example": "listing_01234567890"
+            },
+            "required": true,
+            "description": "Internal listing ID",
+            "in": "path",
+            "name": "id"
+          },
+          {
+            "schema": {
+              "type": "boolean",
+              "description": "Force aggregation of listing data",
+              "example": false
+            },
+            "required": false,
+            "description": "Force aggregation of listing data",
+            "in": "query",
+            "name": "forceAggregate"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Listing found successfully",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ListingResponse" }
+              }
+            }
+          },
+          "404": {
+            "description": "Listing not found",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/listings/locationId/{locationId}": {
+      "get": {
+        "summary": "Get listings by location ID",
+        "operationId": "getListingsByLocationId",
+        "description": "Retrieve listings for one or more location IDs (comma-separated)",
+        "tags": ["Listings"],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "description": "Location ID(s), comma-separated for multiple",
+              "example": "123456,789012"
+            },
+            "required": true,
+            "description": "Location ID(s), comma-separated for multiple",
+            "in": "path",
+            "name": "locationId"
+          },
+          {
+            "schema": {
+              "type": "boolean",
+              "description": "Force aggregation of listing data",
+              "example": false
+            },
+            "required": false,
+            "description": "Force aggregation of listing data",
+            "in": "query",
+            "name": "forceAggregate"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Listings retrieved successfully",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ListingsResponse" }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid location ID format",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/listings/": {
+      "post": {
+        "summary": "Ingest a listing",
+        "operationId": "ingestListingWithSlash",
+        "description": "Ingest a new listing or update an existing one (trailing slash variant)",
+        "tags": ["Listings"],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "locationId": { "type": "string", "nullable": true },
+                  "provider": { "type": "string" },
+                  "key": { "type": "string" },
+                  "currency": { "type": "string", "default": "GBP" },
+                  "price": {
+                    "type": "number",
+                    "minimum": 0,
+                    "exclusiveMinimum": true
+                  },
+                  "priceHistory": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "date": { "type": "string", "format": "date-time" },
+                        "price": {
+                          "type": "number",
+                          "minimum": 0,
+                          "exclusiveMinimum": true
+                        },
+                        "oldPrice": {
+                          "type": "number",
+                          "nullable": true,
+                          "minimum": 0,
+                          "exclusiveMinimum": true
+                        },
+                        "amount": { "type": "number", "nullable": true },
+                        "percent": { "type": "number", "nullable": true },
+                        "direction": {
+                          "type": "string",
+                          "enum": ["up", "down", "initial", "same"]
+                        }
+                      },
+                      "required": ["date", "price"]
+                    }
+                  },
+                  "propertyType": { "type": "string" },
+                  "subPropertyType": { "type": "string", "nullable": true },
+                  "isRetirement": { "type": "boolean" },
+                  "isNewBuild": { "type": "boolean" },
+                  "isSharedOwnership": { "type": "boolean" },
+                  "isAuction": { "type": "boolean" },
+                  "type": { "type": "string", "enum": ["sale", "rent"] },
+                  "status": {
+                    "type": "string",
+                    "enum": [
+                      "live",
+                      "removed",
+                      "sold",
+                      "under_offer",
+                      "reserved",
+                      "sstc"
+                    ]
+                  },
+                  "category": {
+                    "type": "string",
+                    "enum": ["residential", "commercial"],
+                    "default": "residential"
+                  },
+                  "spatial": {
+                    "type": "object",
+                    "nullable": true,
+                    "properties": {
+                      "type": { "type": "string", "enum": ["Point"] },
+                      "coordinates": {
+                        "type": "array",
+                        "items": { "type": "number" }
+                      }
+                    },
+                    "required": ["type", "coordinates"]
+                  },
+                  "lat": { "type": "number", "minimum": -90, "maximum": 90 },
+                  "lng": { "type": "number", "minimum": -180, "maximum": 180 },
+                  "address": {
+                    "type": "object",
+                    "properties": {
+                      "propertyNumber": { "type": "string", "nullable": true },
+                      "country": { "type": "string" },
+                      "postcode": { "type": "string" },
+                      "outcode": { "type": "string" },
+                      "incode": { "type": "string" },
+                      "street": { "type": "string", "nullable": true },
+                      "city": { "type": "string", "nullable": true },
+                      "region": { "type": "string", "nullable": true },
+                      "district": { "type": "string", "nullable": true },
+                      "originalAddress": { "type": "string" }
+                    },
+                    "required": ["postcode", "originalAddress"]
+                  },
+                  "displayAddress": { "type": "string" },
+                  "publishedDate": {
+                    "anyOf": [
+                      { "type": "string", "format": "date-time" },
+                      { "type": "string", "format": "date" }
+                    ]
+                  },
+                  "removedDate": {
+                    "anyOf": [
+                      { "type": "string", "format": "date-time" },
+                      { "type": "string", "format": "date" },
+                      { "nullable": true }
+                    ]
+                  },
+                  "removedDateSource": {
+                    "type": "string",
+                    "enum": ["portal", "feed", "scraper", "manual"]
+                  },
+                  "images": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "url": { "type": "string", "format": "uri" },
+                        "caption": { "type": "string" },
+                        "order": { "type": "number" },
+                        "type": {
+                          "type": "string",
+                          "enum": ["photo", "floorplan", "epc", "brochure"]
+                        }
+                      },
+                      "required": ["url"]
+                    },
+                    "default": []
+                  },
+                  "energyRatingImages": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "url": { "type": "string", "format": "uri" },
+                        "caption": { "type": "string" },
+                        "order": { "type": "number" },
+                        "type": {
+                          "type": "string",
+                          "enum": ["photo", "floorplan", "epc", "brochure"]
+                        }
+                      },
+                      "required": ["url"]
+                    },
+                    "default": []
+                  },
+                  "floorPlanImages": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "url": { "type": "string", "format": "uri" },
+                        "caption": { "type": "string" },
+                        "order": { "type": "number" },
+                        "type": {
+                          "type": "string",
+                          "enum": ["photo", "floorplan", "epc", "brochure"]
+                        }
+                      },
+                      "required": ["url"]
+                    },
+                    "default": []
+                  },
+                  "brochureImages": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "url": { "type": "string", "format": "uri" },
+                        "caption": { "type": "string" },
+                        "order": { "type": "number" },
+                        "type": {
+                          "type": "string",
+                          "enum": ["photo", "floorplan", "epc", "brochure"]
+                        }
+                      },
+                      "required": ["url"]
+                    },
+                    "default": []
+                  },
+                  "features": {
+                    "type": "array",
+                    "nullable": true,
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "featureId": { "type": "string" },
+                        "value": { "type": "string" }
+                      },
+                      "required": ["featureId", "value"]
+                    }
+                  },
+                  "narratives": {
+                    "type": "array",
+                    "nullable": true,
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "type": {
+                          "type": "string",
+                          "enum": [
+                            "DESCRIPTION",
+                            "BULLET",
+                            "DISCLAIMER",
+                            "KEYFEATURES",
+                            "ROOMDESCRIPTION",
+                            "MEASUREMENT_DISCLAIMER",
+                            "TAG"
+                          ]
+                        },
+                        "content": {
+                          "anyOf": [
+                            { "type": "string" },
+                            { "type": "array", "items": { "type": "string" } },
+                            { "nullable": true }
+                          ]
+                        }
+                      },
+                      "required": ["type", "content"]
+                    }
+                  },
+                  "meta": { "nullable": true },
+                  "forceUpdate": { "type": "boolean" }
+                },
+                "required": [
+                  "provider",
+                  "key",
+                  "price",
+                  "propertyType",
+                  "type",
+                  "status",
+                  "address",
+                  "publishedDate"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Listing ingested successfully",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/IngestResponse" }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request data",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/listings": {
+      "post": {
+        "summary": "Ingest a listing",
+        "operationId": "ingestListing",
+        "description": "Ingest a new listing or update an existing one",
+        "tags": ["Listings"],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "locationId": { "type": "string", "nullable": true },
+                  "provider": { "type": "string" },
+                  "key": { "type": "string" },
+                  "currency": { "type": "string", "default": "GBP" },
+                  "price": {
+                    "type": "number",
+                    "minimum": 0,
+                    "exclusiveMinimum": true
+                  },
+                  "priceHistory": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "date": { "type": "string", "format": "date-time" },
+                        "price": {
+                          "type": "number",
+                          "minimum": 0,
+                          "exclusiveMinimum": true
+                        },
+                        "oldPrice": {
+                          "type": "number",
+                          "nullable": true,
+                          "minimum": 0,
+                          "exclusiveMinimum": true
+                        },
+                        "amount": { "type": "number", "nullable": true },
+                        "percent": { "type": "number", "nullable": true },
+                        "direction": {
+                          "type": "string",
+                          "enum": ["up", "down", "initial", "same"]
+                        }
+                      },
+                      "required": ["date", "price"]
+                    }
+                  },
+                  "propertyType": { "type": "string" },
+                  "subPropertyType": { "type": "string", "nullable": true },
+                  "isRetirement": { "type": "boolean" },
+                  "isNewBuild": { "type": "boolean" },
+                  "isSharedOwnership": { "type": "boolean" },
+                  "isAuction": { "type": "boolean" },
+                  "type": { "type": "string", "enum": ["sale", "rent"] },
+                  "status": {
+                    "type": "string",
+                    "enum": [
+                      "live",
+                      "removed",
+                      "sold",
+                      "under_offer",
+                      "reserved",
+                      "sstc"
+                    ]
+                  },
+                  "category": {
+                    "type": "string",
+                    "enum": ["residential", "commercial"],
+                    "default": "residential"
+                  },
+                  "spatial": {
+                    "type": "object",
+                    "nullable": true,
+                    "properties": {
+                      "type": { "type": "string", "enum": ["Point"] },
+                      "coordinates": {
+                        "type": "array",
+                        "items": { "type": "number" }
+                      }
+                    },
+                    "required": ["type", "coordinates"]
+                  },
+                  "lat": { "type": "number", "minimum": -90, "maximum": 90 },
+                  "lng": { "type": "number", "minimum": -180, "maximum": 180 },
+                  "address": {
+                    "type": "object",
+                    "properties": {
+                      "propertyNumber": { "type": "string", "nullable": true },
+                      "country": { "type": "string" },
+                      "postcode": { "type": "string" },
+                      "outcode": { "type": "string" },
+                      "incode": { "type": "string" },
+                      "street": { "type": "string", "nullable": true },
+                      "city": { "type": "string", "nullable": true },
+                      "region": { "type": "string", "nullable": true },
+                      "district": { "type": "string", "nullable": true },
+                      "originalAddress": { "type": "string" }
+                    },
+                    "required": ["postcode", "originalAddress"]
+                  },
+                  "displayAddress": { "type": "string" },
+                  "publishedDate": {
+                    "anyOf": [
+                      { "type": "string", "format": "date-time" },
+                      { "type": "string", "format": "date" }
+                    ]
+                  },
+                  "removedDate": {
+                    "anyOf": [
+                      { "type": "string", "format": "date-time" },
+                      { "type": "string", "format": "date" },
+                      { "nullable": true }
+                    ]
+                  },
+                  "removedDateSource": {
+                    "type": "string",
+                    "enum": ["portal", "feed", "scraper", "manual"]
+                  },
+                  "images": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "url": { "type": "string", "format": "uri" },
+                        "caption": { "type": "string" },
+                        "order": { "type": "number" },
+                        "type": {
+                          "type": "string",
+                          "enum": ["photo", "floorplan", "epc", "brochure"]
+                        }
+                      },
+                      "required": ["url"]
+                    },
+                    "default": []
+                  },
+                  "energyRatingImages": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "url": { "type": "string", "format": "uri" },
+                        "caption": { "type": "string" },
+                        "order": { "type": "number" },
+                        "type": {
+                          "type": "string",
+                          "enum": ["photo", "floorplan", "epc", "brochure"]
+                        }
+                      },
+                      "required": ["url"]
+                    },
+                    "default": []
+                  },
+                  "floorPlanImages": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "url": { "type": "string", "format": "uri" },
+                        "caption": { "type": "string" },
+                        "order": { "type": "number" },
+                        "type": {
+                          "type": "string",
+                          "enum": ["photo", "floorplan", "epc", "brochure"]
+                        }
+                      },
+                      "required": ["url"]
+                    },
+                    "default": []
+                  },
+                  "brochureImages": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "url": { "type": "string", "format": "uri" },
+                        "caption": { "type": "string" },
+                        "order": { "type": "number" },
+                        "type": {
+                          "type": "string",
+                          "enum": ["photo", "floorplan", "epc", "brochure"]
+                        }
+                      },
+                      "required": ["url"]
+                    },
+                    "default": []
+                  },
+                  "features": {
+                    "type": "array",
+                    "nullable": true,
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "featureId": { "type": "string" },
+                        "value": { "type": "string" }
+                      },
+                      "required": ["featureId", "value"]
+                    }
+                  },
+                  "narratives": {
+                    "type": "array",
+                    "nullable": true,
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "type": {
+                          "type": "string",
+                          "enum": [
+                            "DESCRIPTION",
+                            "BULLET",
+                            "DISCLAIMER",
+                            "KEYFEATURES",
+                            "ROOMDESCRIPTION",
+                            "MEASUREMENT_DISCLAIMER",
+                            "TAG"
+                          ]
+                        },
+                        "content": {
+                          "anyOf": [
+                            { "type": "string" },
+                            { "type": "array", "items": { "type": "string" } },
+                            { "nullable": true }
+                          ]
+                        }
+                      },
+                      "required": ["type", "content"]
+                    }
+                  },
+                  "meta": { "nullable": true },
+                  "forceUpdate": { "type": "boolean" }
+                },
+                "required": [
+                  "provider",
+                  "key",
+                  "price",
+                  "propertyType",
+                  "type",
+                  "status",
+                  "address",
+                  "publishedDate"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Listing ingested successfully",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/IngestResponse" }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request data",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/listings/query": {
+      "post": {
+        "summary": "Query listings",
+        "operationId": "queryListings",
+        "description": "Query listings with various filters",
+        "tags": ["Listings"],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "locationIds": {
+                    "type": "array",
+                    "items": { "type": "string" }
+                  },
+                  "providers": {
+                    "type": "array",
+                    "items": { "type": "string" }
+                  },
+                  "status": {
+                    "type": "string",
+                    "enum": ["live", "archived", "removed"]
+                  },
+                  "limit": {
+                    "type": "number",
+                    "minimum": 1,
+                    "maximum": 100,
+                    "default": 25
+                  },
+                  "offset": { "type": "number", "minimum": 0, "default": 0 },
+                  "orderBy": {
+                    "type": "string",
+                    "enum": ["publishedDate", "price", "updatedAt"]
+                  },
+                  "order": {
+                    "type": "string",
+                    "enum": ["asc", "desc"],
+                    "default": "desc"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Query executed successfully",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ListingsResponse" }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid query parameters",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/listings/source/query": {
+      "post": {
+        "summary": "Query listings by source",
+        "operationId": "queryListingsBySource",
+        "description": "Query multiple listings by provider and keys",
+        "tags": ["Listings"],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "provider": { "type": "string" },
+                  "keys": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "minItems": 1,
+                    "maxItems": 500
+                  }
+                },
+                "required": ["provider", "keys"]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Query executed successfully",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ListingsResponse" }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid query parameters",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal server error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}