{"openapi":"3.0.3","info":{"title":"myKutir Public API","version":"1.0.0","description":"Read-only integration API for a single society, scoped by API key. Each key belongs to one society and carries one or more scopes (e.g. flats:read); a request must present a key that has every scope required by the endpoint it calls."},"servers":[{"url":"/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Full API key secret, issued from Platform Console → Society 360 → Access. Keys can optionally expire and are always scoped to one society."}},"schemas":{"Pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"message":{"type":"string"}}}},"parameters":{"limit":{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}},"offset":{"name":"offset","in":"query","schema":{"type":"integer","default":0}}},"responses":{"Unauthorized":{"description":"Missing, invalid, expired, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Key is valid but lacks a required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"Rate limit exceeded for this key. See X-RateLimit-* response headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/ping":{"get":{"summary":"Health check","description":"Verifies the API key is valid and returns the society/label it belongs to. No data access beyond confirming the key.","security":[{"ApiKeyAuth":["ping:read"]}],"responses":{"200":{"description":"Key is valid.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"societyId":{"type":"string"},"label":{"type":"string"},"message":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/flats":{"get":{"summary":"List flats","description":"Flats belonging to the API key's society, optionally filtered by a search term matching flat number or block.","security":[{"ApiKeyAuth":["flats:read"]}],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Matches flat number or block, case-insensitive."}],"responses":{"200":{"description":"Paginated list of flats.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","allOf":[{"$ref":"#/components/schemas/Pagination"}],"properties":{"rows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"block":{"type":"string"},"flatNumber":{"type":"string"},"floor":{"type":"integer"},"type":{"type":"string"},"isOccupied":{"type":"boolean"},"monthlyMaintenance":{"type":"number"},"advanceBalance":{"type":"number"},"createdAt":{"type":"string","format":"date-time"}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/residents":{"get":{"summary":"List residents","description":"Active residents of the API key's society, optionally filtered by a search term matching name, email, phone, flat number, or block.","security":[{"ApiKeyAuth":["residents:read"]}],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"name":"search","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of residents.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","allOf":[{"$ref":"#/components/schemas/Pagination"}],"properties":{"rows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"isOwner":{"type":"boolean"},"isPrimary":{"type":"boolean"},"moveInDate":{"type":"string","format":"date-time","nullable":true},"moveOutDate":{"type":"string","format":"date-time","nullable":true},"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true}}},"flat":{"type":"object","properties":{"id":{"type":"string"},"block":{"type":"string"},"flatNumber":{"type":"string"},"floor":{"type":"integer"},"type":{"type":"string"}}}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/maintenance/bills":{"get":{"summary":"List maintenance bills","description":"Maintenance bills for the API key's society, optionally filtered by month, year, status, or flat.","security":[{"ApiKeyAuth":["maintenance:read"]}],"parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"name":"month","in":"query","schema":{"type":"integer","minimum":1,"maximum":12}},{"name":"year","in":"query","schema":{"type":"integer"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"flatId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of maintenance bills.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","allOf":[{"$ref":"#/components/schemas/Pagination"}],"properties":{"rows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"flatId":{"type":"string"},"billNumber":{"type":"string"},"month":{"type":"integer"},"year":{"type":"integer"},"amount":{"type":"number"},"lateFee":{"type":"number"},"totalAmount":{"type":"number"},"dueDate":{"type":"string","format":"date-time"},"status":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"flat":{"type":"object","properties":{"block":{"type":"string"},"flatNumber":{"type":"string"}}}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}