{"openapi":"3.0.3","info":{"title":"iYugam IoT API","version":"0.1.0","description":"Generated from the server's own route definitions. Design notes: docs/spec/openapi.yaml."},"servers":[{"url":"https://iot.iyugam.com/api/v1"}],"security":[{"userToken":[]}],"paths":{"/me":{"get":{"tags":["me"],"summary":"The signed-in user and their homes / organizations (a personal home is made on the first call)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"displayName":{"nullable":true,"type":"string"},"tenants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["personal","organization"]},"name":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","guest","installer"]}},"required":["id","kind","name","role"],"additionalProperties":false}}},"required":["id","email","displayName","tenants"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants":{"post":{"tags":["tenants"],"summary":"Create an organization; the caller becomes its owner","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80}},"required":["name"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["personal","organization"]},"name":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","guest","installer"]},"telemetryRetentionDays":{"type":"number"},"eventRetentionDays":{"type":"number"},"aiEnabled":{"type":"boolean"},"requireMfaCritical":{"type":"boolean"},"createdAt":{"type":"string"}},"required":["id","kind","name","role","telemetryRetentionDays","eventRetentionDays","aiEnabled","requireMfaCritical","createdAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}":{"get":{"tags":["tenants"],"summary":"One home / organization and the caller's role in it","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["personal","organization"]},"name":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","guest","installer"]},"telemetryRetentionDays":{"type":"number"},"eventRetentionDays":{"type":"number"},"aiEnabled":{"type":"boolean"},"requireMfaCritical":{"type":"boolean"},"createdAt":{"type":"string"}},"required":["id","kind","name","role","telemetryRetentionDays","eventRetentionDays","aiEnabled","requireMfaCritical","createdAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"tags":["tenants"],"summary":"Rename, set data retention, switch the AI assistant on or off","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"telemetryRetentionDays":{"type":"integer","minimum":1,"maximum":730},"eventRetentionDays":{"type":"integer","minimum":7,"maximum":730},"aiEnabled":{"type":"boolean"},"requireMfaCritical":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["personal","organization"]},"name":{"type":"string"},"role":{"type":"string","enum":["owner","admin","member","guest","installer"]},"telemetryRetentionDays":{"type":"number"},"eventRetentionDays":{"type":"number"},"aiEnabled":{"type":"boolean"},"requireMfaCritical":{"type":"boolean"},"createdAt":{"type":"string"}},"required":["id","kind","name","role","telemetryRetentionDays","eventRetentionDays","aiEnabled","requireMfaCritical","createdAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/summary":{"get":{"tags":["tenants"],"summary":"Dashboard numbers: devices by status and category, places","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"devices":{"type":"object","properties":{"total":{"type":"number"},"online":{"type":"number"},"offline":{"type":"number"},"provisioning":{"type":"number"},"disabled":{"type":"number"},"revoked":{"type":"number"}},"required":["total","online","offline","provisioning","disabled","revoked"],"additionalProperties":false},"byCategory":{"type":"object","additionalProperties":{"type":"number"}},"locations":{"type":"number"},"rooms":{"type":"number"}},"required":["devices","byCategory","locations","rooms"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/members":{"get":{"tags":["members"],"summary":"Members and their roles","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string"},"email":{"type":"string"},"displayName":{"nullable":true,"type":"string"},"role":{"type":"string","enum":["owner","admin","member","guest","installer"]},"expiresAt":{"nullable":true,"type":"string"},"createdAt":{"type":"string"}},"required":["userId","email","displayName","role","expiresAt","createdAt"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"tags":["members"],"summary":"Add someone who has signed in to iYugam IoT before, by email","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":200,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"role":{"type":"string","enum":["owner","admin","member","guest","installer"]},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"required":["email","role"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string"},"email":{"type":"string"},"displayName":{"nullable":true,"type":"string"},"role":{"type":"string","enum":["owner","admin","member","guest","installer"]},"expiresAt":{"nullable":true,"type":"string"},"createdAt":{"type":"string"}},"required":["userId","email","displayName","role","expiresAt","createdAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/members/{userId}":{"patch":{"tags":["members"],"summary":"Change a member's role or access end date","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string","pattern":"^usr_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["owner","admin","member","guest","installer"]},"expiresAt":{"nullable":true,"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string"},"email":{"type":"string"},"displayName":{"nullable":true,"type":"string"},"role":{"type":"string","enum":["owner","admin","member","guest","installer"]},"expiresAt":{"nullable":true,"type":"string"},"createdAt":{"type":"string"}},"required":["userId","email","displayName","role","expiresAt","createdAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["members"],"summary":"Remove a member, or leave (your own id)","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string","pattern":"^usr_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/audit":{"get":{"tags":["audit"],"summary":"The audit log, newest first","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{1,19}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"actorKind":{"type":"string"},"actorId":{"type":"string"},"action":{"type":"string"},"targetKind":{"nullable":true,"type":"string"},"targetId":{"nullable":true,"type":"string"},"detail":{}},"required":["id","at","actorKind","actorId","action","targetKind","targetId","detail"],"additionalProperties":false}},"next":{"nullable":true,"type":"string"}},"required":["items","next"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/locations":{"get":{"tags":["places"],"summary":"Locations, each with its rooms","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"timezone":{"type":"string"},"lat":{"nullable":true,"type":"number"},"lon":{"nullable":true,"type":"number"},"createdAt":{"type":"string"},"rooms":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"locationId":{"type":"string"},"name":{"type":"string"},"floor":{"nullable":true,"type":"string"}},"required":["id","locationId","name","floor"],"additionalProperties":false}}},"required":["id","name","kind","timezone","lat","lon","createdAt","rooms"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"tags":["places"],"summary":"Add a location","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"kind":{"type":"string","enum":["home","office","building","industrial","outdoor","other"]},"timezone":{"type":"string","maxLength":64},"lat":{"nullable":true,"type":"number","minimum":-90,"maximum":90},"lon":{"nullable":true,"type":"number","minimum":-180,"maximum":180}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"timezone":{"type":"string"},"lat":{"nullable":true,"type":"number"},"lon":{"nullable":true,"type":"number"},"createdAt":{"type":"string"}},"required":["id","name","kind","timezone","lat","lon","createdAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/locations/{locationId}":{"patch":{"tags":["places"],"summary":"Change a location","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"locationId","in":"path","required":true,"schema":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"kind":{"type":"string","enum":["home","office","building","industrial","outdoor","other"]},"timezone":{"type":"string","maxLength":64},"lat":{"nullable":true,"type":"number","minimum":-90,"maximum":90},"lon":{"nullable":true,"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string"},"timezone":{"type":"string"},"lat":{"nullable":true,"type":"number"},"lon":{"nullable":true,"type":"number"},"createdAt":{"type":"string"}},"required":["id","name","kind","timezone","lat","lon","createdAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["places"],"summary":"Remove an empty location (its rooms go with it)","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"locationId","in":"path","required":true,"schema":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/locations/{locationId}/rooms":{"post":{"tags":["places"],"summary":"Add a room","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"locationId","in":"path","required":true,"schema":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"floor":{"type":"string","maxLength":20}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"locationId":{"type":"string"},"name":{"type":"string"},"floor":{"nullable":true,"type":"string"}},"required":["id","locationId","name","floor"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/locations/{locationId}/rooms/{roomId}":{"patch":{"tags":["places"],"summary":"Rename a room","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"locationId","in":"path","required":true,"schema":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"roomId","in":"path","required":true,"schema":{"type":"string","pattern":"^rm_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"floor":{"nullable":true,"type":"string","maxLength":20}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"locationId":{"type":"string"},"name":{"type":"string"},"floor":{"nullable":true,"type":"string"}},"required":["id","locationId","name","floor"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["places"],"summary":"Remove a room (its devices stay in the location, without a room)","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"locationId","in":"path","required":true,"schema":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"roomId","in":"path","required":true,"schema":{"type":"string","pattern":"^rm_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/devices":{"get":{"tags":["devices"],"summary":"Devices, oldest first, with filters","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-z]{2,4}_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"locationId","in":"query","required":false,"schema":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"roomId","in":"query","required":false,"schema":{"type":"string","pattern":"^rm_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["provisioning","online","offline","disabled","revoked"]}},{"name":"capability","in":"query","required":false,"schema":{"type":"string","pattern":"^iyg\\.cap\\.[a-zA-Z0-9]+@\\d+$"}},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":60}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"modelId":{"type":"string"},"manufacturer":{"type":"string"},"model":{"type":"string"},"category":{"type":"string"},"deviceType":{"type":"string"},"support":{"type":"string"},"simulated":{"type":"boolean"},"protocol":{"type":"string"},"connectionType":{"type":"string"},"gatewayId":{"nullable":true,"type":"string"},"nativeId":{"nullable":true,"type":"string"},"locationId":{"nullable":true,"type":"string"},"roomId":{"nullable":true,"type":"string"},"serialNumber":{"nullable":true,"type":"string"},"capabilities":{"type":"array","items":{"type":"object","properties":{"component":{"type":"string"},"capability":{"type":"string"}},"required":["component","capability"],"additionalProperties":false}},"status":{"type":"string"},"health":{"type":"string"},"firmwareVersion":{"nullable":true,"type":"string"},"signalDbm":{"nullable":true,"type":"number"},"batteryPercent":{"nullable":true,"type":"number"},"lastSeenAt":{"nullable":true,"type":"string"},"createdAt":{"type":"string"}},"required":["id","name","modelId","manufacturer","model","category","deviceType","support","simulated","protocol","connectionType","gatewayId","nativeId","locationId","roomId","serialNumber","capabilities","status","health","firmwareVersion","signalDbm","batteryPercent","lastSeenAt","createdAt"],"additionalProperties":false}},"next":{"nullable":true,"type":"string"}},"required":["items","next"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"tags":["devices"],"summary":"Register a device from a catalog model (it stays 'provisioning' until it enrolls, Phase 2)","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"modelId":{"type":"string","maxLength":120},"locationId":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"},"roomId":{"type":"string","pattern":"^rm_[0-9A-HJKMNP-TV-Z]{26}$"},"serialNumber":{"type":"string","minLength":1,"maxLength":80}},"required":["name","modelId"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"modelId":{"type":"string"},"manufacturer":{"type":"string"},"model":{"type":"string"},"category":{"type":"string"},"deviceType":{"type":"string"},"support":{"type":"string"},"simulated":{"type":"boolean"},"protocol":{"type":"string"},"connectionType":{"type":"string"},"gatewayId":{"nullable":true,"type":"string"},"nativeId":{"nullable":true,"type":"string"},"locationId":{"nullable":true,"type":"string"},"roomId":{"nullable":true,"type":"string"},"serialNumber":{"nullable":true,"type":"string"},"capabilities":{"type":"array","items":{"type":"object","properties":{"component":{"type":"string"},"capability":{"type":"string"}},"required":["component","capability"],"additionalProperties":false}},"status":{"type":"string"},"health":{"type":"string"},"firmwareVersion":{"nullable":true,"type":"string"},"signalDbm":{"nullable":true,"type":"number"},"batteryPercent":{"nullable":true,"type":"number"},"lastSeenAt":{"nullable":true,"type":"string"},"createdAt":{"type":"string"}},"required":["id","name","modelId","manufacturer","model","category","deviceType","support","simulated","protocol","connectionType","gatewayId","nativeId","locationId","roomId","serialNumber","capabilities","status","health","firmwareVersion","signalDbm","batteryPercent","lastSeenAt","createdAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/devices/{deviceId}":{"get":{"tags":["devices"],"summary":"One device","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"deviceId","in":"path","required":true,"schema":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"modelId":{"type":"string"},"manufacturer":{"type":"string"},"model":{"type":"string"},"category":{"type":"string"},"deviceType":{"type":"string"},"support":{"type":"string"},"simulated":{"type":"boolean"},"protocol":{"type":"string"},"connectionType":{"type":"string"},"gatewayId":{"nullable":true,"type":"string"},"nativeId":{"nullable":true,"type":"string"},"locationId":{"nullable":true,"type":"string"},"roomId":{"nullable":true,"type":"string"},"serialNumber":{"nullable":true,"type":"string"},"capabilities":{"type":"array","items":{"type":"object","properties":{"component":{"type":"string"},"capability":{"type":"string"}},"required":["component","capability"],"additionalProperties":false}},"status":{"type":"string"},"health":{"type":"string"},"firmwareVersion":{"nullable":true,"type":"string"},"signalDbm":{"nullable":true,"type":"number"},"batteryPercent":{"nullable":true,"type":"number"},"lastSeenAt":{"nullable":true,"type":"string"},"createdAt":{"type":"string"}},"required":["id","name","modelId","manufacturer","model","category","deviceType","support","simulated","protocol","connectionType","gatewayId","nativeId","locationId","roomId","serialNumber","capabilities","status","health","firmwareVersion","signalDbm","batteryPercent","lastSeenAt","createdAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"tags":["devices"],"summary":"Rename a device or move it (null takes it out of its location or room)","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"deviceId","in":"path","required":true,"schema":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"locationId":{"nullable":true,"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"},"roomId":{"nullable":true,"type":"string","pattern":"^rm_[0-9A-HJKMNP-TV-Z]{26}$"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"modelId":{"type":"string"},"manufacturer":{"type":"string"},"model":{"type":"string"},"category":{"type":"string"},"deviceType":{"type":"string"},"support":{"type":"string"},"simulated":{"type":"boolean"},"protocol":{"type":"string"},"connectionType":{"type":"string"},"gatewayId":{"nullable":true,"type":"string"},"nativeId":{"nullable":true,"type":"string"},"locationId":{"nullable":true,"type":"string"},"roomId":{"nullable":true,"type":"string"},"serialNumber":{"nullable":true,"type":"string"},"capabilities":{"type":"array","items":{"type":"object","properties":{"component":{"type":"string"},"capability":{"type":"string"}},"required":["component","capability"],"additionalProperties":false}},"status":{"type":"string"},"health":{"type":"string"},"firmwareVersion":{"nullable":true,"type":"string"},"signalDbm":{"nullable":true,"type":"number"},"batteryPercent":{"nullable":true,"type":"number"},"lastSeenAt":{"nullable":true,"type":"string"},"createdAt":{"type":"string"}},"required":["id","name","modelId","manufacturer","model","category","deviceType","support","simulated","protocol","connectionType","gatewayId","nativeId","locationId","roomId","serialNumber","capabilities","status","health","firmwareVersion","signalDbm","batteryPercent","lastSeenAt","createdAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["devices"],"summary":"Remove a device","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"deviceId","in":"path","required":true,"schema":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/devices/{deviceId}/shadow":{"get":{"tags":["devices"],"summary":"The device's shadow: desired and reported state, their difference, and the keys it can have","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"deviceId","in":"path","required":true,"schema":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"number"},"desired":{"type":"object","additionalProperties":{}},"reported":{"type":"object","additionalProperties":{}},"delta":{"type":"object","additionalProperties":{}},"meta":{"type":"object","additionalProperties":{}},"keys":{"type":"array","items":{"type":"string"}},"updatedAt":{"type":"string"}},"required":["version","desired","reported","delta","meta","keys","updatedAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/gateways":{"get":{"tags":["gateways"],"summary":"Gateways (iYugam Edge) in this home or organization","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"locationId":{"nullable":true,"type":"string"},"status":{"type":"string"},"agentVersion":{"nullable":true,"type":"string"},"lastSeenAt":{"nullable":true,"type":"string"},"adapters":{"type":"array","items":{}},"rules":{"type":"array","items":{}},"rulesVersion":{"type":"number"},"devices":{"type":"number"},"createdAt":{"type":"string"}},"required":["id","name","locationId","status","agentVersion","lastSeenAt","adapters","rules","rulesVersion","devices","createdAt"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/gateways/{gatewayId}":{"get":{"tags":["gateways"],"summary":"One gateway, with its devices and recent jobs","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"gatewayId","in":"path","required":true,"schema":{"type":"string","pattern":"^gw_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"locationId":{"nullable":true,"type":"string"},"status":{"type":"string"},"agentVersion":{"nullable":true,"type":"string"},"lastSeenAt":{"nullable":true,"type":"string"},"adapters":{"type":"array","items":{}},"rules":{"type":"array","items":{}},"rulesVersion":{"type":"number"},"devices":{"type":"number"},"createdAt":{"type":"string"},"childDevices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"modelId":{"type":"string"},"manufacturer":{"type":"string"},"model":{"type":"string"},"category":{"type":"string"},"deviceType":{"type":"string"},"support":{"type":"string"},"simulated":{"type":"boolean"},"protocol":{"type":"string"},"connectionType":{"type":"string"},"gatewayId":{"nullable":true,"type":"string"},"nativeId":{"nullable":true,"type":"string"},"locationId":{"nullable":true,"type":"string"},"roomId":{"nullable":true,"type":"string"},"serialNumber":{"nullable":true,"type":"string"},"capabilities":{"type":"array","items":{"type":"object","properties":{"component":{"type":"string"},"capability":{"type":"string"}},"required":["component","capability"],"additionalProperties":false}},"status":{"type":"string"},"health":{"type":"string"},"firmwareVersion":{"nullable":true,"type":"string"},"signalDbm":{"nullable":true,"type":"number"},"batteryPercent":{"nullable":true,"type":"number"},"lastSeenAt":{"nullable":true,"type":"string"},"createdAt":{"type":"string"}},"required":["id","name","modelId","manufacturer","model","category","deviceType","support","simulated","protocol","connectionType","gatewayId","nativeId","locationId","roomId","serialNumber","capabilities","status","health","firmwareVersion","signalDbm","batteryPercent","lastSeenAt","createdAt"],"additionalProperties":false}},"jobs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string"},"params":{},"result":{},"error":{},"createdAt":{"type":"string"},"expiresAt":{"type":"string"}},"required":["id","kind","status","params","result","error","createdAt","expiresAt"],"additionalProperties":false}}},"required":["id","name","locationId","status","agentVersion","lastSeenAt","adapters","rules","rulesVersion","devices","createdAt","childDevices","jobs"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["gateways"],"summary":"Remove a gateway (remove its devices first); its certificate stops working","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"gatewayId","in":"path","required":true,"schema":{"type":"string","pattern":"^gw_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/gateways/{gatewayId}/scan":{"post":{"tags":["gateways"],"summary":"Ask the gateway to look for devices on its local network; results arrive as candidates","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"gatewayId","in":"path","required":true,"schema":{"type":"string","pattern":"^gw_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"seconds":{"default":15,"type":"integer","minimum":5,"maximum":120}},"additionalProperties":false}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string"},"params":{},"result":{},"error":{},"createdAt":{"type":"string"},"expiresAt":{"type":"string"}},"required":["id","kind","status","params","result","error","createdAt","expiresAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/gateways/{gatewayId}/candidates":{"get":{"tags":["gateways"],"summary":"What the gateway found, with how well each is supported (devices already added are left out)","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"gatewayId","in":"path","required":true,"schema":{"type":"string","pattern":"^gw_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"candidateId":{"type":"string"},"adapter":{"type":"string"},"protocol":{"type":"string"},"identity":{},"support":{"type":"string"},"needs":{},"address":{"nullable":true,"type":"string"},"lastSeenAt":{"type":"string"},"modelId":{"nullable":true,"type":"string"}},"required":["candidateId","adapter","protocol","identity","support","needs","address","lastSeenAt","modelId"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/gateways/{gatewayId}/candidates/{candidateId}/add":{"post":{"tags":["gateways"],"summary":"Add a found device: registers it and asks the gateway to pair with it","description":"A Matter setup code (pairingCode) is passed to the gateway and never stored.","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"gatewayId","in":"path","required":true,"schema":{"type":"string","pattern":"^gw_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"candidateId","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,80}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"roomId":{"type":"string","pattern":"^rm_[0-9A-HJKMNP-TV-Z]{26}$"},"modelId":{"type":"string","maxLength":120},"pairingCode":{"type":"string","pattern":"^[0-9-]{8,40}$|^MT:[0-9A-Z.\\-]{10,60}$"}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"device":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"modelId":{"type":"string"},"manufacturer":{"type":"string"},"model":{"type":"string"},"category":{"type":"string"},"deviceType":{"type":"string"},"support":{"type":"string"},"simulated":{"type":"boolean"},"protocol":{"type":"string"},"connectionType":{"type":"string"},"gatewayId":{"nullable":true,"type":"string"},"nativeId":{"nullable":true,"type":"string"},"locationId":{"nullable":true,"type":"string"},"roomId":{"nullable":true,"type":"string"},"serialNumber":{"nullable":true,"type":"string"},"capabilities":{"type":"array","items":{"type":"object","properties":{"component":{"type":"string"},"capability":{"type":"string"}},"required":["component","capability"],"additionalProperties":false}},"status":{"type":"string"},"health":{"type":"string"},"firmwareVersion":{"nullable":true,"type":"string"},"signalDbm":{"nullable":true,"type":"number"},"batteryPercent":{"nullable":true,"type":"number"},"lastSeenAt":{"nullable":true,"type":"string"},"createdAt":{"type":"string"}},"required":["id","name","modelId","manufacturer","model","category","deviceType","support","simulated","protocol","connectionType","gatewayId","nativeId","locationId","roomId","serialNumber","capabilities","status","health","firmwareVersion","signalDbm","batteryPercent","lastSeenAt","createdAt"],"additionalProperties":false},"job":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string"},"params":{},"result":{},"error":{},"createdAt":{"type":"string"},"expiresAt":{"type":"string"}},"required":["id","kind","status","params","result","error","createdAt","expiresAt"],"additionalProperties":false}},"required":["device","job"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/gateways/{gatewayId}/rules":{"put":{"tags":["gateways"],"summary":"Replace the gateway's local safety rules (they run on the gateway, with or without the cloud)","description":"Both devices in a rule must be behind this gateway. Critical actions are refused.","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"gatewayId","in":"path","required":true,"schema":{"type":"string","pattern":"^gw_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rules":{"maxItems":100,"type":"array","items":{}}},"required":["rules"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"rules":{"type":"array","items":{}},"rulesVersion":{"type":"number"}},"required":["rules","rulesVersion"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/catalog/capabilities":{"get":{"tags":["catalog"],"summary":"The standard capability catalog","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/catalog/capabilities/{capabilityId}":{"get":{"tags":["catalog"],"summary":"One capability","security":[],"parameters":[{"name":"capabilityId","in":"path","required":true,"schema":{"type":"string","maxLength":80}}],"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/catalog/models":{"get":{"tags":["catalog"],"summary":"Device models the platform knows, with how well each is supported","security":[],"parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string","enum":["smart_home","safety","security","energy","robotics_drones","industrial","other"]}},{"name":"support","in":"query","required":false,"schema":{"type":"string","enum":["native","certified","community","experimental"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/catalog/models/{modelId}":{"get":{"tags":["catalog"],"summary":"One model, with the full definitions of its capabilities","security":[],"parameters":[{"name":"modelId","in":"path","required":true,"schema":{"type":"string","maxLength":120}}],"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/catalog/schemas/{name}":{"get":{"tags":["catalog"],"summary":"A contract as JSON Schema (capability, device-model, shadow, message-telemetry, ...)","security":[],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string","enum":["capability","device-model","shadow","command-input","cloud-event","message-telemetry","message-state","message-event","message-birth","message-command","message-ack"]}}],"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/claims":{"post":{"tags":["provisioning"],"summary":"Make a one-time claim code (15 minutes) to add a new device, or to connect one registered earlier","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"deviceId":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"}},"required":["deviceId"],"additionalProperties":false},{"type":"object","properties":{"gateway":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"locationId":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"}},"required":["name"],"additionalProperties":false}},"required":["gateway"],"additionalProperties":false},{"type":"object","properties":{"modelId":{"type":"string","maxLength":120},"name":{"type":"string","minLength":1,"maxLength":60},"locationId":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"},"roomId":{"type":"string","pattern":"^rm_[0-9A-HJKMNP-TV-Z]{26}$"}},"required":["modelId","name"],"additionalProperties":false}]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"claimId":{"type":"string"},"code":{"type":"string"},"qr":{"type":"string"},"expiresAt":{"type":"string"},"enrollUrl":{"type":"string"},"deviceId":{"nullable":true,"type":"string"}},"required":["claimId","code","qr","expiresAt","enrollUrl","deviceId"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/devices/{deviceId}/credentials":{"get":{"tags":["provisioning"],"summary":"The device's certificates (serial, validity, revocation); never any key","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"deviceId","in":"path","required":true,"schema":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"serial":{"type":"string"},"fingerprint":{"type":"string"},"notAfter":{"type":"string"},"revokedAt":{"nullable":true,"type":"string"},"revokeReason":{"nullable":true,"type":"string"},"createdAt":{"type":"string"}},"required":["serial","fingerprint","notAfter","revokedAt","revokeReason","createdAt"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/device/enroll":{"post":{"tags":["device-endpoints"],"summary":"A device or gateway enrolls with a claim code and a CSR (ECDSA P-256), and gets its id and certificate","description":"The device makes its own key and never sends it. The certificate's name is the device id; nothing else is taken from the CSR.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"claimCode":{"type":"string","minLength":10,"maxLength":40},"csr":{"type":"string","minLength":100,"maxLength":8192},"firmware":{"type":"string","maxLength":40}},"required":["claimCode","csr"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["device","gateway"]},"deviceId":{"type":"string"},"gatewayId":{"type":"string"},"certificate":{"type":"string"},"caChain":{"type":"string"},"notAfter":{"type":"string"},"mqtt":{"type":"object","properties":{"host":{"type":"string"},"port":{"type":"number"},"topicPrefix":{"type":"string"}},"required":["host","port","topicPrefix"],"additionalProperties":false},"https":{"type":"object","properties":{"base":{"type":"string"}},"required":["base"],"additionalProperties":false}},"required":["kind","certificate","caChain","notAfter","mqtt","https"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/device/certificate/renew":{"post":{"tags":["device-endpoints"],"summary":"Renew the device's certificate with a new CSR (the old one stays valid for a day)","security":[{"deviceToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"csr":{"type":"string","minLength":100,"maxLength":8192}},"required":["csr"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"certificate":{"type":"string"},"caChain":{"type":"string"},"notAfter":{"type":"string"}},"required":["certificate","caChain","notAfter"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/internal/crl":{"get":{"tags":["internal"],"summary":"The current certificate revocation list (PEM), for the broker","security":[],"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/device/telemetry":{"post":{"tags":["device-endpoints"],"summary":"Telemetry readings","security":[{"deviceToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"v":{"type":"number","enum":[1]},"msgId":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,64}$"},"ts":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"values":{"type":"object","additionalProperties":{}}},"required":["v","msgId","values"],"additionalProperties":false}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"boolean"},"duplicate":{"type":"boolean"},"rejected":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"reason":{"type":"string"}},"required":["key","reason"],"additionalProperties":false}}},"required":["accepted","duplicate","rejected"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/device/state":{"post":{"tags":["device-endpoints"],"summary":"Reported state (properties)","security":[{"deviceToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"v":{"type":"number","enum":[1]},"msgId":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,64}$"},"ts":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"seq":{"type":"integer","minimum":0,"maximum":9007199254740991},"reported":{"type":"object","additionalProperties":{}}},"required":["v","msgId","seq","reported"],"additionalProperties":false}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"boolean"},"duplicate":{"type":"boolean"},"rejected":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"reason":{"type":"string"}},"required":["key","reason"],"additionalProperties":false}}},"required":["accepted","duplicate","rejected"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/device/events":{"post":{"tags":["device-endpoints"],"summary":"A capability event (door opened, leak detected ...)","security":[{"deviceToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"v":{"type":"number","enum":[1]},"msgId":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,64}$"},"ts":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"event":{"type":"string","pattern":"^([a-z][a-zA-Z0-9]{0,39})\\.([a-z][a-zA-Z0-9]{0,39})\\.([a-z][a-zA-Z0-9]{0,39})$"},"data":{"default":{},"type":"object","additionalProperties":{}}},"required":["v","msgId","event"],"additionalProperties":false}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"boolean"},"duplicate":{"type":"boolean"},"rejected":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"reason":{"type":"string"}},"required":["key","reason"],"additionalProperties":false}}},"required":["accepted","duplicate","rejected"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/device/acks":{"post":{"tags":["device-endpoints"],"summary":"Answer a command","security":[{"deviceToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"v":{"type":"number","enum":[1]},"id":{"type":"string","pattern":"^cmd_[0-9A-HJKMNP-TV-Z]{26}$"},"status":{"type":"string","enum":["accepted","succeeded","failed","rejected"]},"error":{"default":null,"nullable":true,"type":"object","properties":{"code":{"type":"string","maxLength":40},"message":{"type":"string","maxLength":200}},"required":["code","message"]}},"required":["v","id","status"],"additionalProperties":false}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"boolean"},"duplicate":{"type":"boolean"},"rejected":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"reason":{"type":"string"}},"required":["key","reason"],"additionalProperties":false}}},"required":["accepted","duplicate","rejected"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/device/commands":{"get":{"tags":["device-endpoints"],"summary":"Waiting commands, held open up to 25 s until one arrives","security":[{"deviceToken":[]}],"parameters":[{"name":"wait","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":0,"maximum":25}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/integration/whoami":{"get":{"tags":["integration"],"summary":"What this token is: its home, scopes, and the key or app","security":[{"integrationToken":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string"},"tenantId":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"id":{"type":"string"},"userId":{"nullable":true,"type":"string"}},"required":["kind","tenantId","scopes","id","userId"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/integration/devices":{"get":{"tags":["integration"],"summary":"The home's devices (scope devices:read)","security":[{"integrationToken":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"modelId":{"type":"string"},"status":{"type":"string"},"capabilities":{},"roomId":{"nullable":true,"type":"string"},"lastSeenAt":{"nullable":true,"type":"string"}},"required":["id","name","modelId","status","capabilities","roomId","lastSeenAt"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/integration/devices/{deviceId}":{"get":{"tags":["integration"],"summary":"One device with its reported state and latest readings (scope devices:read)","security":[{"integrationToken":[]}],"parameters":[{"name":"deviceId","in":"path","required":true,"schema":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/integration/devices/{deviceId}/telemetry":{"get":{"tags":["integration"],"summary":"Hourly history of one reading (scope telemetry:read)","security":[{"integrationToken":[]}],"parameters":[{"name":"deviceId","in":"path","required":true,"schema":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"metric","in":"query","required":true,"schema":{"type":"string","maxLength":120}},{"name":"hours","in":"query","required":false,"schema":{"default":24,"type":"integer","minimum":1,"maximum":720}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"metric":{"type":"string"},"points":{"type":"array","items":{"type":"object","properties":{"hour":{"type":"string"},"avg":{"type":"number"},"min":{"type":"number"},"max":{"type":"number"}},"required":["hour","avg","min","max"],"additionalProperties":false}}},"required":["metric","points"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/integration/events":{"get":{"tags":["integration"],"summary":"The event log, oldest first after a point (scope events:read); poll with ?after=<last id>","security":[{"integrationToken":[]}],"parameters":[{"name":"after","in":"query","required":false,"schema":{"type":"string","pattern":"^evt_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"limit","in":"query","required":false,"schema":{"default":100,"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"subject":{"type":"string"},"time":{"type":"string"},"data":{}},"required":["id","type","subject","time","data"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/integration/alerts":{"get":{"tags":["integration"],"summary":"Active alerts (scope alerts:read)","security":[{"integrationToken":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"severity":{"type":"string"},"status":{"type":"string"},"deviceId":{"nullable":true,"type":"string"},"openedAt":{"type":"string"}},"required":["id","title","severity","status","deviceId","openedAt"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/integration/devices/{deviceId}/commands":{"post":{"tags":["integration"],"summary":"Send an everyday command (scope devices:control). Sensitive and critical ones are refused: they need a person in the app","security":[{"integrationToken":[]}],"parameters":[{"name":"deviceId","in":"path","required":true,"schema":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"component":{"default":"main","type":"string","pattern":"^[a-z][a-zA-Z0-9]{0,39}$"},"capability":{"type":"string","pattern":"^iyg\\.cap\\.([a-z][a-zA-Z0-9]{0,39})@([1-9][0-9]{0,3})$"},"command":{"type":"string","pattern":"^[a-z][a-zA-Z0-9]{0,39}$"},"params":{"default":{},"type":"object","additionalProperties":{}},"ttlSeconds":{"type":"integer","minimum":5,"maximum":86400}},"required":["capability","command"]}}}},"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/integration/commands/{commandId}":{"get":{"tags":["integration"],"summary":"A command's status (scope devices:control)","security":[{"integrationToken":[]}],"parameters":[{"name":"commandId","in":"path","required":true,"schema":{"type":"string","pattern":"^cmd_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/oauth/app":{"get":{"tags":["oauth"],"summary":"For the consent page: the app, and the permissions it asks for","parameters":[{"name":"client_id","in":"query","required":true,"schema":{"type":"string","pattern":"^app_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"redirect_uri","in":"query","required":true,"schema":{"type":"string","maxLength":500}},{"name":"scope","in":"query","required":true,"schema":{"type":"string","maxLength":300}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"homepageUrl":{"nullable":true,"type":"string"},"approved":{"type":"boolean"},"certified":{"type":"boolean"},"developer":{"type":"string"},"scopes":{"type":"array","items":{"type":"object","properties":{"scope":{"type":"string"},"description":{"type":"string"}},"required":["scope","description"],"additionalProperties":false}}},"required":["name","description","homepageUrl","approved","certified","developer","scopes"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/oauth/authorize":{"post":{"tags":["oauth"],"summary":"The person consents: returns where to send them back, with a one-time code (60 s)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clientId":{"type":"string","pattern":"^app_[0-9A-HJKMNP-TV-Z]{26}$"},"redirectUri":{"type":"string","maxLength":500},"scope":{"type":"string","maxLength":300},"state":{"type":"string","maxLength":500},"codeChallenge":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"codeChallengeMethod":{"type":"string","enum":["S256"]},"tenantId":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},"required":["clientId","redirectUri","scope","codeChallenge","codeChallengeMethod","tenantId"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"redirect":{"type":"string"}},"required":["redirect"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/oauth/token":{"post":{"tags":["oauth"],"summary":"Exchange a code (with its PKCE verifier) or a refresh token for tokens (JSON or form-encoded)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/oauth/revoke":{"post":{"tags":["oauth"],"summary":"Revoke an access or refresh token (RFC 7009); a refresh token ends the whole grant","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/me/oauth-grants":{"get":{"tags":["oauth"],"summary":"Apps you connected, per home","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"app":{"type":"string"},"appId":{"type":"string"},"tenantId":{"type":"string"},"tenant":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string"}},"required":["id","app","appId","tenantId","tenant","scopes","createdAt"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/me/oauth-grants/{grantId}":{"delete":{"tags":["oauth"],"summary":"Disconnect an app (its tokens stop working at once)","parameters":[{"name":"grantId","in":"path","required":true,"schema":{"type":"string","pattern":"^grt_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/devices/{deviceId}/stream-key":{"post":{"tags":["cameras"],"summary":"Make (or replace) the camera's key for publishing its stream; the publish address is shown only now","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"deviceId","in":"path","required":true,"schema":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"publishUrl":{"type":"string"},"path":{"type":"string"},"sentToGateway":{"type":"boolean"},"gatewayError":{"nullable":true,"type":"string"}},"required":["publishUrl","path","sentToGateway","gatewayError"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/devices/{deviceId}/watch":{"post":{"tags":["cameras"],"summary":"Watch a camera live: addresses and a token valid 5 minutes for you and this camera (every view is recorded in the activity log)","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"deviceId","in":"path","required":true,"schema":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"whepUrl":{"type":"string"},"hlsUrl":{"type":"string"},"token":{"type":"string"},"expiresAt":{"type":"string"}},"required":["whepUrl","hlsUrl","token","expiresAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/device/stream-key":{"post":{"tags":["device-endpoints"],"summary":"A camera fetches its own publish address (this replaces its earlier key)","security":[{"deviceToken":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"publishUrl":{"type":"string"}},"required":["publishUrl"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/internal/media/auth":{"post":{"tags":["internal"],"summary":"The media server's authentication hook (200 allows, 401 refuses)","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"string","maxLength":200},"password":{"type":"string","maxLength":500},"token":{"type":"string","maxLength":500},"ip":{"type":"string","maxLength":100},"action":{"type":"string","maxLength":40},"path":{"type":"string","maxLength":200},"protocol":{"type":"string","maxLength":40},"id":{"nullable":true,"type":"string","maxLength":100},"query":{"type":"string","maxLength":2000}},"additionalProperties":{}}}}},"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/developer/scopes":{"get":{"tags":["developer"],"summary":"The scopes API keys and apps can have","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"scope":{"type":"string"},"description":{"type":"string"}},"required":["scope","description"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/me/developer":{"get":{"tags":["developer"],"summary":"Whether you review apps and submissions","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"admin":{"type":"boolean"}},"required":["admin"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/api-keys":{"get":{"tags":["developer"],"summary":"This home's API keys","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"lastUsedAt":{"nullable":true,"type":"string"},"expiresAt":{"nullable":true,"type":"string"},"revokedAt":{"nullable":true,"type":"string"},"createdAt":{"type":"string"}},"required":["id","name","scopes","lastUsedAt","expiresAt","revokedAt","createdAt"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"tags":["developer"],"summary":"Make an API key for this home (the key is shown only now)","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"scopes":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","enum":["devices:read","telemetry:read","events:read","alerts:read","devices:control"]}},"expiresInDays":{"type":"integer","minimum":1,"maximum":730}},"required":["name","scopes"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"lastUsedAt":{"nullable":true,"type":"string"},"expiresAt":{"nullable":true,"type":"string"},"revokedAt":{"nullable":true,"type":"string"},"createdAt":{"type":"string"},"key":{"type":"string"}},"required":["id","name","scopes","lastUsedAt","expiresAt","revokedAt","createdAt","key"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/api-keys/{keyId}":{"delete":{"tags":["developer"],"summary":"Revoke an API key (at once)","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"keyId","in":"path","required":true,"schema":{"type":"string","pattern":"^key_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/webhooks":{"get":{"tags":["developer"],"summary":"This home's webhooks","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"eventTypes":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"failures":{"type":"number"},"disabledNote":{"nullable":true,"type":"string"},"createdAt":{"type":"string"}},"required":["id","url","eventTypes","enabled","failures","disabledNote","createdAt"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"tags":["developer"],"summary":"Send events to an HTTPS address (the signing secret is shown only now)","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":500},"eventTypes":{"minItems":1,"maxItems":30,"type":"array","items":{"type":"string","pattern":"^(\\*|[a-z_]+(\\.[a-z_]+)?(\\.\\*)?)$"}}},"required":["url","eventTypes"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"eventTypes":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"failures":{"type":"number"},"disabledNote":{"nullable":true,"type":"string"},"createdAt":{"type":"string"},"secret":{"type":"string"}},"required":["id","url","eventTypes","enabled","failures","disabledNote","createdAt","secret"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/webhooks/{webhookId}":{"patch":{"tags":["developer"],"summary":"Turn a webhook on or off, or change its events","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"webhookId","in":"path","required":true,"schema":{"type":"string","pattern":"^whk_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"eventTypes":{"minItems":1,"maxItems":30,"type":"array","items":{"type":"string","pattern":"^(\\*|[a-z_]+(\\.[a-z_]+)?(\\.\\*)?)$"}}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"eventTypes":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"failures":{"type":"number"},"disabledNote":{"nullable":true,"type":"string"},"createdAt":{"type":"string"}},"required":["id","url","eventTypes","enabled","failures","disabledNote","createdAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["developer"],"summary":"Delete a webhook","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"webhookId","in":"path","required":true,"schema":{"type":"string","pattern":"^whk_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/webhooks/{webhookId}/deliveries":{"get":{"tags":["developer"],"summary":"Recent deliveries of a webhook","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"webhookId","in":"path","required":true,"schema":{"type":"string","pattern":"^whk_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"eventId":{"type":"string"},"eventType":{"type":"string"},"status":{"type":"string"},"attempts":{"type":"number"},"lastStatus":{"nullable":true,"type":"number"},"lastError":{"nullable":true,"type":"string"},"nextAt":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","eventId","eventType","status","attempts","lastStatus","lastError","nextAt","createdAt"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/developer/apps":{"get":{"tags":["developer"],"summary":"Your apps","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"homepageUrl":{"nullable":true,"type":"string"},"redirectUris":{"type":"array","items":{"type":"string"}},"scopes":{"type":"array","items":{"type":"string"}},"confidential":{"type":"boolean"},"status":{"type":"string"},"certified":{"type":"boolean"},"reviewNotes":{"nullable":true,"type":"string"},"createdAt":{"type":"string"}},"required":["id","name","description","homepageUrl","redirectUris","scopes","confidential","status","certified","reviewNotes","createdAt"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"tags":["developer"],"summary":"Register an app (its client secret, if any, is shown only now). It works for you at once; for others after review","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":60},"description":{"default":"","type":"string","maxLength":500},"homepageUrl":{"type":"string","maxLength":300,"format":"uri"},"redirectUris":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","maxLength":500}},"scopes":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","enum":["devices:read","telemetry:read","events:read","alerts:read","devices:control"]}},"confidential":{"default":true,"type":"boolean"}},"required":["name","redirectUris","scopes"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"homepageUrl":{"nullable":true,"type":"string"},"redirectUris":{"type":"array","items":{"type":"string"}},"scopes":{"type":"array","items":{"type":"string"}},"confidential":{"type":"boolean"},"status":{"type":"string"},"certified":{"type":"boolean"},"reviewNotes":{"nullable":true,"type":"string"},"createdAt":{"type":"string"},"clientId":{"type":"string"},"clientSecret":{"nullable":true,"type":"string"}},"required":["id","name","description","homepageUrl","redirectUris","scopes","confidential","status","certified","reviewNotes","createdAt","clientId","clientSecret"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/developer/apps/{appId}":{"put":{"tags":["developer"],"summary":"Change an app. New return addresses or scopes need a new review","parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string","pattern":"^app_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":60},"description":{"default":"","type":"string","maxLength":500},"homepageUrl":{"type":"string","maxLength":300,"format":"uri"},"redirectUris":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","maxLength":500}},"scopes":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","enum":["devices:read","telemetry:read","events:read","alerts:read","devices:control"]}}},"required":["name","redirectUris","scopes"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"homepageUrl":{"nullable":true,"type":"string"},"redirectUris":{"type":"array","items":{"type":"string"}},"scopes":{"type":"array","items":{"type":"string"}},"confidential":{"type":"boolean"},"status":{"type":"string"},"certified":{"type":"boolean"},"reviewNotes":{"nullable":true,"type":"string"},"createdAt":{"type":"string"}},"required":["id","name","description","homepageUrl","redirectUris","scopes","confidential","status","certified","reviewNotes","createdAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["developer"],"summary":"Delete an app; everyone's connections to it end","parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string","pattern":"^app_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/developer/apps/{appId}/submit":{"post":{"tags":["developer"],"summary":"Ask for review, so that other people can connect it","parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string","pattern":"^app_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"homepageUrl":{"nullable":true,"type":"string"},"redirectUris":{"type":"array","items":{"type":"string"}},"scopes":{"type":"array","items":{"type":"string"}},"confidential":{"type":"boolean"},"status":{"type":"string"},"certified":{"type":"boolean"},"reviewNotes":{"nullable":true,"type":"string"},"createdAt":{"type":"string"}},"required":["id","name","description","homepageUrl","redirectUris","scopes","confidential","status","certified","reviewNotes","createdAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/developer/apps/{appId}/secret":{"post":{"tags":["developer"],"summary":"Replace the client secret (the old one stops working; shown only now)","parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string","pattern":"^app_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"clientSecret":{"type":"string"}},"required":["clientSecret"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/developer/submissions":{"get":{"tags":["developer"],"summary":"Your submissions to the catalog","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"name":{"type":"string"},"manufacturer":{"type":"string"},"repoUrl":{"nullable":true,"type":"string"},"description":{"type":"string"},"status":{"type":"string"},"certified":{"type":"boolean"},"reviewNotes":{"nullable":true,"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","kind","name","manufacturer","repoUrl","description","status","certified","reviewNotes","createdAt","updatedAt"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"tags":["developer"],"summary":"Offer a device model (checked against the catalog's capabilities now) or an adapter for review","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["device_model","adapter"]},"name":{"type":"string","minLength":2,"maxLength":80},"manufacturer":{"type":"string","minLength":2,"maxLength":80},"repoUrl":{"type":"string","maxLength":300,"format":"uri"},"description":{"default":"","type":"string","maxLength":2000},"model":{}},"required":["kind","name","manufacturer"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"name":{"type":"string"},"manufacturer":{"type":"string"},"repoUrl":{"nullable":true,"type":"string"},"description":{"type":"string"},"status":{"type":"string"},"certified":{"type":"boolean"},"reviewNotes":{"nullable":true,"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","kind","name","manufacturer","repoUrl","description","status","certified","reviewNotes","createdAt","updatedAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/admin/review":{"get":{"tags":["admin"],"summary":"Apps and submissions waiting for review (platform admins)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"apps":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"homepageUrl":{"nullable":true,"type":"string"},"redirectUris":{"type":"array","items":{"type":"string"}},"scopes":{"type":"array","items":{"type":"string"}},"confidential":{"type":"boolean"},"status":{"type":"string"},"certified":{"type":"boolean"},"reviewNotes":{"nullable":true,"type":"string"},"createdAt":{"type":"string"},"developer":{"type":"string"}},"required":["id","name","description","homepageUrl","redirectUris","scopes","confidential","status","certified","reviewNotes","createdAt","developer"],"additionalProperties":false}},"submissions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"name":{"type":"string"},"manufacturer":{"type":"string"},"repoUrl":{"nullable":true,"type":"string"},"description":{"type":"string"},"status":{"type":"string"},"certified":{"type":"boolean"},"reviewNotes":{"nullable":true,"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"developer":{"type":"string"},"payload":{}},"required":["id","kind","name","manufacturer","repoUrl","description","status","certified","reviewNotes","createdAt","updatedAt","developer","payload"],"additionalProperties":false}}},"required":["apps","submissions"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/admin/apps/{appId}/review":{"post":{"tags":["admin"],"summary":"Approve or reject an app; mark it certified (checked against the security checklist)","parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string","pattern":"^app_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["approved","rejected"]},"notes":{"type":"string","maxLength":2000},"certified":{"default":false,"type":"boolean"}},"required":["decision"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"homepageUrl":{"nullable":true,"type":"string"},"redirectUris":{"type":"array","items":{"type":"string"}},"scopes":{"type":"array","items":{"type":"string"}},"confidential":{"type":"boolean"},"status":{"type":"string"},"certified":{"type":"boolean"},"reviewNotes":{"nullable":true,"type":"string"},"createdAt":{"type":"string"}},"required":["id","name","description","homepageUrl","redirectUris","scopes","confidential","status","certified","reviewNotes","createdAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/admin/submissions/{submissionId}/review":{"post":{"tags":["admin"],"summary":"Move a submission along: in review, approved (to add to the catalog's next release) or rejected; certified after a hardware test","parameters":[{"name":"submissionId","in":"path","required":true,"schema":{"type":"string","pattern":"^sub_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["in_review","approved","rejected"]},"notes":{"type":"string","maxLength":2000},"certified":{"default":false,"type":"boolean"}},"required":["status"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"name":{"type":"string"},"manufacturer":{"type":"string"},"repoUrl":{"nullable":true,"type":"string"},"description":{"type":"string"},"status":{"type":"string"},"certified":{"type":"boolean"},"reviewNotes":{"nullable":true,"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","kind","name","manufacturer","repoUrl","description","status","certified","reviewNotes","createdAt","updatedAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/devices/{deviceId}/commands":{"post":{"tags":["commands"],"summary":"Send a command. Sensitive and critical ones come back awaiting confirmation","description":"Checked against the device's capabilities, the caller's role and the command's safety class. The answer is the command with its status; `succeeded` comes only once the device has acknowledged it and reported the expected state.","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"deviceId","in":"path","required":true,"schema":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"component":{"default":"main","type":"string","pattern":"^[a-z][a-zA-Z0-9]{0,39}$"},"capability":{"type":"string","pattern":"^iyg\\.cap\\.([a-z][a-zA-Z0-9]{0,39})@([1-9][0-9]{0,3})$"},"command":{"type":"string","pattern":"^[a-z][a-zA-Z0-9]{0,39}$"},"params":{"default":{},"type":"object","additionalProperties":{}},"ttlSeconds":{"type":"integer","minimum":5,"maximum":86400},"idempotencyKey":{"type":"string","minLength":8,"maxLength":64}},"required":["capability","command"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deviceId":{"type":"string"},"component":{"type":"string"},"capability":{"type":"string"},"command":{"type":"string"},"params":{},"source":{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":"string"},"via":{"nullable":true,"type":"string"}},"required":["kind","id","via"],"additionalProperties":false},"safety":{"type":"string"},"status":{"type":"string"},"confirmation":{},"expected":{"type":"object","additionalProperties":{}},"expiresAt":{"type":"string"},"sentAt":{"nullable":true,"type":"string"},"history":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"at":{"type":"string"},"note":{"type":"string"}},"required":["status","at"],"additionalProperties":false}},"error":{},"createdAt":{"type":"string"}},"required":["id","deviceId","component","capability","command","params","source","safety","status","confirmation","expected","expiresAt","sentAt","history","error","createdAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"get":{"tags":["commands"],"summary":"The device's recent commands, newest first","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"deviceId","in":"path","required":true,"schema":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"deviceId":{"type":"string"},"component":{"type":"string"},"capability":{"type":"string"},"command":{"type":"string"},"params":{},"source":{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":"string"},"via":{"nullable":true,"type":"string"}},"required":["kind","id","via"],"additionalProperties":false},"safety":{"type":"string"},"status":{"type":"string"},"confirmation":{},"expected":{"type":"object","additionalProperties":{}},"expiresAt":{"type":"string"},"sentAt":{"nullable":true,"type":"string"},"history":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"at":{"type":"string"},"note":{"type":"string"}},"required":["status","at"],"additionalProperties":false}},"error":{},"createdAt":{"type":"string"}},"required":["id","deviceId","component","capability","command","params","source","safety","status","confirmation","expected","expiresAt","sentAt","history","error","createdAt"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/commands/{commandId}":{"get":{"tags":["commands"],"summary":"One command with its full history","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"commandId","in":"path","required":true,"schema":{"type":"string","pattern":"^cmd_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deviceId":{"type":"string"},"component":{"type":"string"},"capability":{"type":"string"},"command":{"type":"string"},"params":{},"source":{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":"string"},"via":{"nullable":true,"type":"string"}},"required":["kind","id","via"],"additionalProperties":false},"safety":{"type":"string"},"status":{"type":"string"},"confirmation":{},"expected":{"type":"object","additionalProperties":{}},"expiresAt":{"type":"string"},"sentAt":{"nullable":true,"type":"string"},"history":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"at":{"type":"string"},"note":{"type":"string"}},"required":["status","at"],"additionalProperties":false}},"error":{},"createdAt":{"type":"string"}},"required":["id","deviceId","component","capability","command","params","source","safety","status","confirmation","expected","expiresAt","sentAt","history","error","createdAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/commands/{commandId}/confirm":{"post":{"tags":["commands"],"summary":"Confirm a sensitive or critical command. Critical ones need a sign-in within the last 5 minutes (401 step_up_required) and, if you have an authenticator or the home requires one, its code (401 mfa_required)","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"commandId","in":"path","required":true,"schema":{"type":"string","pattern":"^cmd_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mfaCode":{"type":"string","maxLength":12}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deviceId":{"type":"string"},"component":{"type":"string"},"capability":{"type":"string"},"command":{"type":"string"},"params":{},"source":{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":"string"},"via":{"nullable":true,"type":"string"}},"required":["kind","id","via"],"additionalProperties":false},"safety":{"type":"string"},"status":{"type":"string"},"confirmation":{},"expected":{"type":"object","additionalProperties":{}},"expiresAt":{"type":"string"},"sentAt":{"nullable":true,"type":"string"},"history":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"at":{"type":"string"},"note":{"type":"string"}},"required":["status","at"],"additionalProperties":false}},"error":{},"createdAt":{"type":"string"}},"required":["id","deviceId","component","capability","command","params","source","safety","status","confirmation","expected","expiresAt","sentAt","history","error","createdAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/commands/{commandId}/cancel":{"post":{"tags":["commands"],"summary":"Cancel a command that is awaiting confirmation or queued","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"commandId","in":"path","required":true,"schema":{"type":"string","pattern":"^cmd_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deviceId":{"type":"string"},"component":{"type":"string"},"capability":{"type":"string"},"command":{"type":"string"},"params":{},"source":{"type":"object","properties":{"kind":{"type":"string"},"id":{"type":"string"},"via":{"nullable":true,"type":"string"}},"required":["kind","id","via"],"additionalProperties":false},"safety":{"type":"string"},"status":{"type":"string"},"confirmation":{},"expected":{"type":"object","additionalProperties":{}},"expiresAt":{"type":"string"},"sentAt":{"nullable":true,"type":"string"},"history":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"at":{"type":"string"},"note":{"type":"string"}},"required":["status","at"],"additionalProperties":false}},"error":{},"createdAt":{"type":"string"}},"required":["id","deviceId","component","capability","command","params","source","safety","status","confirmation","expected","expiresAt","sentAt","history","error","createdAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/me/mfa":{"get":{"tags":["security"],"summary":"Whether you have an authenticator app set up","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"recoveryLeft":{"type":"number"}},"required":["enabled","recoveryLeft"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/me/mfa/setup":{"post":{"tags":["security"],"summary":"Start setting up an authenticator app: a secret to scan (needs a sign-in within 5 minutes)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"secret":{"type":"string"},"otpauthUrl":{"type":"string"},"qrSvg":{"type":"string"}},"required":["secret","otpauthUrl","qrSvg"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/me/mfa/enable":{"post":{"tags":["security"],"summary":"Finish the setup with a code from the app; returns ten one-time recovery codes (shown only now)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":6,"maxLength":12}},"required":["code"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"recoveryCodes":{"type":"array","items":{"type":"string"}}},"required":["recoveryCodes"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/me/mfa/disable":{"post":{"tags":["security"],"summary":"Turn the authenticator off (a fresh sign-in and a current code)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","minLength":6,"maxLength":12}},"required":["code"],"additionalProperties":false}}}},"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/devices/{deviceId}/telemetry":{"get":{"tags":["telemetry"],"summary":"A telemetry series for charts: raw readings, or min/avg/max per bucket","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"deviceId","in":"path","required":true,"schema":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"metric","in":"query","required":true,"schema":{"type":"string","pattern":"^([a-z][a-zA-Z0-9]{0,39})\\.([a-z][a-zA-Z0-9]{0,39})\\.([a-z][a-zA-Z0-9]{0,39})$"}},{"name":"from","in":"query","required":true,"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"bucket","in":"query","required":false,"schema":{"default":"5m","type":"string","enum":["raw","1m","5m","1h","1d"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"metric":{"type":"string"},"bucket":{"type":"string"},"points":{"type":"array","items":{"type":"object","properties":{"t":{"type":"string"},"v":{"nullable":true,"type":"number"},"min":{"nullable":true,"type":"number"},"max":{"nullable":true,"type":"number"}},"required":["t","v"],"additionalProperties":false}}},"required":["metric","bucket","points"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/devices/{deviceId}/latest":{"get":{"tags":["telemetry"],"summary":"The newest reading of every telemetry value, with its time","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"deviceId","in":"path","required":true,"schema":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"values":{"type":"object","additionalProperties":{"type":"object","properties":{"v":{},"at":{"type":"string"}},"required":["v","at"],"additionalProperties":false}}},"required":["values"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/events":{"get":{"tags":["events"],"summary":"The event log, newest first (filter by device and type)","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"subject","in":"query","required":false,"schema":{"type":"string","maxLength":40}},{"name":"type","in":"query","required":false,"schema":{"type":"string","maxLength":60}},{"name":"before","in":"query","required":false,"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"subject":{"type":"string"},"time":{"type":"string"},"data":{}},"required":["id","type","subject","time","data"],"additionalProperties":false}},"next":{"nullable":true,"type":"string"}},"required":["items","next"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/stream":{"get":{"tags":["events"],"summary":"Live events and readings (Server-Sent Events): `event: event` and `event: telemetry`","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/automations":{"get":{"tags":["automations"],"summary":"Automations, with warnings about loops and conflicts between them","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"type":"boolean"},"priority":{"type":"number"},"locationId":{"nullable":true,"type":"string"},"maxRunsPerHour":{"type":"number"},"cooldownS":{"type":"number"},"definition":{},"version":{"type":"number"},"lastRunAt":{"nullable":true,"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","enabled","priority","locationId","maxRunsPerHour","cooldownS","definition","version","lastRunAt","createdAt","updatedAt"],"additionalProperties":false}},"paused":{"type":"boolean"},"analysis":{"type":"object","properties":{"loops":{"type":"array","items":{"type":"array","items":{"type":"string"}}},"conflicts":{"type":"array","items":{}}},"required":["loops","conflicts"],"additionalProperties":false}},"required":["items","paused","analysis"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"tags":["automations"],"summary":"Create an automation (checked against the devices; critical actions are refused)","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"enabled":{"default":true,"type":"boolean"},"priority":{"default":100,"type":"integer","minimum":1,"maximum":1000},"locationId":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"},"maxRunsPerHour":{"default":30,"type":"integer","minimum":1,"maximum":120},"cooldownS":{"default":0,"type":"integer","minimum":0,"maximum":86400},"definition":{"type":"object","properties":{"triggers":{"minItems":1,"maxItems":10,"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["state"]},"deviceId":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"},"key":{"type":"string","pattern":"^([a-z][a-zA-Z0-9]{0,39})\\.([a-z][a-zA-Z0-9]{0,39})\\.([a-z][a-zA-Z0-9]{0,39})$"},"op":{"anyOf":[{"type":"string","enum":["eq","neq","gt","gte","lt","lte"]},{"type":"string","enum":["changes"]}]},"value":{"anyOf":[{"type":"boolean"},{"type":"number"},{"type":"string","maxLength":100}]},"forS":{"type":"integer","minimum":1,"maximum":86400}},"required":["kind","deviceId","key","op"]},{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"deviceId":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"},"event":{"type":"string","pattern":"^([a-z][a-zA-Z0-9]{0,39})\\.([a-z][a-zA-Z0-9]{0,39})\\.([a-z][a-zA-Z0-9]{0,39})$"}},"required":["kind","deviceId","event"]},{"type":"object","properties":{"kind":{"type":"string","enum":["connectivity"]},"deviceId":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"},"to":{"type":"string","enum":["online","offline"]},"forS":{"type":"integer","minimum":1,"maximum":86400}},"required":["kind","deviceId","to"]},{"type":"object","properties":{"kind":{"type":"string","enum":["schedule"]},"cron":{"type":"string","maxLength":80}},"required":["kind","cron"]},{"type":"object","properties":{"kind":{"type":"string","enum":["sun"]},"event":{"type":"string","enum":["sunrise","sunset"]},"offsetMin":{"default":0,"type":"integer","minimum":-240,"maximum":240}},"required":["kind","event"]}]}},"conditions":{"allOf":[{"$ref":"#/definitions/__schema0"}]},"actions":{"minItems":1,"maxItems":30,"type":"array","items":{"$ref":"#/definitions/__schema1"}}},"required":["triggers","actions"]}},"required":["name","definition"],"definitions":{"__schema0":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["state"]},"deviceId":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"},"key":{"type":"string","pattern":"^([a-z][a-zA-Z0-9]{0,39})\\.([a-z][a-zA-Z0-9]{0,39})\\.([a-z][a-zA-Z0-9]{0,39})$"},"op":{"type":"string","enum":["eq","neq","gt","gte","lt","lte"]},"value":{"anyOf":[{"type":"boolean"},{"type":"number"},{"type":"string","maxLength":100}]}},"required":["kind","deviceId","key","op","value"]},{"type":"object","properties":{"kind":{"type":"string","enum":["time"]},"after":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"before":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"days":{"maxItems":7,"type":"array","items":{"type":"integer","minimum":0,"maximum":6}}},"required":["kind"]},{"type":"object","properties":{"kind":{"type":"string","enum":["sun"]},"is":{"type":"string","enum":["day","night"]}},"required":["kind","is"]},{"type":"object","properties":{"kind":{"type":"string","enum":["all"]},"of":{"minItems":1,"maxItems":20,"type":"array","items":{"$ref":"#/definitions/__schema0"}}},"required":["kind","of"]},{"type":"object","properties":{"kind":{"type":"string","enum":["any"]},"of":{"minItems":1,"maxItems":20,"type":"array","items":{"$ref":"#/definitions/__schema0"}}},"required":["kind","of"]},{"type":"object","properties":{"kind":{"type":"string","enum":["not"]},"of":{"$ref":"#/definitions/__schema0"}},"required":["kind","of"]}]},"__schema1":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["command"]},"deviceId":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"},"component":{"default":"main","type":"string","pattern":"^[a-z][a-zA-Z0-9]{0,39}$"},"capability":{"type":"string","pattern":"^iyg\\.cap\\.([a-z][a-zA-Z0-9]{0,39})@([1-9][0-9]{0,3})$"},"command":{"type":"string","pattern":"^[a-z][a-zA-Z0-9]{0,39}$"},"params":{"default":{},"type":"object","additionalProperties":{}}},"required":["kind","deviceId","capability","command"]},{"type":"object","properties":{"kind":{"type":"string","enum":["notify"]},"title":{"type":"string","minLength":1,"maxLength":120},"body":{"default":"","type":"string","maxLength":500},"severity":{"default":"info","type":"string","enum":["info","warning","critical"]},"to":{"default":"owners_admins","type":"string","enum":["owners_admins","all_members"]}},"required":["kind","title"]},{"type":"object","properties":{"kind":{"type":"string","enum":["alert"]},"title":{"type":"string","minLength":1,"maxLength":120},"body":{"default":"","type":"string","maxLength":500},"severity":{"default":"warning","type":"string","enum":["warning","critical"]},"deviceId":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"},"to":{"default":"owners_admins","type":"string","enum":["owners_admins","all_members"]}},"required":["kind","title"]},{"type":"object","properties":{"kind":{"type":"string","enum":["delay"]},"seconds":{"type":"integer","minimum":1,"maximum":86400}},"required":["kind","seconds"]},{"type":"object","properties":{"kind":{"type":"string","enum":["if"]},"condition":{"$ref":"#/definitions/__schema0"},"then":{"minItems":1,"maxItems":20,"type":"array","items":{"$ref":"#/definitions/__schema1"}},"else":{"maxItems":20,"type":"array","items":{"$ref":"#/definitions/__schema1"}}},"required":["kind","condition","then"]}]}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"type":"boolean"},"priority":{"type":"number"},"locationId":{"nullable":true,"type":"string"},"maxRunsPerHour":{"type":"number"},"cooldownS":{"type":"number"},"definition":{},"version":{"type":"number"},"lastRunAt":{"nullable":true,"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"analysis":{"type":"object","properties":{"loops":{"type":"array","items":{"type":"array","items":{"type":"string"}}},"conflicts":{"type":"array","items":{}}},"required":["loops","conflicts"],"additionalProperties":false}},"required":["id","name","enabled","priority","locationId","maxRunsPerHour","cooldownS","definition","version","lastRunAt","createdAt","updatedAt","analysis"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/automations/{automationId}":{"put":{"tags":["automations"],"summary":"Replace an automation (a new version; its commands then run with your rights)","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"automationId","in":"path","required":true,"schema":{"type":"string","pattern":"^aut_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"enabled":{"default":true,"type":"boolean"},"priority":{"default":100,"type":"integer","minimum":1,"maximum":1000},"locationId":{"type":"string","pattern":"^loc_[0-9A-HJKMNP-TV-Z]{26}$"},"maxRunsPerHour":{"default":30,"type":"integer","minimum":1,"maximum":120},"cooldownS":{"default":0,"type":"integer","minimum":0,"maximum":86400},"definition":{"type":"object","properties":{"triggers":{"minItems":1,"maxItems":10,"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["state"]},"deviceId":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"},"key":{"type":"string","pattern":"^([a-z][a-zA-Z0-9]{0,39})\\.([a-z][a-zA-Z0-9]{0,39})\\.([a-z][a-zA-Z0-9]{0,39})$"},"op":{"anyOf":[{"type":"string","enum":["eq","neq","gt","gte","lt","lte"]},{"type":"string","enum":["changes"]}]},"value":{"anyOf":[{"type":"boolean"},{"type":"number"},{"type":"string","maxLength":100}]},"forS":{"type":"integer","minimum":1,"maximum":86400}},"required":["kind","deviceId","key","op"]},{"type":"object","properties":{"kind":{"type":"string","enum":["event"]},"deviceId":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"},"event":{"type":"string","pattern":"^([a-z][a-zA-Z0-9]{0,39})\\.([a-z][a-zA-Z0-9]{0,39})\\.([a-z][a-zA-Z0-9]{0,39})$"}},"required":["kind","deviceId","event"]},{"type":"object","properties":{"kind":{"type":"string","enum":["connectivity"]},"deviceId":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"},"to":{"type":"string","enum":["online","offline"]},"forS":{"type":"integer","minimum":1,"maximum":86400}},"required":["kind","deviceId","to"]},{"type":"object","properties":{"kind":{"type":"string","enum":["schedule"]},"cron":{"type":"string","maxLength":80}},"required":["kind","cron"]},{"type":"object","properties":{"kind":{"type":"string","enum":["sun"]},"event":{"type":"string","enum":["sunrise","sunset"]},"offsetMin":{"default":0,"type":"integer","minimum":-240,"maximum":240}},"required":["kind","event"]}]}},"conditions":{"allOf":[{"$ref":"#/definitions/__schema0"}]},"actions":{"minItems":1,"maxItems":30,"type":"array","items":{"$ref":"#/definitions/__schema1"}}},"required":["triggers","actions"]}},"required":["name","definition"],"definitions":{"__schema0":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["state"]},"deviceId":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"},"key":{"type":"string","pattern":"^([a-z][a-zA-Z0-9]{0,39})\\.([a-z][a-zA-Z0-9]{0,39})\\.([a-z][a-zA-Z0-9]{0,39})$"},"op":{"type":"string","enum":["eq","neq","gt","gte","lt","lte"]},"value":{"anyOf":[{"type":"boolean"},{"type":"number"},{"type":"string","maxLength":100}]}},"required":["kind","deviceId","key","op","value"]},{"type":"object","properties":{"kind":{"type":"string","enum":["time"]},"after":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"before":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"days":{"maxItems":7,"type":"array","items":{"type":"integer","minimum":0,"maximum":6}}},"required":["kind"]},{"type":"object","properties":{"kind":{"type":"string","enum":["sun"]},"is":{"type":"string","enum":["day","night"]}},"required":["kind","is"]},{"type":"object","properties":{"kind":{"type":"string","enum":["all"]},"of":{"minItems":1,"maxItems":20,"type":"array","items":{"$ref":"#/definitions/__schema0"}}},"required":["kind","of"]},{"type":"object","properties":{"kind":{"type":"string","enum":["any"]},"of":{"minItems":1,"maxItems":20,"type":"array","items":{"$ref":"#/definitions/__schema0"}}},"required":["kind","of"]},{"type":"object","properties":{"kind":{"type":"string","enum":["not"]},"of":{"$ref":"#/definitions/__schema0"}},"required":["kind","of"]}]},"__schema1":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["command"]},"deviceId":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"},"component":{"default":"main","type":"string","pattern":"^[a-z][a-zA-Z0-9]{0,39}$"},"capability":{"type":"string","pattern":"^iyg\\.cap\\.([a-z][a-zA-Z0-9]{0,39})@([1-9][0-9]{0,3})$"},"command":{"type":"string","pattern":"^[a-z][a-zA-Z0-9]{0,39}$"},"params":{"default":{},"type":"object","additionalProperties":{}}},"required":["kind","deviceId","capability","command"]},{"type":"object","properties":{"kind":{"type":"string","enum":["notify"]},"title":{"type":"string","minLength":1,"maxLength":120},"body":{"default":"","type":"string","maxLength":500},"severity":{"default":"info","type":"string","enum":["info","warning","critical"]},"to":{"default":"owners_admins","type":"string","enum":["owners_admins","all_members"]}},"required":["kind","title"]},{"type":"object","properties":{"kind":{"type":"string","enum":["alert"]},"title":{"type":"string","minLength":1,"maxLength":120},"body":{"default":"","type":"string","maxLength":500},"severity":{"default":"warning","type":"string","enum":["warning","critical"]},"deviceId":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"},"to":{"default":"owners_admins","type":"string","enum":["owners_admins","all_members"]}},"required":["kind","title"]},{"type":"object","properties":{"kind":{"type":"string","enum":["delay"]},"seconds":{"type":"integer","minimum":1,"maximum":86400}},"required":["kind","seconds"]},{"type":"object","properties":{"kind":{"type":"string","enum":["if"]},"condition":{"$ref":"#/definitions/__schema0"},"then":{"minItems":1,"maxItems":20,"type":"array","items":{"$ref":"#/definitions/__schema1"}},"else":{"maxItems":20,"type":"array","items":{"$ref":"#/definitions/__schema1"}}},"required":["kind","condition","then"]}]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"type":"boolean"},"priority":{"type":"number"},"locationId":{"nullable":true,"type":"string"},"maxRunsPerHour":{"type":"number"},"cooldownS":{"type":"number"},"definition":{},"version":{"type":"number"},"lastRunAt":{"nullable":true,"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"analysis":{"type":"object","properties":{"loops":{"type":"array","items":{"type":"array","items":{"type":"string"}}},"conflicts":{"type":"array","items":{}}},"required":["loops","conflicts"],"additionalProperties":false}},"required":["id","name","enabled","priority","locationId","maxRunsPerHour","cooldownS","definition","version","lastRunAt","createdAt","updatedAt","analysis"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"get":{"tags":["automations"],"summary":"One automation","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"automationId","in":"path","required":true,"schema":{"type":"string","pattern":"^aut_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"type":"boolean"},"priority":{"type":"number"},"locationId":{"nullable":true,"type":"string"},"maxRunsPerHour":{"type":"number"},"cooldownS":{"type":"number"},"definition":{},"version":{"type":"number"},"lastRunAt":{"nullable":true,"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","enabled","priority","locationId","maxRunsPerHour","cooldownS","definition","version","lastRunAt","createdAt","updatedAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"tags":["automations"],"summary":"Turn an automation on or off","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"automationId","in":"path","required":true,"schema":{"type":"string","pattern":"^aut_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}},"required":["enabled"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"type":"boolean"},"priority":{"type":"number"},"locationId":{"nullable":true,"type":"string"},"maxRunsPerHour":{"type":"number"},"cooldownS":{"type":"number"},"definition":{},"version":{"type":"number"},"lastRunAt":{"nullable":true,"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","name","enabled","priority","locationId","maxRunsPerHour","cooldownS","definition","version","lastRunAt","createdAt","updatedAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["automations"],"summary":"Delete an automation and its history","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"automationId","in":"path","required":true,"schema":{"type":"string","pattern":"^aut_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/automations/{automationId}/run":{"post":{"tags":["automations"],"summary":"Run its actions now (to try it), with your rights","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"automationId","in":"path","required":true,"schema":{"type":"string","pattern":"^aut_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string"},"status":{"type":"string"}},"required":["runId","status"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/automations/{automationId}/runs":{"get":{"tags":["automations"],"summary":"Its recent runs, with every step","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"automationId","in":"path","required":true,"schema":{"type":"string","pattern":"^aut_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"trigger":{},"steps":{},"error":{},"chainDepth":{"type":"number"},"startedAt":{"type":"string"},"finishedAt":{"nullable":true,"type":"string"},"resumeAt":{"nullable":true,"type":"string"}},"required":["id","status","trigger","steps","error","chainDepth","startedAt","finishedAt","resumeAt"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/automations/pause":{"post":{"tags":["automations"],"summary":"Emergency stop: pause every automation in this home (or resume them)","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"paused":{"type":"boolean"}},"required":["paused"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"paused":{"type":"boolean"}},"required":["paused"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/alerts":{"get":{"tags":["alerts"],"summary":"Alerts, open ones first","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"status","in":"query","required":false,"schema":{"default":"active","type":"string","enum":["open","acknowledged","resolved","active"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"deviceId":{"nullable":true,"type":"string"},"automationId":{"nullable":true,"type":"string"},"severity":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"},"status":{"type":"string"},"openedAt":{"type":"string"},"acknowledgedAt":{"nullable":true,"type":"string"},"resolvedAt":{"nullable":true,"type":"string"}},"required":["id","deviceId","automationId","severity","title","body","status","openedAt","acknowledgedAt","resolvedAt"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/alerts/{alertId}/acknowledge":{"post":{"tags":["alerts"],"summary":"Say you have seen it","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"alertId","in":"path","required":true,"schema":{"type":"string","pattern":"^alr_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deviceId":{"nullable":true,"type":"string"},"automationId":{"nullable":true,"type":"string"},"severity":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"},"status":{"type":"string"},"openedAt":{"type":"string"},"acknowledgedAt":{"nullable":true,"type":"string"},"resolvedAt":{"nullable":true,"type":"string"}},"required":["id","deviceId","automationId","severity","title","body","status","openedAt","acknowledgedAt","resolvedAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/alerts/{alertId}/resolve":{"post":{"tags":["alerts"],"summary":"Close it","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"alertId","in":"path","required":true,"schema":{"type":"string","pattern":"^alr_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deviceId":{"nullable":true,"type":"string"},"automationId":{"nullable":true,"type":"string"},"severity":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"},"status":{"type":"string"},"openedAt":{"type":"string"},"acknowledgedAt":{"nullable":true,"type":"string"},"resolvedAt":{"nullable":true,"type":"string"}},"required":["id","deviceId","automationId","severity","title","body","status","openedAt","acknowledgedAt","resolvedAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/notifications":{"get":{"tags":["notifications"],"summary":"Your notifications here, newest first, with the unread count","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"body":{"type":"string"},"severity":{"type":"string"},"link":{"nullable":true,"type":"string"},"read":{"type":"boolean"},"delivery":{},"createdAt":{"type":"string"}},"required":["id","title","body","severity","link","read","delivery","createdAt"],"additionalProperties":false}},"unread":{"type":"number"}},"required":["items","unread"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/notifications/read":{"post":{"tags":["notifications"],"summary":"Mark your notifications here as read","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"marked":{"type":"number"}},"required":["marked"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/dashboards":{"get":{"tags":["dashboards"],"summary":"Dashboards","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"widgets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z0-9]{1,16}$"},"deviceId":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"},"component":{"default":"main","type":"string","maxLength":40},"capability":{"type":"string","maxLength":60},"size":{"default":"m","type":"string","enum":["s","m","l"]}},"required":["id","deviceId","component","capability","size"],"additionalProperties":false}},"updatedAt":{"type":"string"}},"required":["id","name","widgets","updatedAt"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"tags":["dashboards"],"summary":"Create a dashboard","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"widgets":{"maxItems":60,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z0-9]{1,16}$"},"deviceId":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"},"component":{"default":"main","type":"string","maxLength":40},"capability":{"type":"string","maxLength":60},"size":{"default":"m","type":"string","enum":["s","m","l"]}},"required":["id","deviceId","capability"]}}},"required":["name","widgets"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"widgets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z0-9]{1,16}$"},"deviceId":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"},"component":{"default":"main","type":"string","maxLength":40},"capability":{"type":"string","maxLength":60},"size":{"default":"m","type":"string","enum":["s","m","l"]}},"required":["id","deviceId","component","capability","size"],"additionalProperties":false}},"updatedAt":{"type":"string"}},"required":["id","name","widgets","updatedAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/dashboards/{dashboardId}":{"put":{"tags":["dashboards"],"summary":"Save a dashboard (name and widgets, in order)","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"dashboardId","in":"path","required":true,"schema":{"type":"string","pattern":"^dsh_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60},"widgets":{"maxItems":60,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z0-9]{1,16}$"},"deviceId":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"},"component":{"default":"main","type":"string","maxLength":40},"capability":{"type":"string","maxLength":60},"size":{"default":"m","type":"string","enum":["s","m","l"]}},"required":["id","deviceId","capability"]}}},"required":["name","widgets"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"widgets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z0-9]{1,16}$"},"deviceId":{"type":"string","pattern":"^dev_[0-9A-HJKMNP-TV-Z]{26}$"},"component":{"default":"main","type":"string","maxLength":40},"capability":{"type":"string","maxLength":60},"size":{"default":"m","type":"string","enum":["s","m","l"]}},"required":["id","deviceId","component","capability","size"],"additionalProperties":false}},"updatedAt":{"type":"string"}},"required":["id","name","widgets","updatedAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["dashboards"],"summary":"Delete a dashboard","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"dashboardId","in":"path","required":true,"schema":{"type":"string","pattern":"^dsh_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/ai/status":{"get":{"tags":["ai"],"summary":"Whether the assistant can be used here, which service it uses, and today's use","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"available":{"type":"boolean"},"provider":{"nullable":true,"type":"string"},"model":{"nullable":true,"type":"string"},"usage":{"type":"object","properties":{"requests":{"type":"number"},"tokens":{"type":"number"},"limit":{"type":"number"}},"required":["requests","tokens","limit"],"additionalProperties":false}},"required":["enabled","available","provider","model","usage"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/ai/conversations":{"get":{"tags":["ai"],"summary":"Your conversations with the assistant here, newest first","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"updatedAt":{"type":"string"}},"required":["id","title","updatedAt"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"tags":["ai"],"summary":"Start a conversation","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/ai/conversations/{conversationId}":{"get":{"tags":["ai"],"summary":"A conversation as you saw it, with its proposals","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","pattern":"^aic_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"transcript":{},"proposals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"summary":{"type":"string"},"safety":{"type":"string"},"status":{"type":"string"},"payload":{},"result":{},"createdAt":{"type":"string"},"expiresAt":{"type":"string"}},"required":["id","kind","summary","safety","status","payload","result","createdAt","expiresAt"],"additionalProperties":false}}},"required":["id","title","transcript","proposals"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["ai"],"summary":"Delete a conversation and its pending proposals","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","pattern":"^aic_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/ai/conversations/{conversationId}/messages":{"post":{"tags":["ai"],"summary":"Ask the assistant. It reads your devices with your rights and can only suggest actions, which you approve","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","pattern":"^aic_[0-9A-HJKMNP-TV-Z]{26}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":4000}},"required":["text"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string"},"stop":{"type":"string"},"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"ok":{"type":"boolean"},"summary":{"type":"string"}},"required":["name","ok","summary"],"additionalProperties":false}},"proposals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"summary":{"type":"string"},"safety":{"type":"string"},"status":{"type":"string"},"payload":{},"result":{},"createdAt":{"type":"string"},"expiresAt":{"type":"string"}},"required":["id","kind","summary","safety","status","payload","result","createdAt","expiresAt"],"additionalProperties":false}}},"required":["text","stop","tools","proposals"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/ai/proposals/{proposalId}/approve":{"post":{"tags":["ai"],"summary":"Do what the assistant suggested, as you: a command (with the usual confirmation for sensitive and critical ones) or an automation saved by you","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"proposalId","in":"path","required":true,"schema":{"type":"string","pattern":"^aip_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"summary":{"type":"string"},"safety":{"type":"string"},"status":{"type":"string"},"payload":{},"result":{},"createdAt":{"type":"string"},"expiresAt":{"type":"string"},"command":{},"automationId":{"type":"string"}},"required":["id","kind","summary","safety","status","payload","result","createdAt","expiresAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/ai/proposals/{proposalId}/dismiss":{"post":{"tags":["ai"],"summary":"Turn down a suggestion","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"proposalId","in":"path","required":true,"schema":{"type":"string","pattern":"^aip_[0-9A-HJKMNP-TV-Z]{26}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"summary":{"type":"string"},"safety":{"type":"string"},"status":{"type":"string"},"payload":{},"result":{},"createdAt":{"type":"string"},"expiresAt":{"type":"string"}},"required":["id","kind","summary","safety","status","payload","result","createdAt","expiresAt"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/ai/summary":{"get":{"tags":["ai"],"summary":"What happened at home: facts, and a written summary when the assistant is allowed here","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"hours","in":"query","required":false,"schema":{"default":24,"type":"integer","minimum":1,"maximum":168}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"facts":{},"text":{"nullable":true,"type":"string"}},"required":["facts","text"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/energy":{"get":{"tags":["ai"],"summary":"Energy per device with suggestions (computed here; no AI service involved)","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"days","in":"query","required":false,"schema":{"default":7,"type":"integer","minimum":1,"maximum":30}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/tenants/{tenantId}/anomalies":{"get":{"tags":["ai"],"summary":"Unusual readings found by anomaly detection","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","pattern":"^ten_[0-9A-HJKMNP-TV-Z]{26}$"}},{"name":"hours","in":"query","required":false,"schema":{"default":168,"type":"integer","minimum":1,"maximum":720}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"deviceId":{"type":"string"},"metric":{"type":"string"},"value":{"type":"number"},"mean":{"type":"number"},"std":{"type":"number"},"z":{"type":"number"},"alertId":{"nullable":true,"type":"string"},"at":{"type":"string"}},"required":["id","deviceId","metric","value","mean","std","z","alertId","at"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/me/notification-prefs":{"get":{"tags":["notifications"],"summary":"Your notification settings, and which channels this service offers","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"boolean"},"push":{"type":"boolean"},"minSeverity":{"type":"string","enum":["info","warning","critical"]},"available":{"type":"object","properties":{"email":{"type":"boolean"},"push":{"type":"boolean"}},"required":["email","push"],"additionalProperties":false},"pushPublicKey":{"nullable":true,"type":"string"},"browsers":{"type":"number"}},"required":["email","push","minSeverity","available","pushPublicKey","browsers"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"put":{"tags":["notifications"],"summary":"Change your notification settings (in-app notifications are always on)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"boolean"},"push":{"type":"boolean"},"minSeverity":{"type":"string","enum":["info","warning","critical"]}},"required":["email","push","minSeverity"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"boolean"},"push":{"type":"boolean"},"minSeverity":{"type":"string","enum":["info","warning","critical"]}},"required":["email","push","minSeverity"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/me/push-subscriptions":{"post":{"tags":["notifications"],"summary":"Turn on push notifications in this browser (the browser's PushSubscription)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"endpoint":{"type":"string","maxLength":1000,"format":"uri"},"keys":{"type":"object","properties":{"p256dh":{"type":"string","minLength":20,"maxLength":200},"auth":{"type":"string","minLength":8,"maxLength":100}},"required":["p256dh","auth"]}},"required":["endpoint","keys"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}},"required":["id"],"additionalProperties":false}}}},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["notifications"],"summary":"Turn off push notifications in a browser (by its endpoint)","parameters":[{"name":"endpoint","in":"query","required":true,"schema":{"type":"string","maxLength":1000,"format":"uri"}}],"responses":{"204":{"description":"Done"},"default":{"description":"Error","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"securitySchemes":{"userToken":{"type":"http","scheme":"bearer","description":"Firebase ID token of the iYugam account (project iyugam-web)"},"integrationToken":{"type":"http","scheme":"bearer","description":"A home's API key (iyk_...) or an OAuth access token (iyo_...): the integration API only"},"deviceToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"ES256 JWT signed with the device's own key: {sub: device id, aud: iyugam-iot, iat, exp <= iat + 600, jti}"}},"schemas":{"Problem":{"type":"object","required":["type","title","status","code","detail","requestId"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"},"requestId":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}}