{
  "asyncapi": "3.0.0",
  "info": {
    "title": "ALYT device events",
    "version": "0.1.0",
    "description": "What a device and the platform exchange on the broker. The broker is internal and never published: your code receives these messages through webhooks or the event stream on developers.alyt.com, with the same shapes. Every message here is validated by the bridge with the schema shown; anything else is dropped."
  },
  "servers": {
    "broker": {
      "host": "internal",
      "protocol": "mqtt",
      "description": "Mosquitto, reachable by devices with a per-device credential only. Not reachable from the internet."
    }
  },
  "channels": {
    "status": {
      "address": "alyt/{tenantId}/{propertyId}/{deviceId}/status",
      "title": "status",
      "summary": "The device's current state, nested by capability id, plus firmware and radio facts.",
      "parameters": {
        "tenantId": {
          "description": "The tenant (a brand or an installer's customer base) the device belongs to."
        },
        "propertyId": {
          "description": "The property, a home; a device that moves home keeps its credential, which is why this segment is a wildcard in its ACL."
        },
        "deviceId": {
          "description": "The device's id in the platform, which is also the only subtree its credential may read and write."
        }
      },
      "messages": {
        "statusMessage": {
          "$ref": "#/components/messages/statusMessage"
        }
      }
    },
    "telemetry": {
      "address": "alyt/{tenantId}/{propertyId}/{deviceId}/telemetry",
      "title": "telemetry",
      "summary": "Readings, one per metric, stored as time series.",
      "parameters": {
        "tenantId": {
          "description": "The tenant (a brand or an installer's customer base) the device belongs to."
        },
        "propertyId": {
          "description": "The property, a home; a device that moves home keeps its credential, which is why this segment is a wildcard in its ACL."
        },
        "deviceId": {
          "description": "The device's id in the platform, which is also the only subtree its credential may read and write."
        }
      },
      "messages": {
        "telemetryMessage": {
          "$ref": "#/components/messages/telemetryMessage"
        }
      }
    },
    "events": {
      "address": "alyt/{tenantId}/{propertyId}/{deviceId}/events",
      "title": "events",
      "summary": "Something that happened once: a button, a motion, a door. Counted today, stored when notification-service consumes it.",
      "parameters": {
        "tenantId": {
          "description": "The tenant (a brand or an installer's customer base) the device belongs to."
        },
        "propertyId": {
          "description": "The property, a home; a device that moves home keeps its credential, which is why this segment is a wildcard in its ACL."
        },
        "deviceId": {
          "description": "The device's id in the platform, which is also the only subtree its credential may read and write."
        }
      },
      "messages": {
        "eventsMessage": {
          "$ref": "#/components/messages/eventsMessage"
        }
      }
    },
    "alerts": {
      "address": "alyt/{tenantId}/{propertyId}/{deviceId}/alerts",
      "title": "alerts",
      "summary": "A condition the household should hear about, raised by the device itself.",
      "parameters": {
        "tenantId": {
          "description": "The tenant (a brand or an installer's customer base) the device belongs to."
        },
        "propertyId": {
          "description": "The property, a home; a device that moves home keeps its credential, which is why this segment is a wildcard in its ACL."
        },
        "deviceId": {
          "description": "The device's id in the platform, which is also the only subtree its credential may read and write."
        }
      },
      "messages": {
        "alertsMessage": {
          "$ref": "#/components/messages/alertsMessage"
        }
      }
    },
    "commands": {
      "address": "alyt/{tenantId}/{propertyId}/{deviceId}/commands",
      "title": "commands",
      "summary": "A command from the platform, one per pending command-history row.",
      "parameters": {
        "tenantId": {
          "description": "The tenant (a brand or an installer's customer base) the device belongs to."
        },
        "propertyId": {
          "description": "The property, a home; a device that moves home keeps its credential, which is why this segment is a wildcard in its ACL."
        },
        "deviceId": {
          "description": "The device's id in the platform, which is also the only subtree its credential may read and write."
        }
      },
      "messages": {
        "commandsMessage": {
          "$ref": "#/components/messages/commandsMessage"
        }
      }
    },
    "response": {
      "address": "alyt/{tenantId}/{propertyId}/{deviceId}/response",
      "title": "response",
      "summary": "The device's answer to a command, by id.",
      "parameters": {
        "tenantId": {
          "description": "The tenant (a brand or an installer's customer base) the device belongs to."
        },
        "propertyId": {
          "description": "The property, a home; a device that moves home keeps its credential, which is why this segment is a wildcard in its ACL."
        },
        "deviceId": {
          "description": "The device's id in the platform, which is also the only subtree its credential may read and write."
        }
      },
      "messages": {
        "responseMessage": {
          "$ref": "#/components/messages/responseMessage"
        }
      }
    },
    "availability": {
      "address": "alyt/{tenantId}/{propertyId}/{deviceId}/availability",
      "title": "availability",
      "summary": "Online or offline, retained, set by the broker's last will when the device drops.",
      "parameters": {
        "tenantId": {
          "description": "The tenant (a brand or an installer's customer base) the device belongs to."
        },
        "propertyId": {
          "description": "The property, a home; a device that moves home keeps its credential, which is why this segment is a wildcard in its ACL."
        },
        "deviceId": {
          "description": "The device's id in the platform, which is also the only subtree its credential may read and write."
        }
      },
      "messages": {
        "availabilityMessage": {
          "$ref": "#/components/messages/availabilityMessage"
        }
      },
      "bindings": {
        "mqtt": {
          "retain": true
        }
      }
    }
  },
  "operations": {
    "receiveStatus": {
      "action": "receive",
      "channel": {
        "$ref": "#/channels/status"
      },
      "summary": "A device publishes status; the platform stores or counts it."
    },
    "receiveTelemetry": {
      "action": "receive",
      "channel": {
        "$ref": "#/channels/telemetry"
      },
      "summary": "A device publishes telemetry; the platform stores or counts it."
    },
    "receiveEvents": {
      "action": "receive",
      "channel": {
        "$ref": "#/channels/events"
      },
      "summary": "A device publishes events; the platform stores or counts it."
    },
    "receiveAlerts": {
      "action": "receive",
      "channel": {
        "$ref": "#/channels/alerts"
      },
      "summary": "A device publishes alerts; the platform stores or counts it."
    },
    "sendCommands": {
      "action": "send",
      "channel": {
        "$ref": "#/channels/commands"
      },
      "summary": "The platform publishes a command to one device."
    },
    "receiveResponse": {
      "action": "receive",
      "channel": {
        "$ref": "#/channels/response"
      },
      "summary": "A device publishes response; the platform stores or counts it."
    },
    "receiveAvailability": {
      "action": "receive",
      "channel": {
        "$ref": "#/channels/availability"
      },
      "summary": "A device publishes availability; the platform stores or counts it."
    }
  },
  "components": {
    "messages": {
      "statusMessage": {
        "name": "statusMessage",
        "title": "Status",
        "summary": "The device's current state, nested by capability id, plus firmware and radio facts.",
        "contentType": "application/json",
        "payload": {
          "$ref": "#/components/schemas/statusMessage"
        },
        "examples": [
          {
            "name": "typical",
            "payload": {
              "firmware": "1.4.2",
              "rssi": -58,
              "light": {
                "power": true,
                "brightness": 60
              }
            }
          }
        ]
      },
      "telemetryMessage": {
        "name": "telemetryMessage",
        "title": "Telemetry",
        "summary": "Readings, one per metric, stored as time series.",
        "contentType": "application/json",
        "payload": {
          "$ref": "#/components/schemas/telemetryMessage"
        },
        "examples": [
          {
            "name": "typical",
            "payload": {
              "metrics": {
                "temperature": 21.4,
                "humidity": 48
              }
            }
          }
        ]
      },
      "eventsMessage": {
        "name": "eventsMessage",
        "title": "Events",
        "summary": "Something that happened once: a button, a motion, a door. Counted today, stored when notification-service consumes it.",
        "contentType": "application/json",
        "payload": {
          "$ref": "#/components/schemas/eventsMessage"
        },
        "examples": [
          {
            "name": "typical",
            "payload": {
              "event": "button",
              "button": 1,
              "action": "single"
            }
          }
        ]
      },
      "alertsMessage": {
        "name": "alertsMessage",
        "title": "Alerts",
        "summary": "A condition the household should hear about, raised by the device itself.",
        "contentType": "application/json",
        "payload": {
          "$ref": "#/components/schemas/alertsMessage"
        },
        "examples": [
          {
            "name": "typical",
            "payload": {
              "alert": "water_leak",
              "severity": "high"
            }
          }
        ]
      },
      "commandsMessage": {
        "name": "commandsMessage",
        "title": "Commands",
        "summary": "A command from the platform, one per pending command-history row.",
        "contentType": "application/json",
        "payload": {
          "$ref": "#/components/schemas/commandsMessage"
        },
        "examples": [
          {
            "name": "typical",
            "payload": {
              "commandId": "1042",
              "command": "set",
              "payload": {
                "capability": "light",
                "key": "power",
                "value": true
              }
            }
          }
        ]
      },
      "responseMessage": {
        "name": "responseMessage",
        "title": "Response",
        "summary": "The device's answer to a command, by id.",
        "contentType": "application/json",
        "payload": {
          "$ref": "#/components/schemas/responseMessage"
        },
        "examples": [
          {
            "name": "typical",
            "payload": {
              "commandId": "1042",
              "command": "set",
              "status": "ok"
            }
          }
        ]
      },
      "availabilityMessage": {
        "name": "availabilityMessage",
        "title": "Availability",
        "summary": "Online or offline, retained, set by the broker's last will when the device drops.",
        "contentType": "application/json",
        "payload": {
          "$ref": "#/components/schemas/availabilityMessage"
        },
        "examples": [
          {
            "name": "typical",
            "payload": "online"
          }
        ]
      }
    },
    "schemas": {
      "statusMessage": {
        "type": "object",
        "additionalProperties": {}
      },
      "telemetryMessage": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "metric": {
                "type": "string",
                "minLength": 1,
                "maxLength": 64,
                "description": "The metric's name, stable per device model: `temperature`, `rssi`, `energy_wh`."
              },
              "value": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "payload": {
                "type": [
                  "object",
                  "null"
                ],
                "additionalProperties": {}
              }
            },
            "required": [
              "metric"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "metrics": {
                "type": "object",
                "additionalProperties": {
                  "type": "number"
                },
                "description": "Several metrics read at once, each a finite number."
              }
            },
            "required": [
              "metrics"
            ],
            "additionalProperties": false
          }
        ]
      },
      "eventsMessage": {
        "type": "object",
        "additionalProperties": {}
      },
      "alertsMessage": {
        "type": "object",
        "additionalProperties": {}
      },
      "commandsMessage": {
        "type": "object",
        "properties": {
          "commandId": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "The command's id as a decimal string; echoed back in the response."
          },
          "command": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "The verb the device understands: `set`, `reboot`, `set_volume`, `identify`."
          },
          "payload": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": {}
          }
        },
        "required": [
          "commandId",
          "command",
          "payload"
        ],
        "additionalProperties": false
      },
      "responseMessage": {
        "type": "object",
        "properties": {
          "commandId": {
            "type": "string",
            "pattern": "^\\d+$"
          },
          "command": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          },
          "status": {
            "type": "string",
            "minLength": 1,
            "maxLength": 32
          }
        },
        "additionalProperties": false
      },
      "availabilityMessage": {
        "anyOf": [
          {
            "type": "string",
            "enum": [
              "online",
              "offline"
            ]
          },
          {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "online",
                  "offline"
                ]
              }
            },
            "required": [
              "status"
            ],
            "additionalProperties": false
          }
        ]
      }
    }
  }
}