aedifion MQTT API

asyncapi: 3.0.0
info:
  title: aedifion MQTT API
  version: '2'
  description: >-
    Event-driven interface to the aedifion.io building operations platform. The broker carries
    three topic families - building timeseries observations, semantic metadata, and control
    commands - namespaced by load-balancing group and project handle.


    PROVENANCE: aedifion publishes no AsyncAPI document. This description was GENERATED by API
    Evangelist from aedifion's own published MQTT specification at
    https://docs.aedifion.io/en/developers/mqtt-api/ - every host, port, topic pattern, payload
    format and QoS statement below is taken from that page. Nothing here is inferred beyond
    what the documentation states. It is a third-party rendering of a documented interface, not
    a contract aedifion ships.
  contact:
    name: aedifion GmbH
    url: https://www.aedifion.com/kontakt
    email: contact@aedifion.com
  externalDocs:
    description: aedifion MQTT API documentation
    url: https://docs.aedifion.io/en/developers/mqtt-api/
x-generated-by: API Evangelist enrichment pipeline
x-generated-from: documentation
x-source-url: https://docs.aedifion.io/en/developers/mqtt-api/
x-generated-date: '2026-09-09'
servers:
  cloud-mqtts:
    host: mqtt.aedifion.io:8883
    protocol: secure-mqtt
    protocolVersion: 3.1.1
    description: >-
      Native MQTT over TLS. Brokers accept only TLS 1.2 and TLS 1.3; plain TCP connections are
      rejected. Server certificates are issued by Let's Encrypt.
    security:
    - $ref: '#/components/securitySchemes/userPassword'
  cloud-wss:
    host: mqtt.aedifion.io:9001
    protocol: secure-mqtt
    protocolVersion: 3.1.1
    description: MQTT over WebSockets via TLS, for browser clients.
    security:
    - $ref: '#/components/securitySchemes/userPassword'
  dedicated:
    host: 'mqtt.{realm}.aedifion.io:8883'
    protocol: secure-mqtt
    protocolVersion: 3.1.1
    description: Broker for a dedicated single-tenant instance.
    variables:
      realm:
        description: The customer's dedicated realm name.
    security:
    - $ref: '#/components/securitySchemes/userPassword'
channels:
  timeseries:
    address: '{loadBalancingGroup}/{projectHandle}'
    title: Building timeseries observations
    description: >-
      Observation stream for a project. Messages must strictly adhere to InfluxDB Line
      Protocol. Publishing requires write access to the topic; subscribing requires read access.
    parameters:
      loadBalancingGroup:
        description: The load-balancing group assigned to the project. Also present on the
          Project resource in the HTTP API as load_balancing_group.
      projectHandle:
        description: The project's handle, as returned by the HTTP API Project resource.
    messages:
      observation:
        $ref: '#/components/messages/observation'
  metadata:
    address: 'META/{loadBalancingGroup}/{projectHandle}'
    title: Semantic metadata
    description: >-
      Metadata about datapoints and entities, as JSON. Messages may not exceed 1 MB. Two
      schemes exist - V1 is deprecated, V2 is current and uses an entity/mode/tags structure.
    parameters:
      loadBalancingGroup:
        description: The load-balancing group assigned to the project.
      projectHandle:
        description: The project's handle.
    messages:
      metadata:
        $ref: '#/components/messages/metadata'
  controls:
    address: 'CONTROLS/{loadBalancingGroup}/{projectHandle}'
    title: Control commands
    description: >-
      Setpoints and schedules, as JSON, using the SWOP protocol. This channel writes to physical
      building equipment.
    parameters:
      loadBalancingGroup:
        description: The load-balancing group assigned to the project.
      projectHandle:
        description: The project's handle.
    messages:
      control:
        $ref: '#/components/messages/control'
operations:
  publishObservation:
    action: send
    channel:
      $ref: '#/channels/timeseries'
    summary: Publish building telemetry into the platform.
    description: Requires write access to the topic. QoS 0, 1 and 2 are all supported.
    messages:
    - $ref: '#/channels/timeseries/messages/observation'
  subscribeObservation:
    action: receive
    channel:
      $ref: '#/channels/timeseries'
    summary: Subscribe to a project's live observation stream.
    description: Requires read access to the topic. MQTT hierarchical wildcards (+, #) apply.
    messages:
    - $ref: '#/channels/timeseries/messages/observation'
  publishMetadata:
    action: send
    channel:
      $ref: '#/channels/metadata'
    summary: Publish semantic metadata for datapoints and entities.
    messages:
    - $ref: '#/channels/metadata/messages/metadata'
  subscribeControls:
    action: receive
    channel:
      $ref: '#/channels/controls'
    summary: Receive setpoint and schedule commands for building equipment.
    messages:
    - $ref: '#/channels/controls/messages/control'
components:
  securitySchemes:
    userPassword:
      type: userPassword
      description: >-
        Username and password presented in the MQTT CONNECT packet, over TLS. Limited-validity
        credentials are minted through the HTTP API's MQTT user-management endpoints;
        unlimited-validity credentials are issued only on request by aedifion staff.
        Authorization is per-topic - read to subscribe, write to publish.
  messages:
    observation:
      name: observation
      title: Timeseries observation
      summary: One or more datapoint observations in InfluxDB Line Protocol.
      contentType: text/plain
      payload:
        type: string
        description: >-
          InfluxDB Line Protocol. The documented form is
          `datapoint value=<float> <nanosecond-timestamp>`. Multiple datapoints may be sent in
          a single message.
        examples:
        - 'bacnet100-4120-CO2 value=612.0 1757404800000000000'
    metadata:
      name: metadata
      title: Entity metadata
      summary: Semantic metadata for a datapoint or entity, JSON, max 1 MB.
      contentType: application/json
      payload:
        type: object
        description: >-
          Scheme V2 - entity/mode/tags structure. Scheme V1 is deprecated. aedifion does not
          publish a JSON Schema for either scheme, so the property set is not reproduced here
          rather than guessed.
    control:
      name: control
      title: Control command
      summary: Setpoint or schedule command, JSON, SWOP protocol.
      contentType: application/json
      payload:
        type: object
        description: >-
          SWOP protocol message. aedifion does not publish a JSON Schema for SWOP, so the
          property set is not reproduced here rather than guessed. See
          https://docs.aedifion.io/en/products/io/setpoints-and-schedules/protocol/