REST API

This is an attempt to create a description for REST API used in Valetudo RE.

Note that it MAY and probably WILL change over time WITHOUT further notice.

Currently this list matches RE release 0.10.8.

Route	Method	Parameters	Description
/api/map/latest	GET		Gets latest unmodified map data in binary format as it comes from the device firmware
/api/miio/map_slot_slotID	GET		Gets the unmodified map data from slot number slotID in binary format as it comes from the device firmware
/api/simple_map	GET	slot (int) scale (int) drawPath (bool) useGradient (bool)	Draws a map from latest available map data or from specified slot. You may also optinally choose to scale the image, disable drawPath or 'useGradient' to make it a bit quicker, since such renders take quiet a lot of time here
/api/get_mapdata	GET	slot (int) pixels (bool)	Return parsed map data. If slot is specified, it will return map data from that exact slot, otherwise it will use the latest available map data. If pixels are set to any true value, map data will contain all pixel data in image section, otherwise it will respond with all basic data not including distinct pixels.
/api/poll_map	GET		This just tries to request a new map data if you somehow feel the current one is outdated
/api/current_status	GET		The number one debug tool, it returns the results of get_status miio command in json format
/api/device_features	GET		Returns detected features of the device, required for Web UI to decide which functionality to show
/api/consumable_status	GET		Returns status of consumable timers, which expire over time spent in cleaning states
/api/reset_consumable	PUT	consumable (string)	Resets the specified consumable timer, which could be one of main_brush_work_time, side_brush_work_time, filter_work_time or sensor_dirty_time
/api/interface_config	GET		Returns webInterface section of valetudo configuration
	PUT	localization (string) style (string) zonedImmediate (bool) gotoImmediate (bool) showMultimap (bool) hideMapStatus (bool) staticMapButtons (bool) hideSegmentMarkers (bool) hideControlMap (bool)	Sets webInterface section of valetudo configuration, where localization is 2-char code from supported languages, style one of dark, system or unset aka default, and other options are more or less self-explanatory booleans
/api/telegram_config	GET		Returns telegramBot section of valetudo configuration
	PUT	enabled (bool) token (string) password, host, proxy (strings) clients (array of objects) sendConsumables (bool) sendConsumablesEvery (int) notifyStatusTypes (0, 1 or 2)	Sets telegramBot section of valetudo configuration
/api/telegram_status	GET		Returns {running: status} of telegram bot, where status equal to 1 is disconnected, 2 is error and botname is currently online bot name
/api/telegram_client/clientID	DELETE		Deletes the authorized client with the specified clientID
/api/mqtt_config	GET		Returns mqtt section of valetudo configuration
	PUT	enabled (bool) broker_url (string) caPath, identifier (string or empty) topicPrefix, autoconfPrefix (string) qos (int) provideMapData (bool)	Sets mqtt section of valetudo configuration
/api/token	GET		Returns current device token
/api/get_fw_version	GET		Returns firmware version information in json, i.e. {"version":"miio-client 3.3.9", "build":"002020", "nodejs":"v12.18.2", "valetudo":"v0.10.0"}
/api/get_app_locale	GET		Returns quiet useless firmware app_locale information
/api/wifi_status	GET		Returns firmware wifi information in json, i.e. {"connected":true, "connection_info":{"bssid":"00:00:00:00:00:00", "ssid":"Wifi Spot", "freq":"2412", "signal":"-69 dBm", "tx_bitrate":"72.2 MBit/s"}}
/api/valetudo_log	GET		Returns last 50 lines from /var/log/upstart/valetudo.log file
/api/timers	GET		Returns current configuration of cleaning timers in firmware
	PUT	id (string) cron (crontab-like string) coordinates (array of array of ints) fanpower (int) edit (string)	Adds a zoned cleaning timer. If edit parameter is specified, it will try to overwrite a timer with the specified name or add a new one if no matches would be found
/api/ztimers/timerID	PUT	enabled (bool)	Toggles on/off the zoned cleaning timer with the specified timerID
	DELETE		Deletes the zoned cleaning timer with the specified timerID
