openapi: 3.1.0
info:
  title: Cozify Hub API Documentation
  version: 0.1.0
  description: 'Draft OpenAPI 3.1 document generated from `hub_api.md`.


    Notes:

    - This file is generated from markdown only.

    - Payload schemas are placeholders unless the markdown defines them precisely.

    - The normal local versioned API is served under `/cc/{apiVersion}`.

    - `GET /hub` is also available without the versioned prefix and is used for bootstrap.

    - The Hub API uses the `Authorization` header with the raw HubKey value. No `Bearer`
    prefix is used.

    '
servers:
- url: http://{host}:8893/cc/{apiVersion}
  description: Local Hub API
  variables:
    host:
      default: 192.168.1.42
    apiVersion:
      default: '1.14'
- url: https://{remoteHost}/ui/{uiVersion}/hub/remote/cc/{apiVersion}
  description: Remote Hub API proxy
  variables:
    remoteHost:
      default: api.cozify.fi
    uiVersion:
      default: '0.2'
    apiVersion:
      default: '1.14'
security:
- AuthorizationToken: []
tags:
- name: General Hub
- name: Devices
- name: Groups
- name: Rules
- name: Scenes
- name: Rooms
- name: Alarms
- name: BACnet
- name: Log
paths:
  /hub:
    get:
      tags:
      - General Hub
      operationId: getHub
      summary: Gets Hub metadata.
      description: 'Gets Hub metadata.


        This endpoint is the primary local bootstrap entry point. It is used to identify
        the target Hub, determine its lifecycle state, and derive the versioned API
        prefix.


        This endpoint is available only as unversioned `GET /hub`. It is not part
        of the versioned `/cc/<api-version>/hub/...` endpoint set.


        For remote-only bootstrap through the cloud relay, use `GET /hub/remote/hub`
        with:


        - `Authorization: <cloud-token>` - `X-Hub-Key: <hub-key>`


        `GET /hub/remote/hub` returns the same Hub metadata object and is the documented
        way to bootstrap remote-only Hub selection before the client knows which `/hub/remote/cc/<api-version>/...`
        prefix to use.'
      x-access-right: ANONYMOUS_ACCESS
      security: []
      responses:
        '200':
          description: Hub metadata object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBody'
      servers:
      - url: http://{host}:8893
        description: Unversioned local bootstrap endpoint
        variables:
          host:
            default: 192.168.1.42
  /hub/claim:
    post:
      tags:
      - General Hub
      operationId: postHubClaim
      summary: Claims a factory-new Hub for the given email address.
      description: Claims a factory-new Hub for the given email address. This endpoint
        is only valid while the Hub is in the `factory_new` state.
      x-access-right: ANONYMOUS_ACCESS
      security: []
      parameters:
      - in: query
        name: email
        required: true
        description: email address used for claiming the Hub
        schema:
          type: string
          format: email
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/name:
    put:
      tags:
      - General Hub
      operationId: putHubName
      summary: Sets the Hub name.
      description: Sets the Hub name. This endpoint can also set the house type in
        the same request.
      x-access-right: USER_ADMIN_ACCESS
      parameters:
      - in: query
        name: name
        required: true
        description: new Hub name
        schema:
          type: string
      - in: query
        name: housetype
        required: false
        description: optional house type value
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/poll:
    get:
      tags:
      - General Hub
      operationId: getHubPoll
      summary: Polls the Hub for data.
      description: 'Polls the Hub for data.


        This endpoint returns Hub data which has changed since the given timestamp
        parameters. It is the main endpoint for incremental synchronization.


        Recommended usage:


        1. Call `GET /hub/poll?ts=0` for the initial synchronization. 2. For each
        subsequent poll, set `ts` to the timestamp returned by the previous poll response.
        3. Use only the `ts` and `cozify_uuid` query parameters in normal clients.
        4. When polling the Hub over LAN, send the next poll about two seconds after
        receiving the previous response. 5. When polling the Hub remotely through
        the cloud service, send the next poll about five seconds after receiving the
        previous response.


        Example:


        All timestamps are milliseconds since EPOCH.


        `cozify_uuid` should identify the client application instance. The recommended
        value is a 16-byte UUID for that installation or app instance. The field is
        mainly used for notification routing. Any string value is accepted, but clients
        should keep it stable for the same installation.'
      x-access-right: GUEST_ACCESS
      parameters:
      - in: query
        name: ts
        required: true
        description: timestamp for all data. If specified, the result contains all
          Hub data that has changed after this timestamp.
        schema:
          type: integer
      - in: query
        name: cozify_uuid
        required: false
        description: optional client identifier. Recommended for clients that maintain
          a stable application-instance identifier.
        schema:
          type: string
      responses:
        '200':
          description: 'single delta object Example sequence:'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBody'
  /hub/colors:
    get:
      tags:
      - General Hub
      operationId: getHubColors
      summary: Returns the stored color list used by the Hub UI.
      description: Returns the stored color list used by the Hub UI.
      x-access-right: GUEST_ACCESS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
    post:
      tags:
      - General Hub
      operationId: postHubColors
      summary: Stores a color value in the Hub color list.
      description: Stores a color value in the Hub color list.
      x-access-right: GUEST_ACCESS
      parameters:
      - in: query
        name: color
        required: true
        description: color value to store
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
    delete:
      tags:
      - General Hub
      operationId: deleteHubColors
      summary: Clears the stored color list.
      description: Clears the stored color list.
      x-access-right: GUEST_ACCESS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/zigbeechannel:
    post:
      tags:
      - General Hub
      operationId: postHubZigbeechannel
      summary: Changes the Zigbee channel.
      description: Changes the Zigbee channel.
      x-access-right: USER_ADMIN_ACCESS
      parameters:
      - in: query
        name: channel
        required: true
        description: target Zigbee channel
        schema:
          type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/zigbeepower:
    post:
      tags:
      - General Hub
      operationId: postHubZigbeepower
      summary: Changes the Zigbee radio power.
      description: Changes the Zigbee radio power.
      x-access-right: USER_ADMIN_ACCESS
      parameters:
      - in: query
        name: power
        required: true
        description: target Zigbee transmission power
        schema:
          type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/zigbeestatus:
    get:
      tags:
      - General Hub
      operationId: getHubZigbeestatus
      summary: Returns current Zigbee network status information.
      description: Returns current Zigbee network status information.
      x-access-right: GUEST_ACCESS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/zigbeesettings:
    post:
      tags:
      - General Hub
      operationId: postHubZigbeesettings
      summary: Sets Zigbee network settings.
      description: Sets Zigbee network settings.
      x-access-right: USER_ADMIN_ACCESS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestBody'
        description: Zigbee network settings object
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/zigbeescan:
    get:
      tags:
      - General Hub
      operationId: getHubZigbeescan
      summary: Runs a Zigbee energy scan and returns the result.
      description: Runs a Zigbee energy scan and returns the result.
      x-access-right: USER_ADMIN_ACCESS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/pairphilips:
    post:
      tags:
      - General Hub
      operationId: postHubPairphilips
      summary: Starts pairing of a Philips bridge integration.
      description: Starts pairing of a Philips bridge integration.
      x-access-right: USER_ADMIN_ACCESS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/pairairpatrol:
    post:
      tags:
      - General Hub
      operationId: postHubPairairpatrol
      summary: Pairs an Airpatrol device by hardware identifier.
      description: Pairs an Airpatrol device by hardware identifier.
      x-access-right: USER_ADMIN_ACCESS
      parameters:
      - in: query
        name: hwId
        required: true
        description: Airpatrol hardware identifier
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/lockconfig:
    post:
      tags:
      - General Hub
      operationId: postHubLockconfig
      summary: Locks Hub configuration.
      description: 'Locks Hub configuration.


        This endpoint applies a lock access mask to every device so that configuration
        rights are removed while read and command rights remain available. After the
        access masks are updated, the Hub schedules the locked state to be persisted
        as a user backup.'
      x-access-right: USER_ADMIN_ACCESS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/users:
    get:
      tags:
      - General Hub
      operationId: getHubUsers
      summary: Returns Hub users.
      description: Returns Hub users.
      x-access-right: GUEST_ACCESS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/tz:
    get:
      tags:
      - General Hub
      operationId: getHubTz
      summary: Returns the current Hub timezone.
      description: Returns the current Hub timezone.
      x-access-right: GUEST_ACCESS
      responses:
        '200':
          description: timezone identifier as a string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBody'
    put:
      tags:
      - General Hub
      operationId: putHubTz
      summary: Sets the current Hub timezone.
      description: Sets the current Hub timezone.
      x-access-right: USER_ADMIN_ACCESS
      parameters:
      - in: query
        name: timezone
        required: true
        description: timezone identifier
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/housetypes:
    get:
      tags:
      - General Hub
      operationId: getHubHousetypes
      summary: Returns available house types.
      description: Returns available house types.
      x-access-right: ANONYMOUS_ACCESS
      security: []
      responses:
        '200':
          description: 'dictionary `{house type code: localized display name}` Allowed
            house type codes: `block` `row` `pair` `house` `leisure` `industrial`
            `other`'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /hub/housetype:
    get:
      tags:
      - General Hub
      operationId: getHubHousetype
      summary: Returns the current house type.
      description: Returns the current house type.
      x-access-right: GUEST_ACCESS
      responses:
        '200':
          description: house type code as a string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBody'
    put:
      tags:
      - General Hub
      operationId: putHubHousetype
      summary: Sets the current house type.
      description: Sets the current house type.
      x-access-right: USER_ADMIN_ACCESS
      parameters:
      - in: query
        name: housetype
        required: true
        description: house type value
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/timezones:
    get:
      tags:
      - General Hub
      operationId: getHubTimezones
      summary: Returns available timezone identifiers.
      description: Returns available timezone identifiers.
      x-access-right: GUEST_ACCESS
      responses:
        '200':
          description: array of timezone identifier strings
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /hub/433devices:
    get:
      tags:
      - General Hub
      operationId: getHub433devices
      summary: Returns available 433 MHz device classes.
      description: Returns available 433 MHz device classes.
      x-access-right: USER_ADMIN_ACCESS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/pair433:
    post:
      tags:
      - General Hub
      operationId: postHubPair433
      summary: Starts pairing of a 433 MHz device class.
      description: Starts pairing of a 433 MHz device class.
      x-access-right: USER_ADMIN_ACCESS
      parameters:
      - in: query
        name: device433
        required: true
        description: 433 MHz device class identifier
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/scan:
    get:
      tags:
      - General Hub
      operationId: getHubScan
      summary: Returns scan results for device discovery.
      description: Returns scan results for device discovery.
      x-access-right: USER_ADMIN_ACCESS
      parameters:
      - in: query
        name: ts
        required: false
        description: optional scan timestamp filter
        schema:
          type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
    put:
      tags:
      - General Hub
      operationId: putHubScan
      summary: Updates the `ignored` state of a discovered scan result.
      description: Updates the `ignored` state of a discovered scan result.
      x-access-right: USER_ADMIN_ACCESS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetScanResult'
        description: '`SetScanResult` object containing the discovered device id and
          the desired `ignored` value'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/stopscan:
    get:
      tags:
      - General Hub
      operationId: getHubStopscan
      summary: Stops ongoing device scanning.
      description: Stops ongoing device scanning.
      x-access-right: USER_ADMIN_ACCESS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/features:
    get:
      tags:
      - General Hub
      operationId: getHubFeatures
      summary: Returns Hub features visible to the UI.
      description: Returns Hub features visible to the UI.
      x-access-right: GUEST_ACCESS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/activatefeature:
    post:
      tags:
      - General Hub
      operationId: postHubActivatefeature
      summary: Activates a Hub feature by activation code.
      description: Activates a Hub feature by activation code.
      x-access-right: USER_ADMIN_ACCESS
      parameters:
      - in: query
        name: code
        required: true
        description: feature activation code
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/pairIp:
    post:
      tags:
      - General Hub
      operationId: postHubPairIp
      summary: Pairs an IP-based device using the supplied host data.
      description: Pairs an IP-based device using the supplied host data.
      x-access-right: USER_ADMIN_ACCESS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestBody'
        description: IP host/device description object
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/protocolconfig:
    post:
      tags:
      - General Hub
      operationId: postHubProtocolconfig
      summary: Sends protocol configuration commands to the matching protocol controller.
      description: Sends protocol configuration commands to the matching protocol
        controller.
      x-access-right: USER_ADMIN_ACCESS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestBody'
        description: list containing one protocol configuration command In practice,
          clients should send one command per request body. Z-Wave commands sent through
          this endpoint are documented in chapter 8. Modbus RTU manual pairing commands
          sent through this endpoint are documented in chapter 10. Modbus TCP server
          commands sent through this endpoint are documented in chapter 11.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/serialports:
    get:
      tags:
      - General Hub
      operationId: getHubSerialports
      summary: Returns serial port configuration data.
      description: 'Returns serial port configuration data.


        This endpoint is the authoritative source for serial-port configuration choices.
        Clients should read this response first and build the serial-port UI dynamically
        from the returned objects instead of assuming fixed controller types or fixed
        baud/data/stop/parity options.


        In practice:


        - each returned `SERIAL_CONFIG` object represents one configurable serial
        controller - `controllerType` identifies which controller the settings apply
        to - `allowedBaurates`, `allowedDatabits`, `allowedStopbits`, and `allowedParities`
        define the valid settings for that controller on that Hub build / feature
        set - clients should only allow combinations derived from this response -
        the example below is illustrative only; actual controllers and allowed values
        may differ'
      x-access-right: USER_ADMIN_ACCESS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/serialport:
    post:
      tags:
      - General Hub
      operationId: postHubSerialport
      summary: Configures a serial port controller.
      description: Configures a serial port controller. On selected Hub feature sets,
        owner-level rights may be required.
      x-access-right: USER_ADMIN_ACCESS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GETHubSerialports'
        description: serial configuration object The request should be based on an
          object previously returned by `GET /hub/serialports`. Clients should keep
          the returned `controllerType` and send `settings` using only values allowed
          for that specific controller. Do not hardcode protocol-specific defaults
          from the documentation examples.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/sync:
    get:
      tags:
      - General Hub
      operationId: getHubSync
      summary: Forces immediate state save/synchronization.
      description: Forces immediate state save/synchronization.
      x-access-right: USER_ADMIN_ACCESS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/restart:
    get:
      tags:
      - General Hub
      operationId: getHubRestart
      summary: Restarts the Hub application.
      description: Restarts the Hub application.
      x-access-right: USER_ADMIN_ACCESS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/reboot:
    get:
      tags:
      - General Hub
      operationId: getHubReboot
      summary: Reboots the Hub device.
      description: Reboots the Hub device.
      x-access-right: USER_ADMIN_ACCESS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/shutdown:
    get:
      tags:
      - General Hub
      operationId: getHubShutdown
      summary: '> `1.14.15+` only.'
      description: '> `1.14.15+` only.


        Shuts the Hub device down.'
      x-access-right: USER_ADMIN_ACCESS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /hub/remotepair:
    post:
      tags:
      - General Hub
      operationId: postHubRemotepair
      summary: '> `1.14.15+` only.'
      description: '> `1.14.15+` only.


        Creates a device directly from a serialized discovery-device description.


        The request body must be a concrete `BaseDevice` subclass from the discovery
        data model. The Hub forwards the message to `HUB_MANAGER` for asynchronous
        device creation.


        - this is not a normal user pairing endpoint - the request body must be a
        valid `BaseDevice` payload'
      x-access-right: SUPER_ADMIN_ACCESS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaseDevice'
        description: concrete `BaseDevice` object
      responses:
        '200':
          description: no documented response body
  /hub/autoconfig:
    put:
      tags:
      - General Hub
      operationId: putHubAutoconfig
      summary: Automatic configuration of the Hub.
      description: 'Automatic configuration of the Hub.


        This endpoint creates devices, rooms, scenes, and rules from configuration
        data.


        If another autoconfiguration is already running, the new request is queued
        and processed after the earlier configuration has finished.'
      x-access-right: USER_ADMIN_ACCESS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoConfiguration'
        description: '`AutoConfiguration` object, documented in [11.1 Autoconfiguration
          data](#111-autoconfiguration-data)'
      responses:
        '200':
          description: '`true` on success, otherwise an error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/True'
  /devices:
    get:
      tags:
      - Devices
      operationId: getDevices
      summary: Fetches devices.
      description: Fetches devices.
      x-access-right: GUEST_ACCESS
      parameters:
      - in: query
        name: groupId
        required: false
        description: optional group identifier. If provided, only devices in that
          group are returned.
        schema:
          type: string
      responses:
        '200':
          description: 'dictionary `{device id: device status}` The returned objects
            are defined in [Device read object](#device-read-object).'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
    put:
      tags:
      - Devices
      operationId: putDevices
      summary: Sets device metadata such as name and room.
      description: Sets device metadata such as name and room.
      x-access-right: IDENTIFIED_USER_ACCESS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        description: 'list of device metadata commands The request objects are defined
          in [Device command objects](#device-command-objects). Additional access
          rules: `DeviceAccessCommand` requires owner-level access `DeviceVisibilityCommand`
          requires owner-level access `DeviceLockedCommand` requires owner-level access'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
    delete:
      tags:
      - Devices
      operationId: deleteDevices
      summary: Deletes devices.
      description: Deletes devices.
      x-access-right: USER_ADMIN_ACCESS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        description: list of device identifiers
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /devices/command:
    put:
      tags:
      - Devices
      operationId: putDevicesCommand
      summary: Sends commands to devices.
      description: 'Sends commands to devices.


        This endpoint mixes asynchronous control commands and synchronous query-style
        commands:


        - normal device control commands are dispatched asynchronously - `IgnoreDeviceCmd`
        and `ResetIgnoreCmd` are synchronous and require `USER_ADMIN_ACCESS` - selected
        query-style commands return immediate data from the device or Hub


        For these two ignore-management commands, the serialized command types are:


        - `IgnoreDeviceCmd` -> `CMD_IGNORE_DEVICE` - `ResetIgnoreCmd` -> `CMD_RESET_IGNORED`


        For a remote caller with `REMOTE_GUEST` role, only these command types are
        allowed:


        - `GetCDCommand` - `GetQueueCommand` - `GetAirpatrollerPumps` - `GetFnipConfigs`
        - `GetUpgradeInfos` - `GetUpgradeInfo`


        Special cases:


        - `GetUpgradeInfo` returns the upgrade information for the target device -
        `GetUpgradeInfos` returns Hub-level upgrade information - `SearchCommand`,
        `UseCredentials`, `ChangeCredentials`, `ScanWifis`, `SetWifi`, `FoscamHostAtIp`,
        `GetCDCommand`, `GetQueueCommand`, `GetAirpatrollerPumps`, and `GetFnipConfigs`
        return immediate results - `SnapShotCmd` is dispatched without an immediate
        payload result - `RefreshDevice` is dispatched asynchronously; updated camera
        or device metadata is observed later via poll data


        The command payloads are defined in [Device command objects](#device-command-objects).'
      x-access-right: GUEST_ACCESS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /devices/preset:
    put:
      tags:
      - Devices
      operationId: putDevicesPreset
      summary: Runs device presets.
      description: Runs device presets.
      x-access-right: GUEST_ACCESS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        description: 'list of preset objects Additional access rules: for remote calls,
          at least `IDENTIFIED_USER_ACCESS` is required Each preset object is expected
          to contain at least: `targetIds`: target device ids `state`: device state
          to apply The reused `Preset` object shape is defined in [Scene read objects](#scene-read-objects).'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /devices/configuration:
    get:
      tags:
      - Devices
      operationId: getDevicesConfiguration
      summary: Fetches device configuration.
      description: Fetches device configuration.
      x-access-right: USER_ADMIN_ACCESS
      parameters:
      - in: query
        name: deviceId
        required: true
        description: target device identifier
        schema:
          type: string
      - in: query
        name: templates
        required: false
        description: optional string flag, default `True`. When `true`, configuration
          templates are included.
        schema:
          type: string
      responses:
        '200':
          description: device configuration object The returned object is defined
            in [Device configuration objects](#device-configuration-objects).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBody'
    put:
      tags:
      - Devices
      operationId: putDevicesConfiguration
      summary: Saves device configuration.
      description: Saves device configuration.
      x-access-right: USER_ADMIN_ACCESS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestBody'
        description: device configuration object The request object is defined in
          [Device configuration objects](#device-configuration-objects).
      responses:
        '200':
          description: '`true` if the configuration was accepted'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/True'
    delete:
      tags:
      - Devices
      operationId: deleteDevicesConfiguration
      summary: Removes device configuration and restores default values.
      description: Removes device configuration and restores default values.
      x-access-right: USER_ADMIN_ACCESS
      parameters:
      - in: query
        name: deviceId
        required: true
        description: target device identifier
        schema:
          type: string
      responses:
        '200':
          description: '`true` if successful'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/True'
  /groups:
    get:
      tags:
      - Groups
      operationId: getGroups
      summary: Fetches all groups.
      description: Fetches all groups.
      x-access-right: GUEST_ACCESS
      responses:
        '200':
          description: 'dictionary `{group id: group data}` The returned objects are
            defined in [Group read object](#group-read-object).'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
    put:
      tags:
      - Groups
      operationId: putGroups
      summary: Creates or modifies groups.
      description: 'Creates or modifies groups.


        To create a new group, set the group''s `id` field to `null`.


        - the returned group objects do not include the `state` attribute'
      x-access-right: IDENTIFIED_USER_ACCESS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        description: list of group modification commands The request objects are defined
          in [Group command objects](#group-command-objects).
      responses:
        '200':
          description: list of modified group objects The returned objects are defined
            in [Group read object](#group-read-object).
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
    delete:
      tags:
      - Groups
      operationId: deleteGroups
      summary: Deletes a group.
      description: Deletes a group.
      x-access-right: IDENTIFIED_USER_ACCESS
      parameters:
      - in: query
        name: groupId
        required: true
        description: target group identifier
        schema:
          type: string
      responses:
        '200':
          description: '`true` if successful'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/True'
  /groups/command:
    put:
      tags:
      - Groups
      operationId: putGroupsCommand
      summary: Sends commands to groups.
      description: 'Sends commands to groups.


        Supported command types:


        - `DeviceCommand` - `GroupOnCommand` - `GroupOffCommand`


        Additional access rules:


        - for remote calls, at least `IDENTIFIED_USER_ACCESS` is required


        The group-specific command payloads are defined in [Group command objects](#group-command-objects).
        `PUT /groups/command` may also use the same `CMD_DEVICE` payload shape documented
        in [Device command objects](#device-command-objects), in which case the target
        `id` is the group id.'
      x-access-right: GUEST_ACCESS
      responses:
        '200':
          description: list of command handling results returned by the group operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /rules:
    get:
      tags:
      - Rules
      operationId: getRules
      summary: Fetches rules.
      description: Fetches rules.
      x-access-right: GUEST_ACCESS
      parameters:
      - in: query
        name: ruleId
        required: false
        description: optional rule identifier. If provided, only that rule is returned.
        schema:
          type: string
      responses:
        '200':
          description: 'dictionary `{rule id: rule data}` The returned objects are
            defined in [Rule read objects](#rule-read-objects).'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
    put:
      tags:
      - Rules
      operationId: putRules
      summary: Creates or updates rules.
      description: Creates or updates rules.
      x-access-right: IDENTIFIED_USER_ACCESS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        description: '`rules`: list of rule configurations `onConfiguration`: rule
          on-configuration applied together with the rule configuration The request
          object shapes are defined in [Rule configuration objects](#rule-configuration-objects)
          and [Typed rule value objects](#typed-rule-value-objects). The response
          objects are defined in [Rule read objects](#rule-read-objects).'
      responses:
        '200':
          description: list of created or updated rule objects
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
    delete:
      tags:
      - Rules
      operationId: deleteRules
      summary: Deletes a rule.
      description: Deletes a rule.
      x-access-right: IDENTIFIED_USER_ACCESS
      parameters:
      - in: query
        name: ruleId
        required: true
        description: target rule identifier
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /rules/command:
    put:
      tags:
      - Rules
      operationId: putRulesCommand
      summary: Sends commands to rules.
      description: 'Sends commands to rules.


        Supported command types:


        - `RuleOnCommand` - `RuleOffCommand`


        The command payloads are defined in [Rule command objects](#rule-command-objects),
        and the returned objects are defined in [Rule read objects](#rule-read-objects).'
      x-access-right: IDENTIFIED_USER_ACCESS
      responses:
        '200':
          description: list of rule data objects indicating the state after the command
            is handled
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /rules/templates:
    get:
      tags:
      - Rules
      operationId: getRulesTemplates
      summary: Returns available rule templates.
      description: 'Returns available rule templates.


        The returned template objects are defined in [Rule configuration objects](#rule-configuration-objects).'
      x-access-right: GUEST_ACCESS
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /rules/template:
    get:
      tags:
      - Rules
      operationId: getRulesTemplate
      summary: '`GET /rules/template?ruleType=<rule-type>` returns the stored source
        code for one installed custom rule type.'
      description: '`GET /rules/template?ruleType=<rule-type>` returns the stored
        source code for one installed custom rule type.


        - returns the raw source string stored for that custom rule type - returns
        not found when the requested rule type is unknown - does not expose factory-rule
        implementation source'
      parameters:
      - in: query
        name: ruleType
        required: true
        description: Query parameter documented inline in the markdown source.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
    post:
      tags:
      - Rules
      operationId: postRulesTemplate
      summary: '`POST /rules/template?ruleLogic=<python-source>` installs a custom
        rule.'
      description: '`POST /rules/template?ruleLogic=<python-source>` installs a custom
        rule.


        - parses the supplied source and validates the class structure - if the same
        custom rule type already exists, the old custom rule is uninstalled first
        - if the same type belongs to a factory rule, installation fails - on success,
        returns the installed rule type string - on parse failure, returns an error


        Example success value:'
      parameters:
      - in: query
        name: ruleLogic
        required: true
        description: Query parameter documented inline in the markdown source.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
    delete:
      tags:
      - Rules
      operationId: deleteRulesTemplate
      summary: '`DELETE /rules/template?ruleType=<rule-type>` removes one custom rule
        type.'
      description: '`DELETE /rules/template?ruleType=<rule-type>` removes one custom
        rule type.


        - removes the persisted source code - removes the custom rule class from the
        available template set - clears the custom rule''s log files - disables and
        removes all existing rule instances whose `configType` matches the removed
        custom rule type - returns `true` on success'
      parameters:
      - in: query
        name: ruleType
        required: true
        description: Query parameter documented inline in the markdown source.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /rules/log:
    get:
      tags:
      - Rules
      operationId: getRulesLog
      summary: '`GET /rules/log?ruleType=<rule-type>` returns the runtime log text
        for one custom rule type.'
      description: '`GET /rules/log?ruleType=<rule-type>` returns the runtime log
        text for one custom rule type.


        - reads the current log file for that rule type - if one rotated backup log
        exists, it is concatenated before the current log - if no log files exist,
        the endpoint returns an empty string'
      parameters:
      - in: query
        name: ruleType
        required: true
        description: Query parameter documented inline in the markdown source.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /rules/onConfiguration:
    put:
      tags:
      - Rules
      operationId: putRulesOnConfiguration
      summary: Updates rule on-configuration.
      description: Updates rule on-configuration.
      x-access-right: IDENTIFIED_USER_ACCESS
      parameters:
      - in: query
        name: ruleId
        required: true
        description: target rule identifier
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestBody'
        description: on-configuration object The request object is defined in [Rule
          configuration objects](#rule-configuration-objects).
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /rules/proposals:
    post:
      tags:
      - Rules
      operationId: postRulesProposals
      summary: Returns rule proposals.
      description: Returns rule proposals.
      x-access-right: IDENTIFIED_USER_ACCESS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        description: list of rule proposal request commands The returned proposal
          objects are defined in [Rule read objects](#rule-read-objects), with nested
          configuration objects defined in [Rule configuration objects](#rule-configuration-objects).
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /scenes:
    get:
      tags:
      - Scenes
      operationId: getScenes
      summary: Fetches scenes.
      description: Fetches scenes.
      x-access-right: GUEST_ACCESS
      parameters:
      - in: query
        name: sceneId
        required: false
        description: optional scene identifier. If provided, only that scene is returned.
        schema:
          type: string
      responses:
        '200':
          description: 'dictionary `{scene id: scene data}` The returned objects are
            defined in [Scene read objects](#scene-read-objects).'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
    put:
      tags:
      - Scenes
      operationId: putScenes
      summary: Creates or modifies scenes.
      description: 'Creates or modifies scenes.


        To create a new scene, set the scene `id` to `null`.'
      x-access-right: IDENTIFIED_USER_ACCESS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        description: list of `ChangeScene` commands The request objects are defined
          in [Scene command objects](#scene-command-objects).
      responses:
        '200':
          description: list of modified scene objects The returned objects are defined
            in [Scene read objects](#scene-read-objects).
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
    delete:
      tags:
      - Scenes
      operationId: deleteScenes
      summary: Deletes a scene.
      description: Deletes a scene.
      x-access-right: IDENTIFIED_USER_ACCESS
      parameters:
      - in: query
        name: sceneId
        required: true
        description: target scene identifier
        schema:
          type: string
      responses:
        '200':
          description: '`true` if successful'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/True'
  /scenes/command:
    put:
      tags:
      - Scenes
      operationId: putScenesCommand
      summary: Sends commands to scenes.
      description: 'Sends commands to scenes.


        Supported command types:


        - `ChangeScene` - `SceneOnCommand` - `SceneOffCommand`


        Additional access rules:


        - for remote calls, at least `IDENTIFIED_USER_ACCESS` is required - `ChangeScene`
        itself requires `IDENTIFIED_USER_ACCESS` even on local calls'
      x-access-right: GUEST_ACCESS
      responses:
        '200':
          description: list of scene data objects indicating the state after the command
            is handled The command payloads are defined in [Scene command objects](#scene-command-objects),
            and the returned scene objects are defined in [Scene read objects](#scene-read-objects).
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /rooms:
    get:
      tags:
      - Rooms
      operationId: getRooms
      summary: Fetches rooms.
      description: Fetches rooms.
      x-access-right: GUEST_ACCESS
      parameters:
      - in: query
        name: roomId
        required: false
        description: optional room identifier. If provided, only that room is returned.
        schema:
          type: string
      responses:
        '200':
          description: 'dictionary `{room id: room data}` The returned objects are
            defined in [Room read objects](#room-read-objects).'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
    put:
      tags:
      - Rooms
      operationId: putRooms
      summary: Creates or modifies rooms.
      description: 'Creates or modifies rooms.


        To create a new room, set the room `id` to `null`.'
      x-access-right: IDENTIFIED_USER_ACCESS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        description: list of room commands The request objects are defined in [Room
          command objects](#room-command-objects).
      responses:
        '200':
          description: list of success values
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
    delete:
      tags:
      - Rooms
      operationId: deleteRooms
      summary: Deletes a room.
      description: Deletes a room.
      x-access-right: IDENTIFIED_USER_ACCESS
      parameters:
      - in: query
        name: roomId
        required: true
        description: target room identifier
        schema:
          type: string
      responses:
        '200':
          description: '`true` if successful'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/True'
  /rooms/order:
    put:
      tags:
      - Rooms
      operationId: putRoomsOrder
      summary: Changes room ordering.
      description: Changes room ordering.
      x-access-right: IDENTIFIED_USER_ACCESS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        description: list of `SetRoomOrder` commands The request objects are defined
          in [Room command objects](#room-command-objects).
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /alarms:
    get:
      tags:
      - Alarms
      operationId: getAlarms
      summary: Fetches alarms.
      description: Fetches alarms.
      x-access-right: GUEST_ACCESS
      parameters:
      - in: query
        name: alarmId
        required: false
        description: optional alarm identifier. If provided, only that alarm is returned.
        schema:
          type: string
      responses:
        '200':
          description: 'dictionary `{alarm id: alarm data}`'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
    delete:
      tags:
      - Alarms
      operationId: deleteAlarms
      summary: Deletes an alarm.
      description: Deletes an alarm.
      x-access-right: IDENTIFIED_USER_ACCESS
      parameters:
      - in: query
        name: alarmId
        required: true
        description: target alarm identifier
        schema:
          type: string
      responses:
        '200':
          description: alarm deletion result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBody'
  /alarms/close:
    put:
      tags:
      - Alarms
      operationId: putAlarmsClose
      summary: Closes an alarm.
      description: Closes an alarm.
      x-access-right: IDENTIFIED_USER_ACCESS
      parameters:
      - in: query
        name: alarmId
        required: true
        description: target alarm identifier
        schema:
          type: string
      responses:
        '200':
          description: alarm close result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseBody'
  /bacnet/settings:
    get:
      tags:
      - BACnet
      operationId: getBacnetSettings
      summary: Returns the current BACnet server settings.
      description: 'Returns the current BACnet server settings.


        - these settings affect the Hub''s BACnet server functionality only - BACnet
        client-side discovery and pairing are not configured through this object -
        `bacnetEnabled` reflects whether BACnet server functionality is enabled'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
    post:
      tags:
      - BACnet
      operationId: postBacnetSettings
      summary: Saves BACnet server settings.
      description: Saves BACnet server settings.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: boolean
        description: 'BACnet settings object Validation rules: `deviceId` must be
          an integer in the valid BACnet device-id range used by the implementation
          `deviceName` must be a non-empty string `port` must be an integer greater
          than or equal to `1025` `broadcast` must be boolean when provided'
      responses:
        '200':
          description: '`true` on success'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/True'
  /bacnet/defaultsettings:
    post:
      tags:
      - BACnet
      operationId: postBacnetDefaultsettings
      summary: Restores default BACnet settings.
      description: 'Restores default BACnet settings.


        - resets `port` to `47808` - resets `broadcast` to `true` - regenerates the
        Hub BACnet `deviceId` and `deviceName` from the Hub identity'
      responses:
        '200':
          description: '`true` on success'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/True'
  /bacnet/localdevicetypes:
    get:
      tags:
      - BACnet
      operationId: getBacnetLocaldevicetypes
      summary: Returns the available local BACnet device types.
      description: Returns the available local BACnet device types.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /bacnet/objecttypes:
    get:
      tags:
      - BACnet
      operationId: getBacnetObjecttypes
      summary: Returns the available BACnet object types.
      description: Returns the available BACnet object types.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /bacnet/device:
    post:
      tags:
      - BACnet
      operationId: postBacnetDevice
      summary: Creates a local BACnet device or object.
      description: 'Creates a local BACnet device or object.


        - this endpoint requires BACnet pairing to be active - this endpoint requires
        BACnet server functionality to be enabled - the request model contains `objectId`
        and `objectName`, but they are currently not used by the implementation'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestBody'
        description: local BACnet device creation request
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /bacnet/scan:
    post:
      tags:
      - BACnet
      operationId: postBacnetScan
      summary: Scans BACnet devices.
      description: Scans BACnet devices.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestBody'
        description: BACnet scan request
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /bacnet/devices:
    get:
      tags:
      - BACnet
      operationId: getBacnetDevices
      summary: Returns available BACnet devices discovered by scanning.
      description: Returns available BACnet devices discovered by scanning.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /bacnet/pair:
    post:
      tags:
      - BACnet
      operationId: postBacnetPair
      summary: Pairs a BACnet object into the Hub.
      description: 'Pairs a BACnet object into the Hub.


        - this endpoint is intended to be used while BACnet pairing is active'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestBody'
        description: BACnet pairing request
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
  /log:
    get:
      tags:
      - Log
      operationId: getLog
      summary: Streams the local `hub.log` file over HTTP under the versioned API
        prefix.
      description: 'Streams the local `hub.log` file over HTTP under the versioned
        API prefix.


        - this endpoint is available only when the `LOG_SERVICE` Hub feature is enabled
        - on the local network, the endpoint is anonymously accessible when the feature
        is enabled - the response is a streaming text response - if the logging feature
        is disabled, the endpoint returns `403`'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericObject'
components:
  securitySchemes:
    AuthorizationToken:
      type: apiKey
      in: header
      name: Authorization
      description: Raw HubKey token. No `Bearer` prefix is used.
  schemas:
    GenericObject:
      type: object
      description: Fallback object schema generated from markdown.
      additionalProperties: true
    ResponseBody:
      type: object
      description: Hub metadata object
      additionalProperties: true
    RequestBody:
      type: object
      description: Zigbee network settings object
      additionalProperties: true
    SetScanResult:
      type: object
      description: '`SetScanResult` object containing the discovered device id and
        the desired `ignored` value'
      additionalProperties: true
    GETHubSerialports:
      type: object
      description: serial configuration object The request should be based on an object
        previously returned by `GET /hub/serialports`. Clients should keep the returned
        `controllerType` and send `settings` using only values allowed for that specific
        controller. Do not hardcode protocol-specific defaults from the documentation
        examples.
      additionalProperties: true
    BaseDevice:
      type: object
      description: concrete `BaseDevice` object
      additionalProperties: true
    AutoConfiguration:
      type: object
      description: '`AutoConfiguration` object, documented in [11.1 Autoconfiguration
        data](#111-autoconfiguration-data)'
      additionalProperties: true
    'True':
      type: object
      description: '`true` on success, otherwise an error'
      additionalProperties: true