{"openapi":"3.0.3","info":{"title":"Linter IoT API","version":"0.1.0"},"components":{"schemas":{}},"paths":{"/v1/auth/login":{"post":{"summary":"Email + password login, returns a JWT","tags":["auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":1}},"required":["email","password"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"token":{"type":"string"},"user":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["ROOT","SUBSIDIARY","DISTRIBUTOR","CLIENT_ADMIN","CLIENT_USER","INSTALLER"]},"scope":{"type":"object","properties":{"level":{"type":"string","enum":["ROOT","SUBSIDIARY","DISTRIBUTOR","CLIENT"]},"subsidiaryId":{"type":"string"},"distributorId":{"type":"string"},"clientId":{"type":"string"}},"required":["level"],"additionalProperties":false},"deviceAssignments":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"twoFactorEmail":{"type":"boolean"}},"required":["_id","name","email","role","scope","deviceAssignments","status","twoFactorEmail"],"additionalProperties":false}},"required":["token","user"],"additionalProperties":false},{"type":"object","properties":{"twoFactorRequired":{"type":"boolean","enum":[true]},"challengeId":{"type":"string"}},"required":["twoFactorRequired","challengeId"],"additionalProperties":false}]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/auth/login/verify":{"post":{"summary":"Second login step: verify the emailed 2FA PIN","tags":["auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"challengeId":{"type":"string"},"code":{"type":"string","pattern":"^\\d{6}$"}},"required":["challengeId","code"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"user":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["ROOT","SUBSIDIARY","DISTRIBUTOR","CLIENT_ADMIN","CLIENT_USER","INSTALLER"]},"scope":{"type":"object","properties":{"level":{"type":"string","enum":["ROOT","SUBSIDIARY","DISTRIBUTOR","CLIENT"]},"subsidiaryId":{"type":"string"},"distributorId":{"type":"string"},"clientId":{"type":"string"}},"required":["level"],"additionalProperties":false},"deviceAssignments":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"twoFactorEmail":{"type":"boolean"}},"required":["_id","name","email","role","scope","deviceAssignments","status","twoFactorEmail"],"additionalProperties":false}},"required":["token","user"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/auth/two-factor":{"post":{"summary":"Enable/disable email 2FA (requires the current password)","tags":["auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"password":{"type":"string","minLength":1}},"required":["enabled","password"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["ROOT","SUBSIDIARY","DISTRIBUTOR","CLIENT_ADMIN","CLIENT_USER","INSTALLER"]},"scope":{"type":"object","properties":{"level":{"type":"string","enum":["ROOT","SUBSIDIARY","DISTRIBUTOR","CLIENT"]},"subsidiaryId":{"type":"string"},"distributorId":{"type":"string"},"clientId":{"type":"string"}},"required":["level"],"additionalProperties":false},"deviceAssignments":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"twoFactorEmail":{"type":"boolean"}},"required":["_id","name","email","role","scope","deviceAssignments","status","twoFactorEmail"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/auth/register":{"post":{"summary":"Public self-registration (creates a pending client + admin user)","tags":["auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":120},"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8,"maxLength":200},"companyName":{"type":"string","minLength":2,"maxLength":160},"fiscalId":{"type":"string","minLength":3,"maxLength":32}},"required":["name","email","password","companyName","fiscalId"],"additionalProperties":false}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"},"user":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["ROOT","SUBSIDIARY","DISTRIBUTOR","CLIENT_ADMIN","CLIENT_USER","INSTALLER"]},"scope":{"type":"object","properties":{"level":{"type":"string","enum":["ROOT","SUBSIDIARY","DISTRIBUTOR","CLIENT"]},"subsidiaryId":{"type":"string"},"distributorId":{"type":"string"},"clientId":{"type":"string"}},"required":["level"],"additionalProperties":false},"deviceAssignments":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"twoFactorEmail":{"type":"boolean"}},"required":["_id","name","email","role","scope","deviceAssignments","status","twoFactorEmail"],"additionalProperties":false}},"required":["token","user"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/auth/profile":{"patch":{"summary":"Update the caller's own profile","tags":["auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":120}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["ROOT","SUBSIDIARY","DISTRIBUTOR","CLIENT_ADMIN","CLIENT_USER","INSTALLER"]},"scope":{"type":"object","properties":{"level":{"type":"string","enum":["ROOT","SUBSIDIARY","DISTRIBUTOR","CLIENT"]},"subsidiaryId":{"type":"string"},"distributorId":{"type":"string"},"clientId":{"type":"string"}},"required":["level"],"additionalProperties":false},"deviceAssignments":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"twoFactorEmail":{"type":"boolean"}},"required":["_id","name","email","role","scope","deviceAssignments","status","twoFactorEmail"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/auth/change-password":{"post":{"summary":"Change the caller's password (requires the current one)","tags":["auth"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"current":{"type":"string","minLength":1},"next":{"type":"string","minLength":8,"maxLength":200}},"required":["current","next"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/auth/me":{"get":{"summary":"Current authenticated user","tags":["auth"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["ROOT","SUBSIDIARY","DISTRIBUTOR","CLIENT_ADMIN","CLIENT_USER","INSTALLER"]},"scope":{"type":"object","properties":{"level":{"type":"string","enum":["ROOT","SUBSIDIARY","DISTRIBUTOR","CLIENT"]},"subsidiaryId":{"type":"string"},"distributorId":{"type":"string"},"clientId":{"type":"string"}},"required":["level"],"additionalProperties":false},"deviceAssignments":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"twoFactorEmail":{"type":"boolean"}},"required":["_id","name","email","role","scope","deviceAssignments","status","twoFactorEmail"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/scope/tree":{"get":{"summary":"Filterable hierarchy, trimmed to the user's ceiling","tags":["scope"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"subsidiaries":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"distributors":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"clients":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"sites":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"}},"required":["_id","name"],"additionalProperties":false}}},"required":["_id","name","sites"],"additionalProperties":false}}},"required":["_id","name","clients"],"additionalProperties":false}},"directClients":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"sites":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"}},"required":["_id","name"],"additionalProperties":false}}},"required":["_id","name","sites"],"additionalProperties":false}}},"required":["_id","name","distributors","directClients"],"additionalProperties":false}}},"required":["subsidiaries"],"additionalProperties":false}}}}}}},"/v1/health":{"get":{"summary":"Liveness/readiness check","tags":["system"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"mongo":{"type":"string","enum":["up","down"]},"uptime":{"type":"number"}},"required":["status","mongo","uptime"],"additionalProperties":false}}}}}}},"/v1/telemetry/count24h":{"get":{"summary":"Reading count of the caller's fleet over the last 24h (+ per-hour buckets)","tags":["telemetry"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number"},"byHour":{"type":"array","items":{"type":"number"},"minItems":24,"maxItems":24}},"required":["count","byHour"],"additionalProperties":false}}}}}}},"/v1/telemetry/devices":{"get":{"summary":"Devices seen in telemetry, grouped by MAC, with bound/unbound flag","tags":["telemetry"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"deviceId":{"type":"string"},"partNumber":{"type":"string"},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"]},"modelName":{"type":"string"},"typeLabel":{"type":"string"},"photoUrl":{"type":"string"},"media":{"type":"object","properties":{"drawer":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"detail":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"spotlight":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false}},"additionalProperties":false},"summaryConfig":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"type":"object","properties":{"label":{"type":"string"},"unit":{"type":"string"},"decimals":{"type":"integer","minimum":0,"maximum":6},"hidden":{"type":"boolean"}},"additionalProperties":false}},"drawer":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}},"detail":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}}},"required":["fields","drawer","detail"],"additionalProperties":false},"lastSeenAt":{"type":"string"},"count":{"type":"number"},"lastPayload":{"type":"object","additionalProperties":{}},"assigned":{"type":"boolean"},"deviceDbId":{"type":"string"}},"required":["deviceId","partNumber","deviceType","modelName","typeLabel","photoUrl","lastSeenAt","count","lastPayload","assigned"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/telemetry":{"get":{"summary":"List telemetry_raw docs (newest first, paginated)","tags":["telemetry"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":2000,"default":20},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"query","name":"deviceId","required":false},{"schema":{"type":"string"},"in":"query","name":"partNumber","required":false},{"schema":{"type":"string"},"in":"query","name":"from","required":false},{"schema":{"type":"string"},"in":"query","name":"to","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"partNumber":{"type":"string"},"deviceId":{"type":"string"},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"],"nullable":true},"receivedAt":{"type":"string"},"source":{"type":"string"},"payload":{"type":"object","additionalProperties":{}}},"required":["_id","partNumber","deviceId","deviceType","receivedAt","payload"],"additionalProperties":false}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["items","total","limit","offset"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/telemetry/{id}":{"get":{"summary":"Get one telemetry doc by id","tags":["telemetry"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"partNumber":{"type":"string"},"deviceId":{"type":"string"},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"],"nullable":true},"receivedAt":{"type":"string"},"source":{"type":"string"},"payload":{"type":"object","additionalProperties":{}}},"required":["_id","partNumber","deviceId","deviceType","receivedAt","payload"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/devices":{"get":{"summary":"List devices in scope (filtered, paginated)","tags":["devices"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":500,"default":20},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"query","name":"deviceType","required":false},{"schema":{"type":"string","enum":["REGISTERED","ACTIVE","INACTIVE","RETIRED"]},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false},{"schema":{"type":"string"},"in":"query","name":"subsidiaryId","required":false},{"schema":{"type":"string"},"in":"query","name":"distributorId","required":false},{"schema":{"type":"string"},"in":"query","name":"clientId","required":false},{"schema":{"type":"string"},"in":"query","name":"siteId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"deviceId":{"type":"string"},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"]},"status":{"type":"string","enum":["REGISTERED","ACTIVE","INACTIVE","RETIRED"]},"connectivity":{"type":"string","enum":["online","offline"]},"siteName":{"type":"string"},"clientName":{"type":"string"},"lastSeenAt":{"type":"string"},"friendlyName":{"type":"string"},"location":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"},"source":{"type":"string","enum":["MOCK","OPERATOR"]}},"required":["lat","lng","source"],"additionalProperties":false},"alertSeverity":{"type":"string","enum":["warning","critical"]},"model":{"type":"object","properties":{"_id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"typeLabel":{"type":"string"},"photoUrl":{"type":"string"},"summaryConfig":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"type":"object","properties":{"label":{"type":"string"},"unit":{"type":"string"},"decimals":{"type":"integer","minimum":0,"maximum":6},"hidden":{"type":"boolean"}},"additionalProperties":false}},"drawer":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}},"detail":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}}},"required":["fields","drawer","detail"],"additionalProperties":false},"media":{"type":"object","properties":{"drawer":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"detail":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"spotlight":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false}},"additionalProperties":false}},"required":["_id","code","name","typeLabel","photoUrl"],"additionalProperties":false}},"required":["_id","deviceId","deviceType","status","connectivity"],"additionalProperties":false}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["items","total","limit","offset"],"additionalProperties":false}}}}}}},"/v1/devices/{id}":{"get":{"summary":"Device detail (scoped)","tags":["devices"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"deviceId":{"type":"string"},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"]},"status":{"type":"string","enum":["REGISTERED","ACTIVE","INACTIVE","RETIRED"]},"connectivity":{"type":"string","enum":["online","offline"]},"siteName":{"type":"string"},"clientName":{"type":"string"},"lastSeenAt":{"type":"string"},"friendlyName":{"type":"string"},"location":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"},"source":{"type":"string","enum":["MOCK","OPERATOR"]}},"required":["lat","lng","source"],"additionalProperties":false},"alertSeverity":{"type":"string","enum":["warning","critical"]},"model":{"type":"object","properties":{"_id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"typeLabel":{"type":"string"},"photoUrl":{"type":"string"},"summaryConfig":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"type":"object","properties":{"label":{"type":"string"},"unit":{"type":"string"},"decimals":{"type":"integer","minimum":0,"maximum":6},"hidden":{"type":"boolean"}},"additionalProperties":false}},"drawer":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}},"detail":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}}},"required":["fields","drawer","detail"],"additionalProperties":false},"media":{"type":"object","properties":{"drawer":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"detail":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"spotlight":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false}},"additionalProperties":false}},"required":["_id","code","name","typeLabel","photoUrl"],"additionalProperties":false},"imei":{"type":"string"},"orderCode":{"type":"string"},"simStatus":{"type":"string","enum":["PENDING","ACTIVE"]},"gps":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"}},"required":["lat","lng"],"additionalProperties":false},"partNumber":{"type":"string"},"clientLabel":{"type":"string"},"icc":{"type":"string"},"subsidiaryId":{"type":"string"},"distributorId":{"type":"string"},"currentClientId":{"type":"string"},"siteId":{"type":"string"},"installerUserId":{"type":"string"}},"required":["_id","deviceId","deviceType","status","connectivity","orderCode","simStatus"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"summary":"Edit device management fields (ROOT)","tags":["devices"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"partNumber":{"type":"string"},"orderCode":{"type":"string"},"clientLabel":{"type":"string"},"icc":{"type":"string"},"subsidiaryId":{"type":"string"},"distributorId":{"type":"string"},"clientId":{"type":"string"},"siteId":{"type":"string"},"installerUserId":{"type":"string"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"deviceId":{"type":"string"}},"required":["_id","deviceId"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete a device (ROOT) — history and telemetry are preserved","tags":["devices"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/devices/{id}/friendly-name":{"patch":{"summary":"Set the device friendly name (scoped)","tags":["devices"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"friendlyName":{"type":"string","maxLength":80}},"required":["friendlyName"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"friendlyName":{"type":"string"}},"required":["_id","friendlyName"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/devices/{id}/telemetry":{"get":{"summary":"Recent telemetry for a device (scoped via the device)","tags":["devices"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"receivedAt":{"type":"string"},"payload":{"type":"object","additionalProperties":{}}},"required":["_id","receivedAt","payload"],"additionalProperties":false}}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/device-models":{"get":{"summary":"List the device-type catalog (part number → type)","tags":["device-models"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"partNumber":{"type":"string"},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"]},"name":{"type":"string"},"code":{"type":"string"},"photoUrl":{"type":"string"},"summaryConfig":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"type":"object","properties":{"label":{"type":"string"},"unit":{"type":"string"},"decimals":{"type":"integer","minimum":0,"maximum":6},"hidden":{"type":"boolean"}},"additionalProperties":false}},"drawer":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}},"detail":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}}},"required":["fields","drawer","detail"],"additionalProperties":false},"media":{"type":"object","properties":{"drawer":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"detail":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"spotlight":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false}},"additionalProperties":false},"alertRules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"field":{"type":"string","minLength":1},"op":{"type":"string","enum":["gt","gte","lt","lte"]},"threshold":{"type":"number"},"severity":{"type":"string","enum":["warning","critical"]},"label":{"type":"string","maxLength":120},"enabled":{"type":"boolean"}},"required":["id","field","op","threshold","severity","enabled"],"additionalProperties":false}}},"required":["_id","partNumber","deviceType","name","code","photoUrl"],"additionalProperties":false}}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}},"post":{"summary":"Add a part number → type mapping","tags":["device-models"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"partNumber":{"type":"string","minLength":1},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"]},"name":{"type":"string","minLength":1},"code":{"type":"string"},"typeLabel":{"type":"string"},"photoUrl":{"type":"string"}},"required":["partNumber","deviceType","name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"partNumber":{"type":"string"},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"]},"name":{"type":"string"},"code":{"type":"string"},"photoUrl":{"type":"string"},"summaryConfig":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"type":"object","properties":{"label":{"type":"string"},"unit":{"type":"string"},"decimals":{"type":"integer","minimum":0,"maximum":6},"hidden":{"type":"boolean"}},"additionalProperties":false}},"drawer":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}},"detail":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}}},"required":["fields","drawer","detail"],"additionalProperties":false},"media":{"type":"object","properties":{"drawer":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"detail":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"spotlight":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false}},"additionalProperties":false},"alertRules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"field":{"type":"string","minLength":1},"op":{"type":"string","enum":["gt","gte","lt","lte"]},"threshold":{"type":"number"},"severity":{"type":"string","enum":["warning","critical"]},"label":{"type":"string","maxLength":120},"enabled":{"type":"boolean"}},"required":["id","field","op","threshold","severity","enabled"],"additionalProperties":false}}},"required":["_id","partNumber","deviceType","name","code","photoUrl"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/device-models/{id}":{"get":{"summary":"Get one catalog entry","tags":["device-models"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"partNumber":{"type":"string"},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"]},"name":{"type":"string"},"code":{"type":"string"},"photoUrl":{"type":"string"},"summaryConfig":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"type":"object","properties":{"label":{"type":"string"},"unit":{"type":"string"},"decimals":{"type":"integer","minimum":0,"maximum":6},"hidden":{"type":"boolean"}},"additionalProperties":false}},"drawer":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}},"detail":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}}},"required":["fields","drawer","detail"],"additionalProperties":false},"media":{"type":"object","properties":{"drawer":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"detail":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"spotlight":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false}},"additionalProperties":false},"alertRules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"field":{"type":"string","minLength":1},"op":{"type":"string","enum":["gt","gte","lt","lte"]},"threshold":{"type":"number"},"severity":{"type":"string","enum":["warning","critical"]},"label":{"type":"string","maxLength":120},"enabled":{"type":"boolean"}},"required":["id","field","op","threshold","severity","enabled"],"additionalProperties":false}}},"required":["_id","partNumber","deviceType","name","code","photoUrl"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"summary":"Edit a part number → type mapping","tags":["device-models"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"partNumber":{"type":"string","minLength":1},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"]},"name":{"type":"string","minLength":1},"photoUrl":{"type":"string"},"summaryConfig":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"type":"object","properties":{"label":{"type":"string"},"unit":{"type":"string"},"decimals":{"type":"integer","minimum":0,"maximum":6},"hidden":{"type":"boolean"}},"additionalProperties":false}},"drawer":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}},"detail":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}}},"required":["fields","drawer","detail"],"additionalProperties":false}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"partNumber":{"type":"string"},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"]},"name":{"type":"string"},"code":{"type":"string"},"photoUrl":{"type":"string"},"summaryConfig":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"type":"object","properties":{"label":{"type":"string"},"unit":{"type":"string"},"decimals":{"type":"integer","minimum":0,"maximum":6},"hidden":{"type":"boolean"}},"additionalProperties":false}},"drawer":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}},"detail":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}}},"required":["fields","drawer","detail"],"additionalProperties":false},"media":{"type":"object","properties":{"drawer":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"detail":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"spotlight":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false}},"additionalProperties":false},"alertRules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"field":{"type":"string","minLength":1},"op":{"type":"string","enum":["gt","gte","lt","lte"]},"threshold":{"type":"number"},"severity":{"type":"string","enum":["warning","critical"]},"label":{"type":"string","maxLength":120},"enabled":{"type":"boolean"}},"required":["id","field","op","threshold","severity","enabled"],"additionalProperties":false}}},"required":["_id","partNumber","deviceType","name","code","photoUrl"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"summary":"Remove a part number → type mapping (soft delete)","tags":["device-models"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/device-models/{id}/alert-rules":{"put":{"summary":"Replace the type's alert threshold rules (ROOT)","tags":["device-models"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"alertRules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"field":{"type":"string","minLength":1},"op":{"type":"string","enum":["gt","gte","lt","lte"]},"threshold":{"type":"number"},"severity":{"type":"string","enum":["warning","critical"]},"label":{"type":"string","maxLength":120},"enabled":{"type":"boolean"}},"required":["id","field","op","threshold","severity","enabled"],"additionalProperties":false},"maxItems":50}},"required":["alertRules"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"partNumber":{"type":"string"},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"]},"name":{"type":"string"},"code":{"type":"string"},"photoUrl":{"type":"string"},"summaryConfig":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"type":"object","properties":{"label":{"type":"string"},"unit":{"type":"string"},"decimals":{"type":"integer","minimum":0,"maximum":6},"hidden":{"type":"boolean"}},"additionalProperties":false}},"drawer":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}},"detail":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}}},"required":["fields","drawer","detail"],"additionalProperties":false},"media":{"type":"object","properties":{"drawer":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"detail":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"spotlight":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false}},"additionalProperties":false},"alertRules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"field":{"type":"string","minLength":1},"op":{"type":"string","enum":["gt","gte","lt","lte"]},"threshold":{"type":"number"},"severity":{"type":"string","enum":["warning","critical"]},"label":{"type":"string","maxLength":120},"enabled":{"type":"boolean"}},"required":["id","field","op","threshold","severity","enabled"],"additionalProperties":false}}},"required":["_id","partNumber","deviceType","name","code","photoUrl"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/device-models/{id}/telemetry-fields":{"get":{"summary":"Per-field 7-day telemetry stats for this model's partNumber (configurator palette)","tags":["device-models"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"isNumeric":{"type":"boolean"},"latest":{"anyOf":[{"type":"string"},{"type":"number"},{"enum":["null"],"nullable":true}]},"avg":{"type":"number","nullable":true},"median":{"type":"number","nullable":true},"min":{"type":"number","nullable":true},"max":{"type":"number","nullable":true},"count":{"type":"number"},"spark":{"type":"array","items":{"type":"number"}}},"required":["key","isNumeric","latest","avg","median","min","max","count","spark"],"additionalProperties":false}}},"required":["fields"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/device-models/{id}/media/{slot}":{"post":{"summary":"Upload a video for a media slot (generates a webp poster)","tags":["device-models"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string","enum":["drawer","detail","spotlight"]},"in":"path","name":"slot","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"partNumber":{"type":"string"},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"]},"name":{"type":"string"},"code":{"type":"string"},"photoUrl":{"type":"string"},"summaryConfig":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"type":"object","properties":{"label":{"type":"string"},"unit":{"type":"string"},"decimals":{"type":"integer","minimum":0,"maximum":6},"hidden":{"type":"boolean"}},"additionalProperties":false}},"drawer":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}},"detail":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}}},"required":["fields","drawer","detail"],"additionalProperties":false},"media":{"type":"object","properties":{"drawer":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"detail":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"spotlight":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false}},"additionalProperties":false},"alertRules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"field":{"type":"string","minLength":1},"op":{"type":"string","enum":["gt","gte","lt","lte"]},"threshold":{"type":"number"},"severity":{"type":"string","enum":["warning","critical"]},"label":{"type":"string","maxLength":120},"enabled":{"type":"boolean"}},"required":["id","field","op","threshold","severity","enabled"],"additionalProperties":false}}},"required":["_id","partNumber","deviceType","name","code","photoUrl"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"summary":"Remove a media slot","tags":["device-models"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string","enum":["drawer","detail","spotlight"]},"in":"path","name":"slot","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"partNumber":{"type":"string"},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"]},"name":{"type":"string"},"code":{"type":"string"},"photoUrl":{"type":"string"},"summaryConfig":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"type":"object","properties":{"label":{"type":"string"},"unit":{"type":"string"},"decimals":{"type":"integer","minimum":0,"maximum":6},"hidden":{"type":"boolean"}},"additionalProperties":false}},"drawer":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}},"detail":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"field":{"type":"string"},"type":{"type":"string","enum":["value","stat","chart","text","level","status"]},"width":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]}]},"agg":{"type":"string","enum":["avg","median","min","max"]},"max":{"type":"number"},"maxField":{"type":"string"},"okValue":{"type":"string"}},"required":["id","field","type","width"],"additionalProperties":false}}},"required":["fields","drawer","detail"],"additionalProperties":false},"media":{"type":"object","properties":{"drawer":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"detail":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"spotlight":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false}},"additionalProperties":false},"alertRules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1},"field":{"type":"string","minLength":1},"op":{"type":"string","enum":["gt","gte","lt","lte"]},"threshold":{"type":"number"},"severity":{"type":"string","enum":["warning","critical"]},"label":{"type":"string","maxLength":120},"enabled":{"type":"boolean"}},"required":["id","field","op","threshold","severity","enabled"],"additionalProperties":false}}},"required":["_id","partNumber","deviceType","name","code","photoUrl"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/bindings":{"post":{"summary":"Bind a MAC to a client/order (creates Device + Assignment)","tags":["bindings"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"deviceId":{"type":"string","minLength":1},"partNumber":{"type":"string","minLength":1},"orderCode":{"type":"string"},"clientLabel":{"type":"string"},"icc":{"type":"string"},"subsidiaryId":{"type":"string"},"distributorId":{"type":"string"},"clientId":{"type":"string"},"siteId":{"type":"string"},"installerUserId":{"type":"string"},"notes":{"type":"string"},"acknowledgeReinstall":{"type":"boolean"}},"required":["deviceId","partNumber"],"additionalProperties":false}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"deviceDbId":{"type":"string"},"deviceId":{"type":"string"},"assignmentId":{"type":"string"},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"]},"status":{"type":"string","enum":["REGISTERED","ACTIVE","INACTIVE","RETIRED"]}},"required":["deviceDbId","deviceId","assignmentId","deviceType","status"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"alreadyBound":{"type":"boolean"},"previousClientName":{"type":"string","nullable":true}},"required":["error","alreadyBound","previousClientName"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/bindings/scan":{"post":{"summary":"Request a binding from a scanned QR (creates a PENDING_REVIEW Assignment for ROOT to approve)","tags":["bindings"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"qr":{"type":"string","minLength":1},"acknowledgeReinstall":{"type":"boolean"},"client":{"type":"object","properties":{"email":{"type":"string","format":"email"},"companyName":{"type":"string","minLength":2,"maxLength":160},"fiscalId":{"type":"string","minLength":3,"maxLength":32},"description":{"type":"string","maxLength":500}},"required":["email"],"additionalProperties":false}},"required":["qr"],"additionalProperties":false}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"assignmentId":{"type":"string"},"status":{"type":"string","enum":["PENDING_REVIEW"]},"deviceId":{"type":"string"},"partNumber":{"type":"string"},"clientName":{"type":"string"},"clientExisted":{"type":"boolean"}},"required":["assignmentId","status","deviceId","partNumber"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/bindings/client-lookup":{"post":{"summary":"Check if an email belongs to a registered client (vendor wizard)","tags":["bindings"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"}},"required":["email"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"exists":{"type":"boolean"},"clientName":{"type":"string"}},"required":["exists"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/bindings/preview":{"post":{"summary":"Resolve a scanned QR to its machine identity + binding state (no bind)","tags":["bindings"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"qr":{"type":"string","minLength":1}},"required":["qr"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"known":{"type":"boolean"},"deviceId":{"type":"string"},"model":{"type":"object","properties":{"name":{"type":"string"},"typeLabel":{"type":"string"},"photoUrl":{"type":"string"},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"]},"media":{"type":"object","properties":{"drawer":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"detail":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"spotlight":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false}},"additionalProperties":false}},"required":["name","typeLabel","photoUrl","deviceType"],"additionalProperties":false},"assigned":{"type":"boolean"},"clientName":{"type":"string"}},"required":["known","deviceId","assigned"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/public/qr-preview":{"post":{"summary":"Catalog identity for a scanned QR (public, pre-auth)","tags":["bindings"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"qr":{"type":"string","minLength":1}},"required":["qr"],"additionalProperties":false}}}},"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"known":{"type":"boolean"},"deviceId":{"type":"string"},"model":{"type":"object","properties":{"name":{"type":"string"},"typeLabel":{"type":"string"},"photoUrl":{"type":"string"},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"]},"media":{"type":"object","properties":{"drawer":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"detail":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false},"spotlight":{"type":"object","properties":{"videoUrl":{"type":"string"},"posterUrl":{"type":"string"}},"required":["videoUrl","posterUrl"],"additionalProperties":false}},"additionalProperties":false}},"required":["name","typeLabel","photoUrl","deviceType"],"additionalProperties":false}},"required":["known","deviceId"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/bindings/lookup":{"get":{"summary":"Current binding state of a MAC (pre-check for the reinstall warning)","tags":["bindings"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"query","name":"deviceId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"exists":{"type":"boolean"},"assigned":{"type":"boolean"},"clientName":{"type":"string"},"clientId":{"type":"string"}},"required":["exists","assigned"],"additionalProperties":false}}}}}}},"/v1/bindings/options":{"get":{"summary":"Selector options for the admin binding form","tags":["bindings"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"subsidiaries":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"}},"required":["_id","name"],"additionalProperties":false}},"distributors":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"}},"required":["_id","name"],"additionalProperties":false}},"clients":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"}},"required":["_id","name"],"additionalProperties":false}},"sites":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"clientId":{"type":"string"}},"required":["_id","name","clientId"],"additionalProperties":false}},"installers":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"}},"required":["_id","name"],"additionalProperties":false}}},"required":["subsidiaries","distributors","clients","sites","installers"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/clients":{"get":{"summary":"List clients the caller may see (scoped via ClientLink)","tags":["clients"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"subsidiaryId","required":false},{"schema":{"type":"string"},"in":"query","name":"distributorId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"fiscalId":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"subsidiaryName":{"type":"string"},"distributorName":{"type":"string"}},"required":["_id","name","fiscalId","status"],"additionalProperties":false}},"total":{"type":"number"}},"required":["items","total"],"additionalProperties":false}}}}}},"post":{"summary":"Create a client + its first ClientLink (ROOT only)","tags":["clients"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"fiscalId":{"type":"string","minLength":1},"subsidiaryId":{"type":"string","minLength":1},"distributorId":{"type":"string"}},"required":["name","fiscalId","subsidiaryId"],"additionalProperties":false}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"fiscalId":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"subsidiaryName":{"type":"string"},"distributorName":{"type":"string"}},"required":["_id","name","fiscalId","status"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/clients/{id}":{"get":{"summary":"Get one client (404 if outside the caller's scope)","tags":["clients"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"fiscalId":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"subsidiaryName":{"type":"string"},"distributorName":{"type":"string"}},"required":["_id","name","fiscalId","status"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"summary":"Edit a client (ROOT only)","tags":["clients"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"fiscalId":{"type":"string","minLength":1},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"fiscalId":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"subsidiaryName":{"type":"string"},"distributorName":{"type":"string"}},"required":["_id","name","fiscalId","status"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/clients/{id}/sites":{"get":{"summary":"Sites of a client (scoped)","tags":["clients"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"deviceCount":{"type":"number"}},"required":["_id","name","deviceCount"],"additionalProperties":false}},"total":{"type":"number"}},"required":["items","total"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}},"post":{"summary":"Create a site for a client (ROOT)","tags":["clients"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"address":{"type":"string","maxLength":200}},"required":["name"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"address":{"type":"string"},"deviceCount":{"type":"number"}},"required":["_id","name","deviceCount"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/clients/{id}/sites/{siteId}":{"delete":{"summary":"Delete an empty site (ROOT)","tags":["clients"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true},{"schema":{"type":"string"},"in":"path","name":"siteId","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/assignments":{"get":{"summary":"List assignments the caller may see (the binding/approval queue)","tags":["assignments"],"parameters":[{"schema":{"type":"string","enum":["PENDING_REVIEW","ACTIVE","INACTIVE","REJECTED"]},"in":"query","name":"status","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"deviceId":{"type":"string"},"partNumber":{"type":"string"},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"],"nullable":true},"clientName":{"type":"string"},"siteName":{"type":"string"},"installerName":{"type":"string"},"orderCode":{"type":"string"},"icc":{"type":"string"},"status":{"type":"string","enum":["PENDING_REVIEW","ACTIVE","INACTIVE","REJECTED"]},"createdAt":{"type":"string"},"createdByEmail":{"type":"string"}},"required":["_id","deviceId","partNumber","status","createdAt"],"additionalProperties":false}},"total":{"type":"number"}},"required":["items","total"],"additionalProperties":false}}}}}}},"/v1/assignments/{id}":{"get":{"summary":"Assignment detail (scoped)","tags":["assignments"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"deviceId":{"type":"string"},"partNumber":{"type":"string"},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"],"nullable":true},"clientName":{"type":"string"},"siteName":{"type":"string"},"installerName":{"type":"string"},"orderCode":{"type":"string"},"icc":{"type":"string"},"status":{"type":"string","enum":["PENDING_REVIEW","ACTIVE","INACTIVE","REJECTED"]},"createdAt":{"type":"string"},"createdByEmail":{"type":"string"}},"required":["_id","deviceId","partNumber","status","createdAt"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/assignments/{id}/approve":{"post":{"summary":"Approve a pending binding request → creates the Device + activates the assignment (ROOT only)","tags":["assignments"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"deviceId":{"type":"string"},"partNumber":{"type":"string"},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"],"nullable":true},"clientName":{"type":"string"},"siteName":{"type":"string"},"installerName":{"type":"string"},"orderCode":{"type":"string"},"icc":{"type":"string"},"status":{"type":"string","enum":["PENDING_REVIEW","ACTIVE","INACTIVE","REJECTED"]},"createdAt":{"type":"string"},"createdByEmail":{"type":"string"}},"required":["_id","deviceId","partNumber","status","createdAt"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/assignments/{id}/reject":{"post":{"summary":"Reject a pending binding request (ROOT only)","tags":["assignments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"deviceId":{"type":"string"},"partNumber":{"type":"string"},"deviceType":{"type":"string","enum":["UDR","UNE","UDO","UTA"],"nullable":true},"clientName":{"type":"string"},"siteName":{"type":"string"},"installerName":{"type":"string"},"orderCode":{"type":"string"},"icc":{"type":"string"},"status":{"type":"string","enum":["PENDING_REVIEW","ACTIVE","INACTIVE","REJECTED"]},"createdAt":{"type":"string"},"createdByEmail":{"type":"string"}},"required":["_id","deviceId","partNumber","status","createdAt"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/assignments/{id}/friendly-name":{"patch":{"summary":"Set the display name for a pending binding request","tags":["assignments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"friendlyName":{"type":"string","maxLength":80}},"required":["friendlyName"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"friendlyName":{"type":"string"}},"required":["_id","friendlyName"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/subsidiaries":{"get":{"summary":"List subsidiaries (filiales) the caller may see","tags":["subsidiaries"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]}},"required":["_id","name","code","status"],"additionalProperties":false}},"total":{"type":"number"}},"required":["items","total"],"additionalProperties":false}}}}}},"post":{"summary":"Create a subsidiary","tags":["subsidiaries"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"code":{"type":"string","minLength":1},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]}},"required":["name","code"],"additionalProperties":false}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]}},"required":["_id","name","code","status"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/subsidiaries/{id}":{"get":{"summary":"Get one subsidiary","tags":["subsidiaries"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]}},"required":["_id","name","code","status"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"summary":"Edit a subsidiary (status=INACTIVE soft-deletes)","tags":["subsidiaries"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"code":{"type":"string","minLength":1},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]}},"required":["_id","name","code","status"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/distributors":{"get":{"summary":"List distributors the caller may see","tags":["distributors"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"subsidiaryId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"subsidiaryId":{"type":"string"},"subsidiaryName":{"type":"string"}},"required":["_id","name","code","status","subsidiaryId"],"additionalProperties":false}},"total":{"type":"number"}},"required":["items","total"],"additionalProperties":false}}}}}},"post":{"summary":"Create a distributor","tags":["distributors"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"code":{"type":"string","minLength":1},"subsidiaryId":{"type":"string","minLength":1},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]}},"required":["name","code","subsidiaryId"],"additionalProperties":false}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"subsidiaryId":{"type":"string"},"subsidiaryName":{"type":"string"}},"required":["_id","name","code","status","subsidiaryId"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/distributors/{id}":{"get":{"summary":"Get one distributor","tags":["distributors"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"subsidiaryId":{"type":"string"},"subsidiaryName":{"type":"string"}},"required":["_id","name","code","status","subsidiaryId"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"summary":"Edit a distributor (status=INACTIVE soft-deletes)","tags":["distributors"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"code":{"type":"string","minLength":1},"subsidiaryId":{"type":"string","minLength":1},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"subsidiaryId":{"type":"string"},"subsidiaryName":{"type":"string"}},"required":["_id","name","code","status","subsidiaryId"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/installers":{"get":{"summary":"List installers the caller may see","tags":["installers"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"scopeLabel":{"type":"string"}},"required":["_id","name","email","status","scopeLabel"],"additionalProperties":false}},"total":{"type":"number"}},"required":["items","total"],"additionalProperties":false}}}}}},"post":{"summary":"Create an installer (User with role INSTALLER)","tags":["installers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":1},"subsidiaryId":{"type":"string","minLength":1},"distributorId":{"type":"string"}},"required":["name","email","password","subsidiaryId"],"additionalProperties":false}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"scopeLabel":{"type":"string"}},"required":["_id","name","email","status","scopeLabel"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/installers/{id}":{"get":{"summary":"Get one installer","tags":["installers"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"scopeLabel":{"type":"string"}},"required":["_id","name","email","status","scopeLabel"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"summary":"Edit an installer (status=INACTIVE soft-deletes; password re-hashes)","tags":["installers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"password":{"type":"string","minLength":1}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"scopeLabel":{"type":"string"}},"required":["_id","name","email","status","scopeLabel"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/alerts":{"get":{"summary":"List alerts for devices in scope (filtered, paginated)","tags":["alerts"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false},{"schema":{"type":"string","enum":["ACTIVE","ACKED","RESOLVED"]},"in":"query","name":"state","required":false},{"schema":{"type":"string","enum":["warning","critical"]},"in":"query","name":"severity","required":false},{"schema":{"type":"string"},"in":"query","name":"deviceId","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"deviceId":{"type":"string"},"partNumber":{"type":"string"},"ruleId":{"type":"string"},"field":{"type":"string"},"op":{"type":"string","enum":["gt","gte","lt","lte"]},"threshold":{"type":"number"},"severity":{"type":"string","enum":["warning","critical"]},"message":{"type":"string"},"value":{"type":"number"},"state":{"type":"string","enum":["ACTIVE","ACKED","RESOLVED"]},"raisedAt":{"type":"string"},"updatedAt":{"type":"string"},"ackedAt":{"type":"string"},"resolvedAt":{"type":"string"},"friendlyName":{"type":"string"},"clientName":{"type":"string"},"siteName":{"type":"string"}},"required":["_id","deviceId","partNumber","ruleId","field","op","threshold","severity","message","value","state","raisedAt","updatedAt"],"additionalProperties":false}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["items","total","limit","offset"],"additionalProperties":false}}}}}}},"/v1/alerts/summary":{"get":{"summary":"ACTIVE alert counters in scope (badges)","tags":["alerts"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"number"},"critical":{"type":"number"},"warning":{"type":"number"}},"required":["active","critical","warning"],"additionalProperties":false}}}}}}},"/v1/alerts/{id}/ack":{"post":{"summary":"Acknowledge an ACTIVE alert (device must be in scope)","tags":["alerts"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"deviceId":{"type":"string"},"partNumber":{"type":"string"},"ruleId":{"type":"string"},"field":{"type":"string"},"op":{"type":"string","enum":["gt","gte","lt","lte"]},"threshold":{"type":"number"},"severity":{"type":"string","enum":["warning","critical"]},"message":{"type":"string"},"value":{"type":"number"},"state":{"type":"string","enum":["ACTIVE","ACKED","RESOLVED"]},"raisedAt":{"type":"string"},"updatedAt":{"type":"string"},"ackedAt":{"type":"string"},"resolvedAt":{"type":"string"},"friendlyName":{"type":"string"},"clientName":{"type":"string"},"siteName":{"type":"string"}},"required":["_id","deviceId","partNumber","ruleId","field","op","threshold","severity","message","value","state","raisedAt","updatedAt"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/audit":{"get":{"summary":"Activity log scoped to the caller's branch (newest first)","tags":["audit"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false},{"schema":{"type":"string","maxLength":60},"in":"query","name":"action","required":false},{"schema":{"type":"string","maxLength":120},"in":"query","name":"q","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"actorName":{"type":"string"},"actorEmail":{"type":"string"},"action":{"type":"string"},"targetType":{"type":"string"},"targetId":{"type":"string"},"targetLabel":{"type":"string"},"detail":{"type":"string"},"at":{"type":"string"}},"required":["_id","actorName","action","at"],"additionalProperties":false}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["items","total","limit","offset"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/users":{"get":{"summary":"List platform users in scope (never installers)","tags":["users"],"parameters":[{"schema":{"type":"string","maxLength":120},"in":"query","name":"q","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["ROOT","SUBSIDIARY","DISTRIBUTOR","INSTALLER","CLIENT_ADMIN","CLIENT_USER"]},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"scopeLabel":{"type":"string"},"deviceAssignments":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string"}},"required":["_id","name","email","role","status","scopeLabel","deviceAssignments","createdAt"],"additionalProperties":false}},"total":{"type":"number"}},"required":["items","total"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}},"post":{"summary":"Create a user (ROOT: any non-root role; CLIENT_ADMIN: users of its own client)","tags":["users"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":120},"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8,"maxLength":200},"role":{"type":"string","enum":["SUBSIDIARY","DISTRIBUTOR","INSTALLER","CLIENT_ADMIN","CLIENT_USER"]},"subsidiaryId":{"type":"string"},"distributorId":{"type":"string"},"clientId":{"type":"string"}},"required":["name","email","password","role"],"additionalProperties":false}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["ROOT","SUBSIDIARY","DISTRIBUTOR","INSTALLER","CLIENT_ADMIN","CLIENT_USER"]},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"scopeLabel":{"type":"string"},"deviceAssignments":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string"}},"required":["_id","name","email","role","status","scopeLabel","deviceAssignments","createdAt"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/users/{id}":{"get":{"summary":"User detail (scoped)","tags":["users"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["ROOT","SUBSIDIARY","DISTRIBUTOR","INSTALLER","CLIENT_ADMIN","CLIENT_USER"]},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"scopeLabel":{"type":"string"},"deviceAssignments":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string"}},"required":["_id","name","email","role","status","scopeLabel","deviceAssignments","createdAt"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}},"patch":{"summary":"Edit a user: name/status/password/deviceAssignments (scoped writes)","tags":["users"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":120},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"password":{"type":"string","minLength":8,"maxLength":200},"deviceAssignments":{"type":"array","items":{"type":"string"},"maxItems":200}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["ROOT","SUBSIDIARY","DISTRIBUTOR","INSTALLER","CLIENT_ADMIN","CLIENT_USER"]},"status":{"type":"string","enum":["PENDING","ACTIVE","INACTIVE"]},"scopeLabel":{"type":"string"},"deviceAssignments":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string"}},"required":["_id","name","email","role","status","scopeLabel","deviceAssignments","createdAt"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/notification-rules":{"get":{"summary":"List notification rules (own; ROOT sees all)","tags":["notifications"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"event":{"type":"string","enum":["alert.raised","binding.requested"]},"minSeverity":{"type":"string","enum":["warning","critical"]},"recipients":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"createdAt":{"type":"string"}},"required":["_id","event","recipients","enabled","createdAt"],"additionalProperties":false}},"total":{"type":"number"}},"required":["items","total"],"additionalProperties":false}}}}}},"post":{"summary":"Create a notification rule","tags":["notifications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","enum":["alert.raised","binding.requested"]},"minSeverity":{"type":"string","enum":["warning","critical"]},"recipients":{"type":"array","items":{"type":"string","format":"email"},"minItems":1,"maxItems":20},"enabled":{"type":"boolean","default":true}},"required":["event","recipients"],"additionalProperties":false}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"event":{"type":"string","enum":["alert.raised","binding.requested"]},"minSeverity":{"type":"string","enum":["warning","critical"]},"recipients":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"createdAt":{"type":"string"}},"required":["_id","event","recipients","enabled","createdAt"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/notification-rules/{id}":{"patch":{"summary":"Edit a notification rule (owner or ROOT)","tags":["notifications"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"minSeverity":{"type":"string","enum":["warning","critical"],"nullable":true},"recipients":{"type":"array","items":{"type":"string","format":"email"},"minItems":1,"maxItems":20},"enabled":{"type":"boolean"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"event":{"type":"string","enum":["alert.raised","binding.requested"]},"minSeverity":{"type":"string","enum":["warning","critical"]},"recipients":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"createdAt":{"type":"string"}},"required":["_id","event","recipients","enabled","createdAt"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete a notification rule (owner or ROOT)","tags":["notifications"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/notifications":{"get":{"summary":"Outbox history (ROOT: all; others: addressed to their email)","tags":["notifications"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"event":{"type":"string"},"recipient":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"status":{"type":"string","enum":["PENDING","SENT","FAILED"]},"createdAt":{"type":"string"}},"required":["_id","event","recipient","subject","body","status","createdAt"],"additionalProperties":false}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["items","total","limit","offset"],"additionalProperties":false}}}}}}},"/v1/api-tokens":{"get":{"summary":"List the caller's API tokens (values are never returned)","tags":["api-tokens"],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"},"createdAt":{"type":"string"},"lastUsedAt":{"type":"string"},"revokedAt":{"type":"string"}},"required":["_id","name","prefix","createdAt"],"additionalProperties":false}},"total":{"type":"number"}},"required":["items","total"],"additionalProperties":false}}}}}},"post":{"summary":"Create an API token — the full value is returned ONLY here","tags":["api-tokens"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":80}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"},"createdAt":{"type":"string"},"lastUsedAt":{"type":"string"},"revokedAt":{"type":"string"},"token":{"type":"string"}},"required":["_id","name","prefix","createdAt","token"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/v1/api-tokens/{id}":{"delete":{"summary":"Revoke an API token (owner only)","tags":["api-tokens"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"_id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"},"createdAt":{"type":"string"},"lastUsedAt":{"type":"string"},"revokedAt":{"type":"string"}},"required":["_id","name","prefix","createdAt"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}}}}