/api/timers	GET		Returns current configuration of valetudo zoned cleaning timers
	PUT	id (string) cron (crontab-like string) segments (comma-separated string) fanpower (int) iterations (int) edit (string)	Adds a cleaning timer. If edit parameter is specified, it will try to overwrite a timer with the specified name or add a new one if no matches would be found. Segments should be specified with their respective digital codes and are supported only on gen2 fw 2008+, segments should be an empty string for gen1 devices or when you want to schedule the full cleaning.
/api/timers/timerID	PUT	enabled (bool)	Toggles on/off the cleaning timer with the specified timerID
	DELETE		Deletes the cleaning timer with the specified timerID
/api/dnd	GET		Returns current settings of Do-Not-Disturb timer (if set)
	PUT	start_hour (int) start_minute (int) end_hour (int) end_minute (int)	Adds or edits Do-Not-Disturb timer
	DELETE		Removes Do-Not-Disturb timer
/api/timezone_list	GET		Returns the list of available timezones on the device that can be used in timezone settings
/api/timezone	GET		Returns currently set timezone from firmware
	PUT	new_zone (string)	Sets specified timezone in firmware, new_zone must exist in device timezone list
/api/clean_summary	GET		Returns overall counter of cleaning time and an array of IDs of latest 20 cleanings
/api/clean_record	PUT	recordId (int)	Returns all available information of the cleaning with recordId ID
/api/clean_record_map	PUT	recordId (int)	Returns a map slot containing the map of the cleaning with recordId ID (or "retry" when it's not ready)
/api/start_cleaning	PUT		Starts a full cleaning or resumes a paused cleaning of any type
/api/start_cleaning_only	PUT		Starts or resumes a full cleaning
/api/pause_cleaning	PUT		Pauses cleaning or moving-to-dock phase, also cancels moving-to-point or spot cleaning
/api/stop_cleaning	PUT		Stops cleaning and some other phases. Depending on firmware version, may require to use pause before
/api/set_lab_status	PUT	lab_status (bool)	Toggles map saving functionality, in some newer Gen3 devices this can't be turned off
/api/reset_map	PUT		Resets current map with corresponding forbidden zones and cleaning timers (though configured zoned cleaning timers will survive)
/api/store_map	PUT	name (string)	Saves current map with corresponding zones and timers as name in valetudo local map archive
/api/load_map	PUT	name (string)	Loads map name with corresponding zones and timers from valetudo local map archive
/api/remove_map	PUT	name (string)	Removes map name with corresponding zones and timers from valetudo local map archive
/api/list_maps	GET		List names of the maps stored in valetudo local map archive
/api/go_to	PUT	x (int) y (int)	Make device move to a point with coordinates (x,y)
/api/start_cleaning_zone	PUT	array of arrays of ints	Starts zoned cleaning specified with [zone1,zone2,...] where each zone is [x1,y1,x2,y2,iterations]
/api/start_cleaning_zone_by_name	PUT	array of strings	Starts zoned cleaning with specified pre-saved zone names list
/api/zones	GET		Returns pre-saved zoned list
	PUT	name (string) coordinates (array of arrays of ints) edit (string)	Saves a zone with specified name and a set of coordinates like [zone1,zone2,...] where each zone is [x1,y1,x2,y2,iterations]. If edit is set, it designates the name of the zone to overwrite with the new data.
/api/zones/zoneID	DELETE		Removes the zone with the name zoneID
/api/spots	GET		Returns pre-saved spots list
	PUT	name (string) coordinates (array of ints) edit (string)	Saves a spot with specified name and a set of coordinates like [x,y]. If edit is set, it designates the name of the spot to overwrite with the new data.
/api/spot/spotID	DELETE		Removes the spot with the name spotID
/api/start_cleaning_segment	PUT	complex array of ints	Starts rooms cleaning, where array is [[id1, id2, ...], iterations, clean_order_mode] and id is a digital id code of a room, iterations defined the number of repeats, clean_order_mode equal to 1 means to follow specified rooms order
/api/segment_names	GET		Returns the correlation between digital id codes of rooms with their user-defined text names
	PUT	array of arrays	Sets the correlation between digital id codes of rooms with their respective names, where array is [[id1,'name 1'], [id2,'name 2'], ...] and idN is room id code and name N is a textual name for that room. Names should be no more than 23 latin characters each (regional symbols may take more than one char)
/api/merge_segment	PUT	array of ints	Merges two rooms, digital ids of which is specified in array. Merging not adjacent rooms is possible but not recommended
/api/split_segment	PUT	array of ints	Splits a room, using [id,], where id is room id code and (x1,y1) defined the beginning of a fictious line, splitting the room, and (x2,y2) the end of it. Those points should be within pixels of the room to be split
/api/autosplit_segments	PUT		Tried to automatically split a map into rooms by some random algorithm only manufacturer knows about. Doesn't work when there are already rooms created.
/api/http_auth_config	GET		Returns httpAuth section of valetudo configuration
	PUT	enabled (bool) username (string) password (string)	Sets basic http authentication parameters used for accessing Web UI if enabled
/api/forbidden_markers	GET		Returns forbidden zones and virtual walls previously saved into valetudo configuration
	PUT	virtual_walls (array of array of ints) forbidden_zones (array of array of ints) forbidden_mop_zones (array of array of ints)	Saves specified forbidden zones and virtual walls into valetudo configuration for backup purposes. Each virtual wall has two (x,y) points defining respectively start and end of the wall. Each zone has four (x,y) points, defining each its corner.
/api/persistent_data	PUT	virtual_walls (array of array of ints) forbidden_zones (array of array of ints) forbidden_mop_zones (array of array of ints)	Saves specified forbidden zones and virtual walls into firmware to be actually used in device navigation. No-Mop-Zones are supported only on selected Gen3 devices.
/api/reboot_device	PUT		Asks the device to reboot itself
/api/fanspeed	PUT	speed (int)	Sets fan speed of the device. Can be any number from 0 to 100 (like percents) on older firmware or numbers from 101 to 105 (distinct values) for newer firmware, having 105 as a special case for mop mode
/api/sound_volume	GET		Returns current sound volume set
	PUT	volume (int)	Sets sound volume from 0 to 100
/api/test_sound_volume	PUT		Allows to check current sound volume of the device
/api/ssh_keys	GET		Returns ssh keys authorized for logging into the device
	PUT	keys (string)	Sets specified string as authorized keys for logging into the device
/api/ssh_keys_permanently_disable	PUT	confirmation (string)	Should this route get a request with confirmation equal to confirm, the ability to rewrite the authorized keys will be disabled
/api/wifi_configuration	PUT	ssid (string) password (string)	Sets new Wi-Fi settings for the device
/api/find_robot	PUT		Makes the device loudly cry "I'm here!" to be easily located (like you don't have the map, pff...)
/api/drive_home	PUT		Sends the device back to charging dock
/api/spot_clean	PUT		Makes the device to clean around its current location at high power
/api/start_manual_control	PUT		Starts manual control mode
/api/stop_manual_control	PUT		Stops manual control mode
/api/set_manual_control	PUT	angle (float) velocity (float) duration (int) sequenceId (int)	Controls the device manually while in the corresponding mode.
/api/auto_manual_control	PUT	angle (float) velocity (float) duration (int)	Controls the device manually, but this will automagically call start and end RC mode and autogenerate sequence ids. This can be called multiple times in a row to have a chain of RC commands to be run.
/api/carpet_mode	GET		Returns current carpet_mode parameters
	PUT	enable (bool) current_integral (int) current_low (int) current_high (int) stall_time (int)	Sets current carpet_mode parameters
/api/install_voice_pack	POST	file (file)	Tries to install a new voice pack
/api/install_voice_pack_status	GET		Returns current status of voice pack installation
/api/send_update_request	PUT	url (string) md5 (string)	Makes device to attempt firmware update installation from the specified remote url and having a md5 hash. Later valetudo versions can read md5 from a remote file too
/api/get_ota_state	GET		Returns results of miIO.get_ota_state miio command
/api/system_config	GET		Returns system section of valetudo configuration
	PUT	afterCleanDest (int or array of ints) autoDockReturn (int) autoMapRestore (string) mapRestoreType (int)	Sets system section of valetudo configuration.
/api/override_queue	PUT	gotoSpot (any value or undefined) postCleaning (0, 1 or {x,y})	Specifies what the device should do either after performing a goto or cleaning. If gotoSpot is set, the spot cleaning will be run upon arriving to target point. If postCleaning is set to 0 - device will stop after cleaning, if set to 1 - return to the base, {x,y} - go to the location at (x,y).
/api/get_config	GET		Returns complete valetudo configuration