Eric Callahan 9c550a8f9a docs: complete API documentation rework

Moonraker's external API documentation has been significantly
overhauled in an effort to improve clarity and readability.
All parameters and responses are documented with specifications.
Tables and other elements are used to make documentation more
visible and less verbose.

Spelling and other corrections have also been added.

Signed-off-by:  Eric Callahan <arksine.code@gmail.com>

2025-02-06 19:15:38 -05:00

45 KiB

Raw Blame History

Switches, Sensors, and Devices

This document covers the API for managing various devices through Moonraker. It should be noted that the endpoints here are only available when such devices are added to Moonraker's configuration.

Power Endpoints

Moonraker's power component enables switch-like device management. Various device types are supported, including GPIOs and HTTP controlled devices.

The endpoints in this section are available when one or more [power <device_name>] sections are configured in moonraker.conf.

Get Device List

GET /machine/device_power/devices

{
    "jsonrpc": "2.0",
    "method": "machine.device_power.devices",
    "id": 5646
}

/// collapse-code

{
    "devices": [
        {
            "device": "green_led",
            "status": "off",
            "locked_while_printing": true,
            "type": "gpio"
        },
        {
            "device": "printer",
            "status": "off",
            "locked_while_printing": false,
            "type": "tplink_smartplug"
        }
    ]
}

///

/// api-response-spec open: True

Field	Type	Description
`devices`	[object]	An array of Power Device Status
		objects.

Field	Type	Description
`device`	string	The configured name of the device.
`status`	string	The current state of the device.
`locked_while_printing`	bool	When set to `true` the power device status
		may not be changed when Klipper is printing.
