{"openapi":"3.0.3","info":{"title":"InvestHome Public API","version":"1.0.0","description":"Programmatic CRUD for the lots you own (sellers, agents, builders, webhooks, integrations). Authenticate every request with an API key issued from your InvestHome account: `Authorization: Bearer ifh_live_...` (or `X-API-Key` header)."},"servers":[{"url":"https://investhome.au/api/v1/public","description":"Production"},{"url":"https://dev.investorfirsthome.com.au/api/v1/public","description":"Dev"}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key"}},"schemas":{"Lot":{"type":"object","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"lotNumber":{"type":"string"},"size":{"type":"integer","description":"Lot size in m²"},"price":{"type":"number","nullable":true},"status":{"type":"string","enum":["UPCOMING","AVAILABLE","HOLD","DEPOSIT","SOLD"]},"packageType":{"type":"string","enum":["LAND_ONLY","LAND_HOUSE_PACKAGE","LAND_HOUSE_PACKAGE_ONLY","TOWNHOME","BIG_LAND","COMMERCIAL","INDUSTRIAL"]},"visibility":{"type":"string","enum":["STANDARD","PRE_RELEASE","OFF_MARKET"]},"description":{"type":"string","nullable":true},"streetAddress":{"type":"string","nullable":true},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"estateName":{"type":"string","nullable":true},"releaseName":{"type":"string","nullable":true},"stage":{"type":"string","nullable":true},"frontage":{"type":"number","nullable":true},"depth":{"type":"number","nullable":true},"aspect":{"type":"string","nullable":true},"features":{"type":"string","nullable":true},"rebate":{"type":"string","nullable":true},"estimatedTitled":{"type":"string","nullable":true},"builderName":{"type":"string","nullable":true},"houseDesign":{"type":"string","nullable":true},"housePrice":{"type":"number","nullable":true},"totalPackagePrice":{"type":"number","nullable":true},"nominationSelling":{"type":"boolean","default":false},"zoning":{"type":"string","nullable":true},"landArea":{"type":"number","nullable":true},"councilName":{"type":"string","nullable":true},"isCornerBlock":{"type":"boolean","default":false},"roadAccess":{"type":"string","nullable":true},"services":{"type":"string","nullable":true},"permittedUses":{"type":"string","nullable":true},"contactEmail":{"type":"string","nullable":true},"contactPhone":{"type":"string","nullable":true},"shareContactDetails":{"type":"boolean","default":false},"images":{"type":"string","description":"JSON-encoded array of image URLs","nullable":true,"readOnly":true},"isPublished":{"type":"boolean","default":false},"approvalStatus":{"type":"string","enum":["PENDING","APPROVED","REJECTED"],"readOnly":true},"createdAt":{"type":"string","format":"date-time","readOnly":true},"updatedAt":{"type":"string","format":"date-time","readOnly":true},"estateId":{"type":"string","format":"uuid","nullable":true,"readOnly":true,"description":"ID of the associated estate, if any"},"releaseId":{"type":"string","format":"uuid","nullable":true,"readOnly":true,"description":"ID of the associated release, if any"},"createdBy":{"type":"string","readOnly":true,"description":"User ID of the API key owner that created this lot"}},"required":["lotNumber","size"]},"Error":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}},"security":[{"BearerAuth":[]},{"ApiKeyHeader":[]}],"paths":{"/health":{"get":{"summary":"Health check (no auth required)","security":[],"responses":{"200":{"description":"OK"}}}},"/lots":{"get":{"summary":"List lots you own","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["createdAt","updatedAt","price","size","lotNumber"]}},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"packageType","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"lots":{"type":"array","items":{"$ref":"#/components/schemas/Lot"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}},"401":{"description":"Missing/invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a new lot (goes to PENDING approval)","description":"Creates a lot owned by your API key’s user. Set `isPublished: true` to publish immediately — this consumes one slot from your published-lot quota and may return `402 PUBLISH_LIMIT_EXCEEDED` if you are over your subscribed + free-lot allowance.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lot"}}}},"responses":{"201":{"description":"Created"},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Publish quota exceeded (PUBLISH_LIMIT_EXCEEDED). Upgrade your subscription or unpublish another lot before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lots/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a single lot you own","responses":{"200":{"description":"OK"},"404":{"description":"Not found"}}},"put":{"summary":"Full replace (reset + set)","description":"Replaces the entire lot. All optional fields not included in the body are reset to their defaults (`null` / `false`). Required fields (`lotNumber`, `size`) must be present. Toggling `isPublished` from `false` to `true` consumes a published-lot slot and may return `402 PUBLISH_LIMIT_EXCEEDED`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lot"}}}},"responses":{"200":{"description":"OK"},"402":{"description":"Publish quota exceeded (PUBLISH_LIMIT_EXCEEDED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Partial update (only supplied fields change)","description":"Updates only the fields you include in the body; all other fields remain unchanged. Toggling `isPublished` from `false` to `true` consumes a published-lot slot and may return `402 PUBLISH_LIMIT_EXCEEDED`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lot"}}}},"responses":{"200":{"description":"OK"},"402":{"description":"Publish quota exceeded (PUBLISH_LIMIT_EXCEEDED).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a lot you own","responses":{"200":{"description":"OK"}}}}}}