`type`	string	The Device Type of the
		device.
{ #power-device-status-spec } Power Device Status

Device State	Description
`on`	The device is powered on.
`off`	The device is powered off.
`init`	The device is initializing.
`error`	The device encountered an error.
{ #power-state-desc } Power Device State

Device Type	Description
`gpio`	The device is controlled by a GPIO on the local machine.
`klipper_device`	The device is controlled by Klipper.
`tplink_smartplug`	The device is a TPLink Smartplug Device (aka Kasa Device.)
`tasmota`	The device is a HTTP device running Tasmota firmware.
`shelly`	The device is a Shelly branded device (V1 API).
`homeseer`	The device is a device managed by HomeSeer.
`homeassistant`	The device is a device managed by Home Assistant.
`loxonev1`	The device is a Loxone V1 device.
`rf`	The device is a RF device with a GPIO interface.
`mqtt`	The device is a device available over MQTT.
`smartthings`	The device is a Samsung SmartThings device.
`hue`	The device is a Phillips Hue device.
`http`	The device is a generic HTTP device.
`uhubctl`	The device is a USB port with a controller compatible with
	`uhubctl`.
{ #power-type-desc } Device Type

//// Note It is possible for unofficial 3rd party extensions to register their own Device Types and implementations. //// ///

Get Device State

Requests the device state for a single configured device.

GET /machine/device_power/device?device=green_led

{
    "jsonrpc": "2.0",
    "method": "machine.device_power.get_device",
    "params": {
        "device": "green_led"
    },
    "id": 4564
}

{
    "green_led": "off"
}

/// api-response-spec open: True

Field	Type	Description
device_name	string	The current state
		of the requested device.

///

Set Device State

Toggle, turn on, or turn off a specified device.

POST /machine/device_power/device
Content-Type: application/json

{
    "device": "green_led",
    "action": "on"
}

{
    "jsonrpc": "2.0",
    "method": "machine.device_power.post_device",
    "params": {
        "device": "green_led",
        "action": "on"
    },
    "id": 4564
}

/// api-parameters open: True

Name	Type	Default	Description
`device`	string	REQUIRED	The name of the device to manage.
`action`	string	REQUIRED	The action
			to perform on the device.

Action	Description
`on`	Turns the device on.
`off`	Turns the device off.
`toggle`	Toggles device state.
{ #power-device-action-desc } Power Device Action

///

{
    "green_led": "off"
}

/// api-response-spec open: True

Field	Type	Description
device_name	string	The current state
		of the requested device.

///

Get Batch Device Status

Get power status for the requested devices. At least one device must be specified.

GET /machine/device_power/status?dev_one&dev_two

{
    "jsonrpc": "2.0",
    "method": "machine.device_power.status",
    "params": {
        "dev_one": null,
        "dev_two": null
    },
    "id": 4564
}

/// api-parameters open: True

Name	Type	Default	Description
device	null	null	There may be multiple devices specified,
			where the keys the requested device names.
			Values should always be `null`.

//// Note The strangeness of this parameter specification is an artifact from an early attempt to simplify the query string and maintain compatibility with JSON parameters. ////

///

{
    "green_led": "off",
    "printer": "off"
}

/// api-response-spec open: True

Field	Type	Description
device_name	string	The current state
		of the requested device.

///

Batch Power On Devices

Power on the requested devices. At least one device must be specified.

POST /machine/device_power/on
Content-Type: application/json

{
    "dev_one": null,
    "dev_two": null
}

{
    "jsonrpc": "2.0",
    "method": "machine.device_power.on",
    "params": {
        "dev_one": null,
        "dev_two": null
    },
    "id": 4564
}

/// api-parameters open: True

Name	Type	Default	Description
device	null	null	There may be multiple devices specified,
			where the keys the requested device names.
			Values should always be `null`.

//// Note The strangeness of this parameter specification is an artifact from an early attempt to simplify query string parameters and maintain compatibility with JSON parameters. ////

///

{
    "green_led": "on",
    "printer": "on"
}

/// api-response-spec open: True

Field	Type	Description
device_name	string	The current state
		of the requested device. The field name
		of the response is the device's configured
		name. The response may contain multiple devices.

///

Batch Power Off Devices

Power off the requested devices. At least one device must be specified.

POST /machine/device_power/off?dev_one&dev_two

{
    "jsonrpc": "2.0",
    "method": "machine.device_power.off",
    "params": {
        "dev_one": null,
        "dev_two": null
    },
    "id": 4564
}

/// api-parameters open: True

Name	Type	Default	Description
device	null	null	There may be multiple devices specified,
			where the keys the requested device names.
			Values should always be `null`.

//// Note The strangeness of this parameter specification is an artifact from an early attempt to simplify query string parameters and maintain compatibility with JSON parameters. ////

///

{
    "green_led": "off",
    "printer": "off"
}

/// api-response-spec open: True

Field	Type	Description
device_name	string	The current state
		of the requested device. The field name
		of the response is the device's configured
		name. The response may contain multiple devices.

///

WLED Endpoints

The wled component can be used to perform high level management of devices running WLED firmware.

The endpoints in this section are available when one or more [wled <dev_name>] sections are configured in moonraker.conf.

For lower-level control of wled consider using the WLED JSON API directly.

Get strips

GET /machine/wled/strips

{
    "jsonrpc": "2.0",
    "method": "machine.wled.strips",
    "id": 7123
}

/// collapse-code

{
    "strips": {
        "lights": {
            "strip": "lights",
            "status": "on",
            "chain_count": 79,
            "preset": -1,
            "brightness": 255,
            "intensity": -1,
            "speed": -1,
            "error": null
        },
        "desk": {
            "strip": "desk",
            "status": "on",
            "chain_count": 60,
            "preset": 8,
            "brightness": -1,
            "intensity": -1,
            "speed": -1,
            "error": null
        }
    }
}

///

/// api-response-spec open: True

Field	Type	Description
`strips`	object	A container of WLED Strip Status
		objects. The keys in this object will be the name of strip
		with the values containing strip status.

Field	Type	Description
`strip`	string	The configured name of the strip.
`status`	string	The current state of the WLED strip. Will
		be `on` if the strip is enabled or `off`
		if the strip is disabled.
`chain_count`	int	The number of LEDs configured on the chain.
`preset`	int	The numbered preset. Will be -1 if no
		preset is selected.
`brightness`	int	The brightness value set by Moonraker. Will
		be -1 if Moonraker has not set this value.
`intensity`	int	The intensity value set by Moonraker. Will
		be -1 if Moonraker has not set this value.
`speed`	int	The speed value set by Moonraker. Will
		be -1 if Moonraker has not set this value.
`error`	string \| null	A message describing last error returned
		from an attempted WLED command. Will be
		`null` if no error is returned.
{ #wled-strip-status-spec } WLED Strip Status

///

Get strip status

GET /machine/wled/status?strip1&strip2

{
    "jsonrpc": "2.0",
    "method": "machine.wled.status",
    "params": {
        "lights": null,
        "desk": null
    },
    "id": 7124
}

/// api-parameters open: True

Name	Type	Default	Description
strip	null	null	There may be multiple strips specified,
			where the keys the requested strip names.
			Values should always be `null`.

///

/// collapse-code

{
    "lights": {
        "strip": "lights",
        "status": "on",
        "chain_count": 79,
        "preset": -1,
        "brightness": 255,
        "intensity": -1,
        "speed": -1,
        "error": null
    },
    "desk": {
        "strip": "desk",
        "status": "on",
        "chain_count": 60,
        "preset": 8,
        "brightness": -1,
        "intensity": -1,
        "speed": -1,
        "error": null
    }
}

///

/// api-response-spec open: True

Field	Type	Description
strip	object	There may be multiple `strips`, where the
		keys are strip names and the values are
		WLED strip status
		objects.

///

Turn strip on

Turns the specified strips on to the initial colors or initial preset.

POST /machine/wled/on
Content-Type: application/json

{
    "lights": null,
    "desk": null
}

{
    "jsonrpc": "2.0",
    "method": "machine.wled.on",
    "params": {
        "lights": null,
        "desk": null
    },
    "id": 7125
}

/// collapse-code

{
    "lights": {
        "strip": "lights",
        "status": "on",
        "chain_count": 79,
        "preset": -1,
        "brightness": 255,
        "intensity": -1,
        "speed": -1,
        "error": null
    },
    "desk": {
        "strip": "desk",
        "status": "on",
        "chain_count": 60,
        "preset": 8,
        "brightness": -1,
        "intensity": -1,
        "speed": -1,
        "error": null
    }
}

///

/// api-response-spec open: True

Field	Type	Description
strip	object	There may be multiple `strips`, where the
		keys are strip names and the values are
		WLED strip status
		objects.

///

Turn strip off

Turns off all specified strips.

POST /machine/wled/off
Content-Type: application/json

{
    "lights": null,
    "desk": null
}

{
    "jsonrpc": "2.0",
    "method": "machine.wled.off",
    "params": {
        "lights": null,
        "desk": null
    },
    "id": 7126
}

/// api-parameters open: True

Name	Type	Default	Description
strip	null	null	There may be multiple strips specified,
			where the keys the requested strip names.
			Values should always be `null`.

///

/// collapse-code

{
    "lights": {
        "strip": "lights",
        "status": "off",
        "chain_count": 79,
        "preset": -1,
        "brightness": 255,
        "intensity": -1,
        "speed": -1,
        "error": null
    },
    "desk": {
        "strip": "desk",
        "status": "off",
        "chain_count": 60,
        "preset": 8,
        "brightness": -1,
        "intensity": -1,
        "speed": -1,
        "error": null
    }
}

///

/// api-response-spec open: True

Field	Type	Description
strip	object	There may be multiple `strips`, where the
		keys are strip names and the values are
		WLED strip status
		objects.

///

Toggle strip on/off state

Toggles the current enabled state for the requested strips.

POST /machine/wled/toggle
Content-Type: application/json

{
    "lights": null,
    "desk": null
}

{
    "jsonrpc": "2.0",
    "method": "machine.wled.toggle",
    "params": {
        "lights": null,
        "desk": null
    },
    "id": 7127
}

/// api-parameters open: True

Name	Type	Default	Description
strip	null	null	There may be multiple strips specified,
			where the keys the requested strip names.
			Values should always be `null`.

///

/// collapse-code

{
    "lights": {
        "strip": "lights",
        "status": "on",
        "chain_count": 79,
        "preset": -1,
        "brightness": 255,
        "intensity": -1,
        "speed": -1,
        "error": null
    },
    "desk": {
        "strip": "desk",
        "status": "off",
        "chain_count": 60,
        "preset": 8,
        "brightness": -1,
        "intensity": -1,
        "speed": -1,
        "error": null
    }
}

///

/// api-response-spec open: True

Field	Type	Description
strip	object	There may be multiple `strips`, where the
		keys are strip names and the values are
		WLED strip status
		objects.

///

Get individual strip state

GET /machine/wled/strip?strip=lights

{
    "jsonrpc": "2.0",
    "method": "machine.wled.get_strip",
    "params": {
        "strip": "lights"
    }
    "id": 7128
}

/// collapse-code

{
    "lights": {
        "strip": "lights",
        "status": "on",
        "chain_count": 79,
        "preset": 1,
        "brightness": 50,
        "intensity": 255,
        "speed": 255,
        "error": null
    }
}

///

/// api-response-spec open: True

Field	Type	Description
strip	object	An object containing the requested strip's current
		status. The key is the strip's name, the value is
		an WLED strip status
		object.

///

Control individual strip state

Toggle, turn on, turn off, turn on with preset, turn on with brightness, or turn on preset will some of brightness, intensity, and speed. Or simply set some of brightness, intensity, and speed.

POST /machine/wled/strip
Content-Type: application/json

{
    "strip": "lights",
    "action" "on",
    "preset": 3,
    "brightness": 200,
    "intensity": 50,
    "speed": 180
}

{
    "jsonrpc": "2.0",
    "method": "machine.wled.post_strip",
    "params": {
        "strip": "lights",
        "action" "on",
        "preset": 3,
        "brightness": 200,
        "intensity": 50,
        "speed": 180
    },
    "id": 7128
}

/// api-parameters open: True

Name	Type	Default	Description
`strip`	string	REQUIRED	The name of the strip to control.
`action`	string	REQUIRED	The WLED Action to
			execute on the strip.
`preset`	int	INITIAL_VAL	The numbered preset stored on the WLED
			controller. The `preset` is only applied when
			a strip is enabled, either through the `on` or
			`toggle` actions.
`brightness`	int	CURRENT_VAL	Changes the `brightness` of the LEDs on the
			strip. The permitted range is 1-255.
`intensity`	int	CURRENT_VAL	Changes the `intensity` value of the current
			preset. The permitted range is 0-255. This
			setting is ignored if no preset is active.
`speed`	int	CURRENT_VAL	Changes the `speed` value of the current
			preset. The permitted range is 0-255. This
			setting is ignored if no preset is active.

Action	Description
`on`	Enable the strip. The `on` action may be accompanied
	by one or more of the `preset`, `brightness`, `intensity`
	or `speed` parameters, which will be applied immediately.
`off`	Disable the strip.
`toggle`	Toggle the strip's enabled state.
`control`	Modify `brightness`, `intensity`, and/or `speed` without
	changing the current enabled state. At least one of the
	these parameters must be provided when the action is
	`control`.
{ #wled-action-desc } WLED Action

//// Note When a strip is enabled the brightness, intensity, and speed values will be reset to the preset's default values. ////

///

/// collapse-code

{
    "lights": {
        "strip": "lights",
        "status": "on",
        "chain_count": 79,
        "preset": 1,
        "brightness": 50,
        "intensity": 255,
        "speed": 255,
        "error": null
    }
}

///

/// api-response-spec open: True

Field	Type	Description
strip	object	An object containing the requested strip's current
		status. The key is the strip's name, the value is
		an WLED strip status
		object.

///

Sensor endpoints

The endpoints in this section are available when at least one [sensor <sensor_name>] section has been configured in moonraker.conf.

Get Sensor List

GET /server/sensors/list?extended=False

{
    "jsonrpc": "2.0",
    "method": "server.sensors.list",
    "params": {
        "extended": false
    }
    "id": 5646
}

/// api-parameters open: True

Name	Type	Default	Description
`extended`	bool	false	When set to `true` the status for each
			sensor will include `parameter_info` and
			`history_fields` fields.

///

/// collapse-code

{
    "sensors": {
        "sensor1": {
            "id": "sensor1",
            "friendly_name": "Sensor 1",
            "type": "mqtt",
            "values": {
                "value1": 0,
                "value2": 119.8
            },
            "parameter_info": [
                {
                    "units": "kWh",
                    "name": "value1"
                },
                {
                    "units": "V",
                    "name": "value2"
                }
            ],
            "history_fields": [
                {
                    "field": "power_consumption",
                    "provider": "sensor sensor1",
                    "description": "Printer Power Consumption",
                    "strategy": "delta",
                    "units": "kWh",
                    "init_tracker": true,
                    "exclude_paused": false,
                    "report_total": true,
                    "report_maximum": true,
                    "precision": 6,
                    "parameter": "value1"
                },
                {
                    "field": "max_voltage",
                    "provider": "sensor sensor1",
                    "description": "Maximum voltage",
                    "strategy": "maximum",
                    "units": "V",
                    "init_tracker": true,
                    "exclude_paused": false,
                    "report_total": false,
                    "report_maximum": false,
                    "precision": 6,
                    "parameter": "value2"
                }
            ]
        }
    }
}

///

/// api-response-spec open: True

Field	Type	Description
`sensors`	object	An object containing the sensor status.
		Each key will be the sensor's ID, each
		value will be a
		sensor status object.

Field	Type	Description
`id`	string	The sensor's configured ID.
`friendly_name`	string	The sensor's configured friendly name.
`type`	string	The sensor's configured type. Currently
		only `mqtt` types are supported.
`values`	object	A `Sensor Values` object reporting the
		most recent values measured by the sensor.
		#sensor-values-spec
`parameter_info`	[object]	An array of `Parameter Info` objects. Only
		included with `extended` responses.
`history_fields`	[object]	An array of `History Field` objects. Only
		reported with `extended` responses. Will
		be an empty list if no history fields are
		configured for the sensor.
{ #sensor-status-spec } Sensor Status

Field	Type	Description
value_name	any	The object may contain multiple `values`, where
		each key is the name of a parameter tracked
		by the sensor, and the value is the most
		recent reported measurement.
{ #sensor-values-spec } Sensor Values

Field	Type	Description
`name`	string	The name of a parameter measured by the sensor.
custom	string	The `parameter_info` object may contain additional
		custom fields provided in the sensor's configuration.
		It is common for a sensor to add a `units` field
		specifying the type of data measured by the sensor.
{ #sensor-parameter-info-spec } Parameter Info

Field	Type	Description
`field`	string	The name of the auxiliary field to be stored in
		the job history.
`provider`	string	The object providing data for history
		tracking. Will be the sensor's config
		section name, ie: `sensor my_sensor`.
`description`	string	A brief description of the measurement.
`strategy`	string	The strategy used to
		track data stored in the job history.
`units`	string \| null	The units, if applicable, for the value stored
		in history.
`init_tracker`	bool	When `true` the first value tracked will be
		initialized to the most recent sensor measurement.
`exclude_paused`	bool	When `true` tracking will exclude measurements
		taken while a job is paused.
`report_total`	bool	When `true` the final tracked value will be
		accumulated and included in the `history`
		component's job totals.
`report_maximum`	bool	When `true` the maximum final tracked value during a
		job will be included in the `history` component's
		job totals.
`precision`	int	The precision of the final tracked value, presuming
		it is a float.
`parameter`	string	The `name` of the sensor parameter to track.
{ #sensor-history-field-spec } History Fields

Strategy	Description
`basic`	Stores the last value measured during a job.
`delta`	Stores the difference between the last and first values
	measured during a job.
`accumulate`	Stores the cumulative value of all measurements reported
	during the job.
`average`	Stores an average of all measurements taken during the
	job.
`maximum`	Stores the maximum value measured during the job.
`minimum`	Stores the minimum value measured during the job.
`collect`	Stores all values measured during the job in an array.
{ #sensor-history-strategy } History Tracking Strategy

///

Get Sensor Information

Returns the status for a single configured sensor.

GET /server/sensors/info?sensor=sensor1&extended=false

{
    "jsonrpc": "2.0",
    "method": "server.sensors.info",
    "params": {
        "sensor": "sensor1",
        "extended": false
    },
    "id": 4564
}

/// api-parameters open: True

Name	Type	Default	Description
`sensor`	string	REQUIRED	The ID of the requested sensor.
`extended`	bool	false	When set to `true` the status for the
			sensor will include `parameter_info` and
			`history_fields` fields.

///

/// collapse-code

{
    "id": "sensor1",
    "friendly_name": "Sensor 1",
    "type": "mqtt",
    "values": {
        "value1": 0.0,
        "value2": 120.0
    },
    "parameter_info": [
        {
            "units": "kWh",
            "name": "value1"
        },
        {
            "units": "V",
            "name": "value2"
        }
    ],
    "history_fields": [
        {
            "field": "power_consumption",
            "provider": "sensor sensor1",
            "description": "Printer Power Consumption",
            "strategy": "delta",
            "units": "kWh",
            "init_tracker": true,
            "exclude_paused": false,
            "report_total": true,
            "report_maximum": true,
            "precision": 6,
            "parameter": "value1"
        },
        {
            "field": "max_voltage",
            "provider": "sensor sensor1",
            "description": "Maximum voltage",
            "strategy": "maximum",
            "units": "V",
            "init_tracker": true,
            "exclude_paused": false,
            "report_total": false,
            "report_maximum": false,
            "precision": 6,
            "parameter": "value2"
        }
    ]
}

///

/// api-response-spec open: True

The response specification is a Sensor Status object.

///

Get Sensor Measurements

Returns all recorded measurements for a configured sensor.

GET /server/sensors/measurements?sensor=sensor1

{
    "jsonrpc": "2.0",
    "method": "server.sensors.measurements",
    "params": {
        "sensor": "sensor1"
    },
    "id": 4564
}

/// api-parameters open: True

Name	Type	Default	Description
`sensor`	string	REQUIRED	The ID of the requested sensor.

///

/// collapse-code

{
    "sensor1": {
        "value1": [
            3.1,
            3.2,
            3.0
        ],
        "value2": [
            120.0,
            120.0,
            119.9
        ]
    }
}

///

/// api-response-spec open: True

Field	Type	Description
sensor_id	object	A Sensor Measurements
		object. The key for this item will be the sensor
		id.

Field	Type	Description
param_name	[float \| int]	An array of decimal numbers containing all
		stored measurements for the named parameter.
		There may be multiple items in this
		object, where they keys are parameter names.
{ #sensor-measurements-spec } Sensor Measurements

///

Get Batch Sensor Measurements

Returns recorded measurements for all sensors.

GET /server/sensors/measurements

{
    "jsonrpc": "2.0",
    "method": "server.sensors.measurements",
    "id": 4564
}

/// collapse-code

{
    "sensor1": {
        "value1": [
            3.1,
            3.2,
            3.0
        ],
        "value2": [
            120.0,
            120.0,
            119.9
        ]
    },
    "sensor2": {
        "value_a": [
            1,
            1,
            0
        ]
    }
}

///

/// api-response-spec open: True

Field	Type	Description
sensor_id	object	A Sensor Measurements
		object. There may be multiple sensor items, where
		the keys are sensor IDs.

///

MQTT Endpoints

Moonraker supports mqtt connections for communicating with other devices on the network. In addition to the power and sensor implementations Moonraker provides endpoints for clients to publish and subscribe to topics on the network. These endpoints are available when [mqtt] has been configured in moonraker.conf.

/// Note These endpoints are not available over the mqtt transport as they are redundant. MQTT clients can publish and subscribe to topics directly. ///

Publish a topic

POST /server/mqtt/publish
Content-Type: application/json

{
    "topic": "home/test/pub",
    "payload": "hello",
    "qos": 0,
    "retain": false,
    "timeout": 5
}

{
    "jsonrpc": "2.0",
    "method": "server.mqtt.publish",
    "params":{
        "topic": "home/test/pub",
        "payload": "hello",
        "qos": 0,
        "retain": false,
        "timeout": 5
    },
    "id": 4564
}

/// api-parameters open: True

Name	Type	Default	Description
`topic`	string	REQUIRED	The topic to publish to the network.
`payload`	any	null	The payload to send with the topic.
			May be a boolean, float, integer,
			object, or array. Objects and Arrays
			are JSON encoded. When this parameter
			is omitted an empty payload is sent.
`qos`	int	CONFIG_DEFAULT	The QOS level to use when publishing a
			topic. Valid range is 0-2.
`retain`	bool	false	When set to `true` the topic's retain
			flag is set.
`timeout`	float	null	A timeout, in seconds, in which
			Moonraker will wait for acknowledgement
			from the broker. If the timeout is
			exceeded the request will return with a
			504 error. Only applies to QOS levels 1
			2. When omitted the request will wait
			indefinitely.

//// tip The retain flag tells the broker to save, or "retain", the payload associated with the topic. Only the most recent payload published to the topic is retained. Subsequent subscribers to the topic will immediately receive the retained payload.

To clear a retained value of a topic, publish the topic with an empty payload and retain set to true. ////

///

{
    "topic": "home/test/pub"
}

/// api-response-spec open: True

Field	Type	Description
`topic`	string	The topic that was successfully published.

///

POST /server/mqtt/subscribe
Content-Type: application/json

{
    "topic": "home/test/sub",
    "qos": 0,
    "timeout": 5
}

{
    "jsonrpc": "2.0",
    "method": "server.mqtt.subscribe",
    "params":{
        "topic": "home/test/sub",
        "qos": 0,
        "timeout": 5
    },
    "id": 4564
}

/// api-parameters open: True

Name	Type	Default	Description
`topic`	string	REQUIRED	The topic to subscribe to. Wildcards
			are not allowed.
`qos`	int	CONFIG_DEFAULT	The QOS level to use for the subscription.
			Valid range is 0-2.
`timeout`	float	null	A timeout, in seconds, to wait until a
			response is received. The request will
			return with a 504 error if the timeout
			is exceeded. By default the request will
			wait indefinitely.

///

/// note If the topic was previously published with a retained payload this request will return immediately with the retained value. ///

{
    "topic": "home/test/pub",
    "payload": "test"
}

/// api-response-spec open: True

Field	Type	Description
`topic`	string	The name of the topic subscribed to.
`payload`	string \| object \| array \| null	The payload received with the topic.

//// note If the payload contains a JSON value it will decoded and set as an object or array before re-encoding the full response back to JSON. Otherwise it will be a string or null if the payload is empty. ////

///

45 KiB Raw Blame History

Switches, Sensors, and Devices

Power Endpoints

Get Device List

Get Device State

Set Device State

Get Batch Device Status

Batch Power On Devices

Batch Power Off Devices

WLED Endpoints

Get strips

Get strip status

Turn strip on

Turn strip off

Toggle strip on/off state

Get individual strip state

Control individual strip state

Sensor endpoints

Get Sensor List

Get Sensor Information

Get Sensor Measurements

Get Batch Sensor Measurements

MQTT Endpoints

Publish a topic

Subscribe to a topic

45 KiB

Raw Blame History