Latest revision as of 18:02, 20 November 2024

Domoticz allows you to interact with all your switches and sensors using JSON, either interactively through a browser or programmatically from a scripting language. In fact, when you interact with the Domoticz UI through your browser by clicking on buttons and such, under the hood it's JSON that actually communicates your changes back to the Domoticz engine (Hint: You can watch this behaviour at any time by enabling developer tools in your browser and watching the network tab's traffic when you change something through the UI. See the section on changing a zwave device parameter for an example, with screenshot). This wiki describes how to use this versatile API.

Warning Stable 2023.2 (and newer)

For users using API calls from outside Domoticz there has been some changes in API calls. They now always should be of the form /json.htm?type=command&param=**command**

For example

/json.htm?type=graph will be /json.htm?type=command&param=graph

/json.htm?type=devices will be /json.htm?type=command&param=getdevices

More info in Forum topic https://www.domoticz.com/forum/viewtopic.php?p=303581#p303581

The following old RType commands will keep working but will give a deprecation warning eg

[WebServer] Deprecated RType (devices) for API request. Handled via fallback (getdevices), please use correct API Command! (IP nnn.nnn.nnn.nnn)

/json.htm?type=**old command** -> /json.htm?type=command&param=**new command**

"settings" -> "getsettings"
"users" -> "getusers";
"devices" -> "getdevices"
"hardware" -> "gethardware";
~~"events" -> "events"~~
"notifications" -> "getnotifications"
"createdevice" -> "createdevice"
"scenes" -> "getscenes";
"plans" -> "getplans"
"graph" -> "graph"
"scenelog" -> "getscenelog"
"mobiles" -> "getmobiles"
"cameras"-> "getcameras"
"cameras_user" -> "getcameras_user"
"schedules" -> "getschedules"
"timers" -> "gettimers"
"scenetimers" -> "getscenetimers"
"setpointtimers" -> "getsetpointtimers"
"plans" -> "getplans"
"floorplans" -> "getfloorplans"
"lightlog" -> "getlightlog"
"textlog" -> "gettextlog"
"setused" -> "setused"

The following old RType command has no fallback:

"/json.htm?type=events"

The updated syntax is "/json.htm?type=command&param=events&evparam=<eventsparam>"

Format

http://<username:password@>domoticz-ip<:port>/json.htm?api-call

<username:password@> = the username and password to access Domoticz, this is optional, see the Security page for details setting up login.
domoticz-ip = the IP-address or hostname of your Domoticz installation.
<:port> = the port number of your Domoticz installation, this is optional.

eg. http://192.168.1.2:8080/json.htm?type=command&param=udevice&idx=$idx&nvalue=0&svalue=79

Hint: You can have a look at the database for the nValue/sValue, or the .cpp code.

Making output more readable

By default, most browser will display the JSON-output in a unordered mess, but some (like FireFox) will recognize it is JSON and show it in a readable manner. To make it more readable you could use a browser plugin that formats the JSON to a more human-readable layout.
For Google Chrome you could use JSONView (Chrome web store). For other browsers a similar extension will probably exist. Look in the extensions/add-on store of your browser.

There are online sites which helps to do the same like https://jsonformatter.org. This site helps to format, tree view and validate JSON.

Authorization

When using some method other than a browser to connect to Domoticz it may be necessary to do Authorization differently. Authorization over HTTP is done by setting the "Authorization" HTTP request header when sending the request to Domoticz. The value of this header is a base64 encoded string of the username and password. When connecting to Domoticz using a browser and the URL method above the browser sets the appropriate header. When creating your own app or script this is not always done for you.

First the username and password are combined into one string "username:password"
This string is encoded using the RFC2045-MIME version of base64
The authorization method and a space i.e. "Basic " is then put before the encoded string.

This results in a header in the following format:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

How the header is send differs per programming language. Check the documentation of the language of your choice on how to set http request headers.

Users

When you use an user and password in this api, the user must have "user" or "admin" rights. See also page User Management
The user also must have the right to access the device (see 'Set Devices' in Edit Users page).

Base64 encode

To encode a string using base64 you could use : codebeautify.org/base64-encode

Response

All responses include a status which is either OK on success or ERR on failure

{
   "status" : "OK"
}

General usage

Please note that many characters are not permitted in URL strings, including spaces, brackets, etc. Depending on which options below you are using, it may be necessary to URL encode the string first. This is also called URI-encoding, escaping or percent-encoding. See URL encode/decode.

As an example, the string:

 This is a test ! (Really)

when properly encoded, looks like this

 This%20is%20a%20test%20%21%20%28Really%29

It's also allowable to use a '+' instead of '%20' to encode spaces (this is normally reserved for HTML forms processing but Domoticz accepts both).

A note on IDXes

There are different categories of IDX values, such as for devices, for scenes, for timers, for hardware devices, etc. Make sure that you are using the correct IDX value when trying the commands below. Device IDXes can be found by looking at the Setup --> Devices tab in the UI. Similarly, Setup --> Hardware will list the hardware category IDXes. See the section(s) on scenes and timers/schedules below to see how to retrieve their particular IDXes or timerIDs using JSON.

Retrieve status of Domoticz instance

You can get the status of a Domoticz instance with:

/json.htm?type=command&param=getversion

{
"DomoticzUpdateURL": "http://www.domoticz.com/download.php?channel=beta&type=release&system=linux&machine=armv7l",
"HaveUpdate": false,
"Revision": 9540,
"SystemName": "linux",
"UseUpdate": true,
"build_time": "2018-05-29 14:27:24",
"dzvents_version": "2.4.6",
"hash": "30295913",
"python_version": "3.5.3 (default, Jan 19 2017, 14:11:04) \n[GCC 6.3.0 20170124]",
"status": "OK",
"title": "GetVersion",
"version": "3.9530"
}

From Stable 2023.2 (7-jun-2023) when a request is done without any authorisation, only the following is returned:

{
	"status" : "OK",
	"title" : "GetVersion"
}

When requested by a (non-admin) User, it gives (which is the current default response for users):

{
	"HaveUpdate" : false,
	"UseUpdate" : false,
	"build_time" : "2023-06-04 16:08:09",
	"dzvents_version" : "3.1.8",
	"hash" : "98a7d1eef-modified",
	"python_version" : "3.8.10 (default, Nov 14 2022, 12:59:47) \n[GCC 9.4.0]",
	"status" : "OK",
	"title" : "GetVersion",
	"version" : "2023.1 (build 15331)"
}

And for admins

{
	"DomoticzUpdateURL" : "https://www.domoticz.com/download.php?channel=stable&type=release&system=linux&machine=x86_64",
	"HaveUpdate" : false,
	"Revision" : 15091,
	"SystemName" : "linux",
	"UseUpdate" : true,
	"build_time" : "2023-06-04 16:08:09",
	"dzvents_version" : "3.1.8",
	"hash" : "98a7d1eef-modified",
	"python_version" : "3.8.10 (default, Nov 14 2022, 12:59:47) \n[GCC 9.4.0]",
	"status" : "OK",
	"title" : "GetVersion",
	"version" : "2023.1 (build 15331)"
}

Get list of all defined users in the system

/json.htm?type=command&param=getusers

{
	"result": [
		{
		"Enabled": "true",
		"Password": "abcdef1234567890abcdef1234567889",
		"RemoteSharing": 1,
		"Rights": 2,
		"TabsEnabled": 127,
		"Username": "waaren",
		"idx": "2"
		},
		{
		"Enabled": "true",
		"Password": "abcdef1234567890abcdef1234567889",
		"RemoteSharing": 0,
		"Rights": 2,
		"TabsEnabled": 0,
		"Username": "IFTTTx",
		"idx": "3"
		},
	],
	"status": "OK",
	"title": "Users"
}

Get settings

/json.htm?type=command&param=getsettings

This will return the settings defined in "Setup" under a JSON form. For ex. :

{
   "AcceptNewHardware" : 0,
   "ActiveTimerPlan" : 0,
   "ClickatellEnabled" : "",
   "ClickatellFrom" : "",
   "ClickatellPassword" : "",
...
}

Retrieve Domoticz logfile information

You can get the last couple (fixed at max. 100) of logmessages with:

/json.htm?type=command&param=getlog&lastlogtime=LASTLOGTIME&loglevel=LOGLEVEL

 LOGLEVEL 1 = normal
          2 = status
          4 = error
  268435455 = all

 LASTLOGTIME  starting with logmessages in LASTLOGTIME seconds since last epoch ( 0 = all available)

{
	"LastLogTime": "1615579727",
	"result": [
		{
			"level": 4,
			"message": "2021-03-12 17:11:47.613  Error: BuienRadar: Problem Connecting to Buienradar! (Check your Internet Connection!)"
		},
		{
			"level": 4,
			"message": "2021-03-12 18:30:05.598  Error: dzVents: Error: (3.1.6) openUV: /opt/domoticz/scripts/dzVents/scripts/openUV.lua:63: attempt to index a nil value (field 'result')"
		},
		{
			"level": 4,
			"message": "2021-03-12 21:08:47.542  Error: (Evohome) status request failed with message: Timeout was reached"
		}
	],
	"status": "OK",
	"title": "GetLog"
}

Add a log message to the Domoticz log

You can add a log message to the system with:

/json.htm?type=command&param=addlogmessage&message=MESSAGE&level=LEVEL

MESSAGE = a string you want to log. Make sure to URL-encode any unsafe non-alphanumeric characters. See URL encode/decode

"LEVEL" 1 = normal // default

         2 = status
         4 = error

{
"status": "OK",
"title": "AddLogMessage"
}

Retrieve status of specific device

You can get the status of a device with:

/json.htm?type=command&param=getdevices&rid=IDX

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
or IDX = 10,20,30 (for querying a range devices, in this case devices with IDX 10, 20 and 30)

{
	"ActTime": 1613058183,
	"AstrTwilightEnd": "19:39",
	"AstrTwilightStart": "06:06",
	"CivTwilightEnd": "18:20",
	"CivTwilightStart": "07:24",
	"DayLength": "09:46",
	"NautTwilightEnd": "19:00",
	"NautTwilightStart": "06:45",
	"ServerTime": "2021-02-11 16:43:03",
	"SunAtSouth": "12:52",
	"Sunrise": "08:00",
	"Sunset": "17:45",
	"app_version": "2020.2 (build 12936)",
	"result": [
		{
			"AddjMulti": 1,
			"AddjMulti2": 1,
			"AddjValue": 0,
			"AddjValue2": 0,
			"BatteryLevel": 255,
			"CustomImage": 0,
			"Data": "On",
			"Description": "Plain text",
			"DimmerType": "none",
			"Favorite": 0,
			"HardwareDisabled": false,
			"HardwareID": 3,
			"HardwareName": "virtual",
			"HardwareType": "Dummy (Does nothing, use for virtual switches only)",
			"HardwareTypeVal": 15,
			"HaveDimmer": true,
			"HaveGroupCmd": true,
			"HaveTimeout": false,
			"ID": "00014052",
			"Image": "Light",
			"IsSubDevice": false,
			"LastUpdate": "2021-02-10 22:47:03",
			"Level": 0,
			"LevelInt": 0,
			"MaxDimLevel": 100,
			"Name": "mySwitch",
			"Notifications": "false",
			"PlanID": "0",
			"PlanIDs": [
				0
			],
			"Protected": false,
			"ShowNotifications": true,
			"SignalLevel": "-",
			"Status": "On",
			"StrParam1": "",
			"StrParam2": "",
			"SubType": "Switch",
			"SwitchType": "On/Off",
			"SwitchTypeVal": 0,
			"Timers": "false",
			"Type": "Light/Switch",
			"TypeImg": "lightbulb",
			"Unit": 1,
			"Used": 1,
			"UsedByCamera": false,
			"User": "Admin (IP: 192.168.192.41)",
			"XOffset": "0",
			"YOffset": "0",
			"idx": "2"
		}
	],
	"status": "OK",
	"title": "Devices"
}

The array result[0] contains a hash/dict with name/value pairs of settings that are relevant to the device in question, in this example a thermostat.
Please note that it will be something like json.result[1] in classic Lua and dzVents script because in Lua an array starts with 1.

Retrieve name / idx of all devices

If you are not sure of the IDX and want to do a quick lookup of name/value pairs to match a device name to its IDX, use

/json.htm?type=command&param=devices_list

which will result in something like (fragment)

		{
			"name" : "Corner Light",
			"value" : "156"
		},
		{
			"name" : "Table Light",
			"value" : "198"
		},

Get status of all devices of a certain type

/json.htm?type=command&param=getdevices&filter=all&used=true&order=Name

This will return information about all used devices. If you want to retrieve information for a specific devicetype, you can use the following filters with &filter=:

light 
weather
temp
utility
wind
rain
uv
baro
zwavealarms

{
	"ActTime": 1615581479,
	"AstrTwilightEnd": "20:34",
	"AstrTwilightStart": "05:09",
	"CivTwilightEnd": "19:15",
	"CivTwilightStart": "06:29",
	"DayLength": "11:39",
	"NautTwilightEnd": "19:54",
	"NautTwilightStart": "05:50",
	"ServerTime": "2021-03-12 21:37:59",
	"SunAtSouth": "12:52",
	"Sunrise": "07:02",
	"Sunset": "18:41",
	"app_version": "2020.2 (build 13065)",
	"result": [
		{
			 "List of all devices": 1
		}
	],
	"status": "OK",
	"title": "Devices"
}

Get status of all devices, including hidden ones

/json.htm?type=command&param=getdevices&used=true&displayhidden=1

Device names starting with a '$' sign are invisible in both the Dashboard and Switches tabs in the Domoticz UI. If you want these devices included in the json output then displayhidden must be specified.

{
	"ActTime": 1615641865,
	"AstrTwilightEnd": "20:36",
	"AstrTwilightStart": "05:07",
	"CivTwilightEnd": "19:16",
	"CivTwilightStart": "06:26",
	"DayLength": "11:43",
	"NautTwilightEnd": "19:56",
	"NautTwilightStart": "05:47",
	"ServerTime": "2021-03-13 14:24:25",
	"SunAtSouth": "12:51",
	"Sunrise": "07:00",
	"Sunset": "18:43",
	"app_version": "2020.2 (build 13065)",
	"result": [
		{
			"AddjMulti": 1,
			"AddjMulti2": 1,
			"AddjValue": 0,
			...
			"Name": "$Harmony_Mediacenter",
			"Notifications": "false",
			"PlanID": "0",
			...
			"YOffset": "0",
			"idx": "2176"
		},
	],
	"status": "OK",
	"title": "Devices"
}

Get status of all Favorite devices

/json.htm?type=command&param=getdevices&used=true&filter=all&favorite=1

This will return only devices that are tagged as Favorite.

Get server time

/json.htm?type=command&param=getServerTime

{
    "ServerTime": "2021-01-13 23:10:13",
    "status": "OK",
    "title": "getServerTime"
}

Get sunrise and sunset times

/json.htm?type=command&param=getSunRiseSet

{
   "ServerTime" : "Sep 30 2013 17:15:21",
   "Sunrise" : "07:38:00",
   "Sunset" : "19:16:00",
   "status" : "OK",
   "title" : "getSunRiseSet"
}

Use Notification Subsystem

You can post a notification to all enabled notification systems with:

/json.htm?type=command&param=sendnotification&subject=SUBJECT&body=THEBODY

{
"status": "OK",
"title": "SendNotification"
}

You can also post a notification to one or more notification systems with:

/json.htm?type=command&param=sendnotification&subject=SUBJECT&body=THEBODY&subsystem=SUBSYSTEM1;SUBSYSTEM2;...&extradata=EXTRADATA1;EXTRADATA2;....

SUBJECT = a string you want to use as subject
THEBODY= a string you want to use as body
SUBSYSTEM= the notification system(s) you want to use (lowercase)
EXTRADATA=Some subsystems can have extra data like for example FCM can have the specigic devices to be notified eg extradata=midx_7

Subsystems:

fcm
http
kodi
lms
nma
prowl
pushalot
pushbullet
pushover
pushsafer

Backup and database related

send a VACUUM request to domoticz database; sqlite.org: "The VACUUM command rebuilds the database file, repacking it into a minimal amount of disk space "

Please note that this command does require free space on the used temporary file system up to twice the current databases size.

See [sqlite.org ] goto 5.Temporary File Storage Locations

json.htm?type=command&param=vacuumdatabase

	{
		"status": "OK",
		"title": "VacuumDatabase"
	}

/backupdatabase.php

this call will create a database backup in the download directory of your workstation.

Event system

Get overview of (internal) events

From Stable 2023.2: /json.htm?type=command&param=events&evparam=list

Deprecated format (no fallback possible!) /json.htm?type=events&param=list

{
	"interpreters": "Blockly:Lua:dzVents:Python",
		"result": [
			{
				"eventstatus": "0",
				"id": "77",
				"name": "Lua  pinger"
			},
			{
				"eventstatus": "0",
				"id": "106",
				"name": "Lua curl"
			},
	....
			}
		],
	"status": "OK",
	"title": "ListEvents"
}

Deprecated format (no fallback possible!) /json.htm?type=events&param=updatestatus&eventid=77&eventstatus=1

From Stable 2023.2: /json.htm?type=command&param=events&evparam=updatestatus&eventid=77&eventstatus=1

	{
		"status": "OK",
		"title": "Events"
	}

Accept new sensors

/json.htm?type=command&param=allownewhardware&timeout=MINUTES

	{
		"status": "OK",
		"title": "AllowNewHardware"
	}

Get list of custom icons

/json.htm?type=command&param=getcustomiconset

Add 100 to the Idx value to use it in the set Custom icon command. So listed Idx: 2 is iconNumber 102 for the command.

{
  "result": [
    {
      "Description": "OpenAQ",
      "IconFile16": "images/xfr_openaq2.png",
      "IconFile48Off": "images/xfr_openaq248_Off.png",
      "IconFile48On": "images/xfr_openaq248_On.png",
      "Title": "OpenAQ",
      "idx": 1
    },
    {
      "Description": "Omnik Logo",
      "IconFile16": "images/Omnik.png",
      "IconFile48Off": "images/Omnik48_Off.png",
      "IconFile48On": "images/Omnik48_On.png",
      "Title": "Omnik",
      "idx": 2
    }
  ],
  "status": "OK",
  "title": "GetCustomIconSet"
}

Lights and switches

Get details of all lights/switches

/json.htm?type=command&param=getlightswitches

OR

/json.htm?type=command&param=getdevices&filter=light&used=true&order=Name

Example output:

{
   "result" : [
      {
         "IsDimmer" : false,
         "Name" : "Bedroom lights",
         "SubType" : "Energenie",
         "Type" : "Lighting 1",
         "idx" : "43"
      },
      {
         "IsDimmer" : false,
         "Name" : "Hall",
         "SubType" : "Energenie",
         "Type" : "Lighting 1",
         "idx" : "30"
      },
      {
         "IsDimmer" : true,
         "Name" : "Lounge Light Front",
         "SubType" : "RGBW",
         "Type" : "Lighting Limitless/Applamp",
         "idx" : "32"
      },
      {
         "IsDimmer" : true,
         "Name" : "Lounge Lights All",
         "SubType" : "RGBW",
         "Type" : "Lighting Limitless/Applamp",
         "idx" : "66"
      },
      {
         "IsDimmer" : true,
         "Name" : "Lounge light back",
         "SubType" : "RGBW",
         "Type" : "Lighting Limitless/Applamp",
         "idx" : "33"
      }
   ],
   "status" : "OK",
   "title" : "GetLightSwitches"
}

Turn a light/switch on/off

/json.htm?type=command&param=switchlight&idx=99&switchcmd=<On|Off|Toggle|Stop>

{
"status": "OK",
"title": "SwitchLight"
}

When error:

{
	"message" : "Error sending switch command, check device/hardware (idx=nnn) !",
	"status" : "ERROR",
	"title" : "SwitchLight"
}

Open-Close-Stop Blinds

Open-Close Blinds

/json.htm?type=command&param=switchlight&idx=99&switchcmd=<Open|Close|Stop>

/json.htm?type=command&param=switchlight&idx=99&switchcmd=Set%20Level&level=<0..100>

General notes

Commands are case sensitive!

Beware that if the switch has the 'protected' attribute set then you need add key `passcode` (with the right passcode)

/json.htm?type=command&param=switchlight&idx=99&switchcmd=Off&passcode=YOUR_SWITCH_PASSWORD_AS_SET_IN_SETTINGS

or the status will be

{  
   "message" : "WRONG CODE",
   "status" : "ERROR",
   "title" : "SwitchLight"
}

Note that when you use &switchcmd, the http:// or script:// on/off actions of the corresponding switch are executed. If you just want to update the status of the switch in Domoticz without running these actions, use the &param=udevice option instead (see update-section below).

Switching RFY Blinds sun/wind detector on/off

On some type of blinds it is possible to enable/disable the sun/wind detector.

Enable (where the number behind idx is the idx number of the screen in domoticz):

/json.htm?type=command&param=switchlight&idx=7&switchcmd=EnableSunWind

Disable:

/json.htm?type=command&param=switchlight&idx=7&switchcmd=DisableSunWind

Set a dimmable light/selector to a certain level

/json.htm?type=command&param=switchlight&idx=99&switchcmd=Set%20Level&level=6

dimmable:
- Some lights have 100 dim levels (like zwave and others), other hardware (kaku/lightwaverf) have other ranges like 16/32
- Level should be the dim level (not percentage), like 0-16 or 0-100 depending on the hardware used
- When the light is off, it will be turned on
Blinds: enter percentage, level will be 0-100
Selector switch: enter the level number (eg 10, 20 or 30) that can be found in the edit section of a switch.
To update in Domoticz only without running it's device actions use /json.htm?type=command&param=udevice&idx=IDX&nvalue=[0,1,2]&svalue=LEVELNR Statuses for Blinds Percentage when using &param=udevice:

      Closed: nValue = 1 and sValue = 100
      partially opened: nValue = 2 and sValue = 1-99
      Open: nValue = 0 and sValue = 0

{
   "status" : "OK",
   "title" : "SwitchLight"
}

Set a light to a certain color or color temperature

Color can be specified as either hue + brightness, RGB + optional brightness or a Domoticz JSON color object

Specify hue and brightness: Hue in degrees, 0..360; Brightness 0..100

/json.htm?type=command&param=setcolbrightnessvalue&idx=99&hue=274&brightness=40&iswhite=false

{
    "status": "OK",
    "title": "SetColBrightnessValue"
}

Note: There is no saturation parameter, specify RGB format Domoticz JSON color format for full color control

Specify RGB and brightness (optional): RGB as hexadecimal number, RRGGBB without prefix (no 0x or #)

/json.htm?type=command&param=setcolbrightnessvalue&idx=99&hex=RRGGBB&brightness=100&iswhite=false

{
    "status": "OK",
    "title": "SetColBrightnessValue"
}

Note: The actual brightness of the light is a combination of RGB value and brightness. Brightness parameter may be omitted.

A site like colorhexa can be used to help pick hex values according to desired colours.

Specify Domoticz JSON color object and brightness: Example: Specify color mode with a dim blue color

/json.htm?type=command&param=setcolbrightnessvalue&idx=130&color={"m":3,"t":0,"r":0,"g":0,"b":50,"cw":0,"ww":0}&brightness=100

{
    "status": "OK",
    "title": "SetColBrightnessValue"
}

Domoticz color format:

Domoticz color format is used as:

input parameter to:
- setcolbrightnessvalue

- updatetimer

- addtimer

- addscenedevice

- updatescenedevice
In response from:
- devices

- getscenedevices

- timers

Example: color={"m":3,"t":0,"r":0,"g":0,"b":50,"cw":0,"ww":0}

                                                         ColorMode {
                                                         	ColorModeNone = 0,   // Illegal
                                                         	ColorModeWhite = 1,  // White. Valid fields: none
                                                         	ColorModeTemp = 2,   // White with color temperature. Valid fields: t
                                                         	ColorModeRGB = 3,    // Color. Valid fields: r, g, b.
                                                         	ColorModeCustom = 4, // Custom (color + white). Valid fields: r, g, b, cw, ww, depending on device capabilities
                                                         	ColorModeLast = ColorModeCustom,
                                                         };
                                                         
                                                         Color {
                                                         	ColorMode m;
                                                         	uint8_t t;     // Range:0..255, Color temperature (warm / cold ratio, 0 is coldest, 255 is warmest)
                                                         	uint8_t r;     // Range:0..255, Red level
                                                         	uint8_t g;     // Range:0..255, Green level
                                                         	uint8_t b;     // Range:0..255, Blue level
                                                         	uint8_t cw;    // Range:0..255, Cold white level
                                                         	uint8_t ww;    // Range:0..255, Warm white level (also used as level for monochrome white)
                                                         }

References This API call is called internally by dzVents when using the following device object methods:

Please ensure local access is enabled for 127.0.0.1 or 127.0.0.* (described here). for these to work correctly.
The parameters r, g, b, cw, ww, m and t map to the same values in the aforementioned color object.
The parameter br maps to brightness [0..100].

Set an RGB_CW_WW or CW_WW light to a certain color temperature

/json.htm?type=command&param=setkelvinlevel&idx=99&kelvin=1

{
    "status": "OK",
    "title": "Set Kelvin Level"
}

Range of kelvin parameter: 0..100, 0 is coldest, 100 is warmest

References This API call is called internally by dzVents when using the following device object method:

setKelvin(Kelvin)

Please ensure local access is enabled for 127.0.0.1 or 127.0.0.* (described here). for this to work correctly.

Toggle a switch state between on/off

/json.htm?type=command&param=switchlight&idx=99&switchcmd=Toggle

{
   "status" : "OK",
   "title" : "SwitchLight"
}

Cameras

Get cameras

/json.htm?type=command&param=getcameras

{
	"result": [
		{
			"Address": "192.168.192.111",
			"Enabled": "true",
			"ImageURL": "image.jpg",
			"Name": "Inside",
			"Password": "Secret",
			"Port": 19767,
			"Protocol": 0,
			"Username": "anyUser",
			"idx": "1"
		},
		{
			"Address": "192.168.192.112",
			"Enabled": "true",
			"ImageURL": "image.jpg",
			"Name": "Outside",
			"Password": "verySecret",
			"Port": 19765,
			"Protocol": 0,
			"Username": "anotherUser",
			"idx": "2"
		}
	],
	"status": "OK",
	"title": "Cameras"
}

Add camera

imageurl must be base64 encoded

/json.htm?type=command&param=addcamera&address=192.168.192.111&port=19765&name=insideCamera&enabled=true&imageurl=aW1hZ2UuanBn&protocol=0

{
"status": "OK",
"title": "AddCamera"
}

Update camera

imageurl must be base64 encoded

/json.htm?type=command&param=updatecamera&address=192.168.192.111&port=19767&name=test&enabled=true&idx=1&imageurl=aW1hZ2UuanBn&protocol=0

{
"status": "OK",
"title": "UpdateCamera"
}

Send snapshot from camera

imageurl must be base64 encoded

&user&password optional

Sends email with a camera snapshots if email is configured in Menu Setup - Settings and set for attachments.

camidx: Send 1 or multiple camerIDs in ; separated.

Subject: Subject of email

/json.htm?type=command&param=emailcamerasnapshot&camidx=1;3&subject=Movement+at+Frontdoor

{
"status": "OK",
"title": "Email Camera Snapshot"
}

Scenes / Groups

Get current state of all scenes & groups

/json.htm?type=command&param=getscenes

Example output:

{
   "result" : [
      {
         "Favorite" : 1,
         "HardwareID" : 0,
         "LastUpdate" : "2013-09-29 19:11:01",
         "Name" : "My Scene",
         "Status" : "Off",
         "Timers" : "true",
         "Type" : "Scene",
         "idx" : "9"
      },
      {
         "Favorite" : 1,
         "HardwareID" : 0,
         "LastUpdate" : "2013-09-30 11:49:13",
         "Name" : "My Group",
         "Status" : "Off",
         "Timers" : "false",
         "Type" : "Group",
         "idx" : "3"
      }
   ],
   "status" : "OK",
   "title" : "Scenes"
}

Turn a scene / group on or off

/json.htm?type=command&param=switchscene&idx=&switchcmd=<On|Off|Toggle>

idx = id of your scene/group.
switchcmd = "On", "Off" or "Toggle" (case sensitive!)
Scenes can only be turned On

{
   "status" : "OK",
   "title" : "SwitchScene"
}

Add a scene (0)

/json.htm?type=command&param=addscene&name=scenename&scenetype=0

Add a group (1)

/json.htm?type=command&param=addscene&name=scenename&scenetype=1

Delete a scene or group

/json.htm?type=command&param=deletescene&idx=number

List devices in a scene

/json.htm?type=command&param=getscenedevices&idx=number&isscene=true

Add device to a scene

/json.htm?type=command&param=addscenedevice&idx=number&isscene=true&devidx=deviceindex&command=1&level=number&hue=number

Delete device from a scene

/json.htm?type=command&param=deletescenedevice&idx=number

List activation devices of a scene

/json.htm?type=command&param=getsceneactivations&idx=number

Example output:

{
    "result": [
       {
           "code": 0,
           "codestr": "-",
           "idx": 249,
           "name": "Activator device"
       },
       {
            "code": 0,
            "codestr": "-",
            "idx": 1048,
            "name": "Another Activator device"
       }
    ],
    "status": "OK",
    "title": "GetSceneActivations"
}

Add activation devices for a scene

/json.htm?type=command&param=addscenecode&sceneidx=<scene ID>&idx=<device ID>&cmnd=<command>

Example output:

{
    "status": "OK",
    "title": "AddSceneCode"
}

Add OnAction and OffAction to a scene or group

This command can be issue only after a scene or group was created, so first create the scene/group, than update the scene/group specifying the On Action and/or Off Action /json.htm?type=command&param=updatescene&idx=number&scenetype=scenetype&onaction=base64onaction&offaction=base64offaction

where number is the idx of the scene/group, scenetype is 0 for scenes of 1 for groups, base64onactions is the On Action coded with base64 and base64offaction is the Off Action coded with base64. It's possible to find base64 converters online, like https://www.base64encode.org/

Please note that you have to include your current description if any

Example output:

{
    "status": "OK",
    "title": "UpdateScene"
}

List timers of a scene

/json.htm?type=command&param=getscenetimers&idx=number

Example output:

{
   "result" : [
      {
         "Active" : "true",
         "Cmd" : 0,
         "Date" : "07-02-2016",
         "Days" : 128,
         "Hue" : 0,
         "Level" : 100,
         "Randomness" : true,
         "Time" : "00:01",
         "Type" : 5,
         "idx" : "16"
      }
   ],
   "status" : "OK",
   "title" : "SceneTimers"
}

Add timer to a scene

/json.htm?type=command&param=addscenetimer&idx=number&active=&timertype=&date=&hour=&min=&randomness=&command=&level=&days=

idx = index of your scene/group.
active = true/false
timertype = 0 = Before Sunrise, 1 = After Sunrise, 2 = On Time, 3 = Before Sunset, 4 = After Sunset, 5 = Fixed Date/Time
date = MM-DD-YYYY
hour = hour
min = minute
randomness = true/false
command = On/Off
level = 0..100 (%)
days = 0x80 = Everyday, 0x100 = Weekdays, 0x200 = Weekends, 0x01 = Mon, 0x02 = Tue, 0x04 = Wed, 0x08 = Thu, 0x10 = Fri, 0x20 = Sat, 0x40 = Sun

Enable/disable/delete specific scene schedule(timer)

Enable specific schedule(timer) for Scenes/Groups

Disable specific schedule(timer) for Scenes/Groups

Delete specific schedule(timer) for Scenes/Groups

Setpoint/Thermostat control

Set Setpoint

/json.htm?type=command&param=setsetpoint&idx=&setpoint=

idx = id of the setpoint
setpoint = value (for temperature in Celsius (like 20.5))

Server control

Shutdown system

/json.htm?type=command&param=system_shutdown

{
   "status" : "OK",
   "title" : "SystemShutdown"
}

Reboot system

/json.htm?type=command&param=system_reboot

{
   "status" : "OK",
   "title" : "SystemReboot"
}

Create, delete, rename, action and disable commands

Create virtual hardware

/json.htm?type=command&param=addhardware&htype=15&port=1&name=Sensors1&enabled=true

afterwards to get the id, either you have your last created id from an index you maintain or sort the hardware page for last ID: /json.htm?type=command&param=gethardware

Create a virtual sensor

Basic action (see below for values) /json.htm?type=command&param=createvirtualsensor&idx=HWIDX&sensorname=SENSORNAME&sensortype=SENSORTYPE

Note: It is normally easier to use the CreateDevice JSON (see next section)

Temp+Humidity example

/json.htm?type=command&param=createvirtualsensor&idx=HWIDX&sensorname=TempHum&sensortype=82

Electricity example

/json.htm?type=command&param=createvirtualsensor&idx=HWIDX&sensorname=Energy&sensortype=90

and then get the device id from the list:

/json.htm?type=command&param=getdevices&filter=all&used=true&order=Name

Values:

HWIDX = id of your (Dummy) hardware (not the device!). This number can be found in the hardware tab in the column "IDX".

Note: If a non existing hardware IDX is used the created device is greyed out in the user interface!

SENSORNAME = sensor name
SENSORTYPE = See list below (this is an incomplete list. For more devices see page Developing a Python plugin)

1 Pressure (Bar) 0.0 	      	     nvalue=BAR (TBC)        
2 Percentage     0.0 	      	     nvalue=PCT (TBC)	        
80 TEMP          0.0     	     svalue=TEMP
81 HUM           1		     nvalue=HUM svalue=1 to 3
82 TEMP_HUM      0.0;50;1 	     svalue=TEMP;HUM;HUM_STATUS
84 TEMP_HUM_BARO 0.0;50;1;1010;1    svalue=TEMP;HUM;HUM_STATUS;BARO;BARO_FCST
85 RAIN          0;0		     svalue=RAIN;Rain in mm/h
86 WIND          0;N;0;0;0;0  	     svalue=WIN_SPD;WIND_DIR;?;?;?;?
87 UV            0;0		     svalue= (TBC)
113 RFXMeter     0		     Can have several values, another order has to be sent to set the sub type:	   
 type 5	Time:   svalue=COUNTER
 type 4	Energy generated:   svalue=POWER;ENERGY
 type 3	Counter:   svalue=COUNTER
 type 2	Water:	   svalue=VOLUME
 type 1	Gas:   svalue=VOLUME
 type 0	Energy: svalue=POWER;ENERGY
90 ENERGY        0;0.0		     svalue=POWER;ENERGY
249 TypeAirQuality    0	     nvalue=PPM

For the RFXMeter another request is needed to set the utility (switchtype). URL is: /json.htm?type=command&param=setused&idx=DEVICE_IDX&name=SENSORNAME&switchtype=SUBTYPE_VALUE&used=true

where DEVICE_IDX is the device idx, SENSORNAME is device name, and the SUBTYPE_VALUE is one of:

0 for Energy
1 for Gas
2 for Water
3 for Custom Counter
4 for Energy Generated
5 for Time

Create a device

An overview of all available devices can be found in wiki page Developing_a_Python_plugin#Available_Device_Types

Basic Action:

/json.htm?type=command&param=createdevice&idx=HWIDX&name=SENSORNAME&sensormappedtype=MAPPEDTYPE".

HWIDX = id of your (Dummy) hardware. This number can be found in the hardware tab in the column "IDX".

Note: If a non existing hardware IDX is used the created device is greyed out in the user interface!

SENSORNAME = sensor name
DEVICETYPE = type of device, see overview Developing_a_Python_plugin#Available_Device_Types

Source: https://github.com/domoticz/domoticz/blob/development/hardware/hardwaretypes.h or https://github.com/domoticz/domoticz/blob/development/main/RFXtrx.h

DEVICESUBTYPE = subtype of device, see overview Developing_a_Python_plugin#Available_Device_Types

Source: https://github.com/domoticz/domoticz/blob/development/hardware/hardwaretypes.h or https://github.com/domoticz/domoticz/blob/development/main/RFXtrx.h

Example Result

{
	"idx" : "142",
	"status" : "OK",
	"title" : "CreateSensor"
}

Examples:

Temp (Type: pTypeTEMP, subType: sTypeTEMP5)

/json.htm?type=command&param=createdevice&idx=HWIDX&sensorname=Temp5&devicetype=50&devicesubtype=5

Voltage (Type: pTypeGeneral, subType: sTypeVoltage)

/json.htm?type=command&param=createdevice&idx=HWIDX&sensorname=Voltage0&devicetype=243&devicesubtype=8

Electric (Instant+Counter)

/json.htm?type=command&param=createdevice&idx=HWIDX&sensorname=ElecInstCount&devicetype=243&devicesubtype=29

Counter Incremental

/json.htm?type=command&param=createdevice&idx=HWIDX&sensorname=Counter%20Increment2&devicetype=243&devicesubtype=28

For the Counter Incremental, Counter and managed Counter and Switches another request is needed to set the type(switchtype). URL is:

/json.htm?type=command&param=setused&idx=DEVICE_IDX&name=SENSORNAME&switchtype=SUBTYPE_VALUE&used=true

where for counters DEVICE_IDX is the device idx, SENSORNAME is device name, and the SUBTYPE_VALUE is one of:

0 for Energy
1 for Gas
2 for Water
3 for Custom Counter
4 for Energy Generated
5 for Time

For switches

SubType Name 	
0  	On/Off 	
1  	Doorbell 	
2  	Contact 	
3  	Blinds 	
4  	X10 Siren 	
5  	Smoke Detector 	
6  	Blinds Inverted 	
7  	Dimmer 	
8  	Motion Sensor
9  	Push On Button 	
10 	Push Off Button 	
11 	Door Contact 
12 	Dusk Sensor 	
13 	Blinds Percentage 
14 	Venetian Blinds US 	
15 	Venetian Blinds EU 	
16 	Blinds Percentage Inverted 	
17 	Media Player 	
18 	Selector 	
19 	Door Lock 	
20 	Door Lock Inverted
21 	Blinds Percentage with Stop
22 	Blinds Percentage with Stop Inverted

Rename hardware

/json.htm?type=command&param=updatehardware&htype=<type>&name=<new name>&enabled=<true or false>&idx=<hardware idx>

To get the required data from the hardware first do /json.htm?type=command&param=gethardware

Rename device / sensor

/json.htm?type=command&param=setused&idx=<device ID>&name=<new name>&used=true

Enable hardware

/json.htm?type=command&param=updatehardware&htype=<type>&name=<name>&enabled=true&port=<port name>&idx=<hardware idx>&loglevel=<log level>

note Use the complete set of parms that you find when entering the enable command on the GUI because if not completely entered it will destroy your hardware table. Test first on a test system !!

Disable hardware

/json.htm?type=command&param=updatehardware&htype=<type>&name=<name>&enabled=false&idx=<hardware idx>

To get the required data from the hardware first do
/json.htm?type=command&param=gethardware

note Use the complete set of parms that you find when entering the disable command on the GUI because if not completely entered it will remove data from the parms. Test on a test system first !!

Delete hardware

/json.htm?type=command&param=deletehardware&idx=<hardware idx>

{
   "status" : "OK",
   "title" : "DeleteHardware"
}

Delete a device or sensor

/json.htm?type=command&param=setused&used=false&idx=<device idx>

{
   "status" : "OK",
   "title" : "SetUsed"
}

Enable/Disable a device or sensor

/json.htm?type=command&param=setdevused&idx=<device idx>&used=<true/false>&name=<device name>

(device name is a optional parameter)

{
   "status" : "OK",
   "title" : "SetDeviceUsed"
}

Enable a disabled device or sensor

/json.htm?idx=<device idx>&name=<new name>&type=setused&used=true

or

/json.htm?idx=<device idx>&type=setused&used=true

{
   "status" : "OK",
   "title" : "SetUsed"
}

Add an On action and/or an Off action to a device or sensor

/json.htm?type=setused&used=true&idx=IDX&strparam1=base64Encoded(ON ACTION STRING)&strparam2=base64Encoded(OFF ACTION STRING)

{
    "status": "OK",
    "title": "SetUsed"
}

Transfer device

/json.htm?type=command&param=transferdevice&idx=IDX_1&newidx=IDX_2

Transfer sensor log of device with oldest lastUpdate value to device with most recent lastUpdate value. So not necessarily from IDX_1 to IDX_2 or the other way around. Source device is removed after transfer of logs.

{
    "status": "OK",
    "title": "TransferDevice"
}

Update devices/sensors

Note that when you use this &param=udevice option with the additional option &parsetrigger=false, the device is updated without running the associated on/off- and script actions.

Expert usage. Directly set device parameters via JSON.

Be careful when firing values to domoticz.db as there is a chance to crash the database if parameters are wrong or missing. First go to the devices tab and notice the device index (idx) of the device you want to change

Generic update API's

Note make sure stringparms must be urlenecoded (eg. <space> %20, <Double quote> %27 etc..

update a sensor device

Note: for switches/lights/dimmers see Lights and Switches section.

/json.htm?type=command&param=udevice&idx=<idx>&nvalue=<numeric value>&svalue=<string value>

{
"status": "OK",
"title": "Update Device"
}

change Icon ^{Not available for all device types}

/json.htm?type=command&param=setused&used=true&name=<devicename>&description=<description>&idx=<idx>&switchtype=<switchType>&customimage=<iconNumber>

Use the getcustomiconset command to get a list of all custom icons. Add 100 the given Idx value to set the iconnumber. So listed Idx:2 is iconNumber 102

{
"status": "OK",
"title": "SetUsed"
}

change name

/json.htm?type=command&param=renamedevice&name=<new devicename>&idx=<idx>

{
"status": "OK",
"title": "RenameDevice"
}

protection On / Off

/json.htm?type=command&param=setused&used=true&protected=<true/falseidx=<idx>

{
"status": "OK",
"title": "SetUsed"
}

update in domoticz only

does not parse the actual command to the hardware (like MQTT)

with parsetrigger=false -->> No event is triggered either

/json.htm?type=command&param=udevice&idx=<idx>&nvalue=<numeric value>&svalue=<string value>&parsetrigger=<false/true>

{
"status": "OK",
"title": "Update Device"
}

Temperature

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=TEMP

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
TEMP = Temperature

{
"status": "OK",
"title": "Update Device"
}

Humidity

/json.htm?type=command&param=udevice&idx=IDX&nvalue=HUM&svalue=HUM_STAT

The above sets the parameters for a Humidity device

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
HUM = Humidity: 45%
HUM_STAT = Humidity_status

Humidity_status can be one of:

0=Normal
1=Comfortable
2=Dry
3=Wet

{
"status": "OK",
"title": "Update Device"
}

Barometer

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=BAR;BAR_FOR

The above sets the parameters for a Barometer device from hardware type 'General'

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
BAR = Barometric pressure
BAR_FOR = Barometer forecast

Barometer forecast can be one of:
0 = Stable
1 = Sunny
2 = Cloudy
3 = Unstable
4 = Thunderstorm
5 = Unknown
6 = Cloudy/Rain

Barometer forecast of other device types can be one of:
0 = Heavy Snow
1 = Snow
2 = Heavy Rain
3 = Rain
4 = Cloudy
5 = Some Clouds
6 = Sunny
7 = Unknown
8 = Unstable
9 = Stable

{
"status": "OK",
"title": "Update Device"
}

Temperature/humidity

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=TEMP;HUM;HUM_STAT

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
TEMP = Temperature
HUM = Humidity (0-100 %)
HUM_STAT = Humidity status

HUM_STAT can be one of:

0=Normal
1=Comfortable
2=Dry
3=Wet

{
"status": "OK",
"title": "Update Device"
}

Temperature/humidity/barometer

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=TEMP;HUM;HUM_STAT;BAR;BAR_FOR

The above sets the parameters for a Temp+Humidity+Barometer device

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
TEMP = Temperature
HUM = Humidity
HUM_STAT = Humidity status
BAR = Barometric pressure
BAR_FOR = Barometer forecast

HUM_STAT can be one of:

0=Normal
1=Comfortable
2=Dry
3=Wet

Barometer forecast of device type "General" (Virtual) can be one of:

0 = No Info
1 = Sunny
2 = Partly Cloudy
3 = Cloudy
4 = Rain

{
"status": "OK",
"title": "Update Device"
}

Temperature/barometer

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=TEMP;BAR;BAR_FOR;ALTITUDE

The above sets the parameters for a Temp+Humidity+Barometer device

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
TEMP = Temperature
BAR = Barometric pressure
BAR_FOR = Barometer forecast
ALTITUDE= Optional. Not used at the moment, can be 0

Barometer forecast can be one of:
0 = Stable
1 = Sunny
2 = Cloudy
3 = Unstable
4 = Thunderstorm
5 = Unknown
6 = Cloudy/Rain

Barometer forecast of other device types can be one of:
0 = Heavy Snow
1 = Snow
2 = Heavy Rain
3 = Rain
4 = Cloudy
5 = Some Clouds
6 = Sunny
7 = Unknown
8 = Unstable
9 = Stable

{
"status": "OK",
"title": "Update Device"
}

Rain

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=RAINRATE;RAINCOUNTER

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
RAINRATE = amount of rain in last hour in [mm x 100]
RAINCOUNTER = continues counter of fallen Rain in [mm]

Soil Moisture

/json.htm?type=command&param=udevice&idx=IDX&nvalue=MOISTURE

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
MOISTURE = moisture content in cb 0-200 where:

00 - 09 = saturated, 10 - 19 = adequately wet, 20 - 59 = irrigation advice, 60 - 99 = irrigation, 100-200 = Dangerously dry,

Wind

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=WB;WD;WS;WG;22;24

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
WB = Wind bearing (0-359)
WD = Wind direction (S, SW, NNW, etc.)
WS = 10 * Wind speed [m/s]
WG = 10 * Gust [m/s]
22 = Temperature
24 = Temperature Windchill

UV

 /json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=UV;TEMP

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
UV = Float (example: 2.1) with current UV reading.
TEMP = temperature (only for UV subtype TFA (3), else specify 0)

Don't loose the ";0" at the end - without it database may corrupt.

If no temp is in use, specify 0 as temperature

Counter

/json.htm?type=command&param=udevice&idx=IDX&svalue=COUNTER

IDX = id of your device (this number can be found in the devices tab in the column "IDX")
COUNTER = Integer of the overall total counter (Energy, Volume, Custom).

When there is a counter created, there is a possibility to change the units by clicking on "Change" at the utility tab.

Energy (reports kWh), give COUNTER value in Wh, integer
Energy Generated (reports kWh). give COUNTER value in Wh, integer
Gas (reports m³) , give COUNTER value in liter (1000 liter = 1 m³), integer
Water (reports m³), give COUNTER value in liter (1000 liter = 1 m³), integer
Counter (no unit)
Time (min?), seems to be obsolete, use Counter instead and use the time units as desired (eg Sec, min, hrs)

The counter will be treated with the divider which is defined in the parameters in the application settings (menu setup-settings, tab counters). For example if the counter is set to "Water" and the value is passed as liters, the divider must set to 1000 (as the unit is m³). The device displays 2 values:

The status is the overall total volume (or counter).
The volume (or counter) of the day (in the top right corner).

The today's volume (or counter) is calculated from the total volume (or counter).

Counter Incremental

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=INCREMENT

INCREMENT = Integer of the increment of the counter. For Counters the standard counter dividers apply (menu setup - settings - tab counters)

will increment the counter value by 1. To reset an incremental counter, set the svalue to a negative integer equal to the current total of the counter.

Electricity (instant and counter)

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=POWER;ENERGY

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
POWER = current power (W)
ENERGY = Integer, total cumulative energy in Watt-hours (Wh)

(Energy Read type (use edit button to change): Default: From Device. If the device is not able to send the ENERGY counter values you choose "Energy read : Computed". This will ignore ENERGY counter values and Domoticz will calculate the Energy (kWh) internally based on the (previous/current) POWER (Watt) values. By design this is less accurate then using the ENERGY counter when using them "from Device".)

Domoticz will calculate the today values based on the delta's in the total cumulative energy of today.

For Counters the standard counter dividers apply (menu setup - settings - tab counters)

Note: This device will show in Domoticz as type "General, kWh"

Managed counter

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=COUNTER;USAGE

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
COUNTER = Integer, total cumulative counter energy (Wh, can be set to -1 if unknown or unused, in that case it won't show on dashboard or in logs)
USAGE = energy usage in Watt-hours (Wh).

Managed counter will not transfer automatically every day data from device status to history log, it's up to an external script or plugin to insert data in history log database (useful to show non realtime consumption of energy provider that put energy information "in the cloud").

For Counters the standard counter dividers apply (menu setup - settings - tab counters)

To insert data in history log:

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=COUNTER;USAGE;DATE

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
COUNTER = total cumulative counter energy (Wh, can be set to -1 if unknown or unused, in that case it won't show on dashboard or in logs)
USAGE = energy usage in Watt-hours (Wh)
DATE = date with %Y-%m-%d format (for instance 2019-09-24) to put data in last week/month/year history log, or "%Y-%m-%d %H:%M:%S" format (for instance 2019-10-03 14:00:00) to put data in last days history log

Electricity Current/Ampere 3 Phase

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=Ampere_1;=Ampere_2;=Ampere_3;

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
Ampere_1 = Ampere value Phase 1
Ampere_2 = Ampere value Phase 2
Ampere_3 = Ampere value Phase 3

Electricity P1 smart meter

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=USAGE1;USAGE2;RETURN1;RETURN2;CONS;PROD

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
USAGE1= integer, total cumulative energy usage meter tariff 1 in Wh.
USAGE2= integer, total cumulative energy usage meter tariff 2 in Wh.
RETURN1= integer, total cumulative energy return meter tariff 1 in Wh.
RETURN2= integer, total cumulative energy return meter tariff 2 in Wh.
CONS= actual usage power (Watt)
PROD= actual return power (Watt)

USAGE and RETURN are total cumulative counters (they should only count up).
For USAGE and RETURN supply the data in total Wh with no decimal point.
(So if your meter displays f.i. USAGE1= 523,66 KWh you need to send 523660)
Domoticz will calculate the today values based on the delta's in the total cumulative energy of today.

For Counters the standard counter dividers apply (menu setup - settings - tab counters)

Air quality

/json.htm?type=command&param=udevice&idx=IDX&nvalue=PPM

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
PPM = CO₂-concentration

Calculated status from PPM value:

airquality < 700 status text: "Excellent"

airquality < 900 status text: "Good"

airquality < 1100 status text:"Fair"

airquality < 1600 status text: "Mediocre"

airquality >= 1600 status text: "Bad"

Pressure

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=BAR

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
BAR = Pressure in Bar

Create sensor under Hardware > Dummy > Create virtual sensor

Percentage

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=PERCENTAGE

IDX = id of your device (this number can be found in the devices tab in the column "IDX")
PERCENTAGE = Percentage

Visibility

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=VISIBILITY

IDX = id of your device (this number can be found in the devices tab in the column "IDX")
VISIBILITY = in KM

Gas

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=USAGE

USAGE= Integer, Gas usage in liter (1000 liter = 1 m³)

So if your gas meter shows f.i. 145,332 m³ you should send 145332.
The USAGE is the total usage in liters from start, not f.i. the daily usage. For Counters the divider is used from menu setup - settings, tab Counters

Lux

/json.htm?type=command&param=udevice&idx=IDX&svalue=VALUE

IDX = device ID of Lux device
VALUE = value of luminosity in Lux (INTEGER/FLOAT)

Voltage

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=VOLTAGE

IDX = device ID of Voltage device
VALUE = value of voltage sensor in Volts

Create sensor under Hardware > Dummy > Create virtual sensor

Text sensor

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=TEXT

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
TEXT = Text you want to display

Alert sensor

/json.htm?type=command&param=udevice&idx=IDX&nvalue=LEVEL&svalue=TEXT

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
Level = (0=gray, 1=green, 2=yellow, 3=orange, 4=red)
TEXT = Text you want to display

Distance sensor

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=DISTANCE

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
DISTANCE = distance in cm or inches, can be in decimals. For example 12.6

Selector Switch

/json.htm?type=command&param=switchlight&idx=IDX&switchcmd=Set%20Level&level=LEVEL

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
LEVEL = level of your selector (This number can be found in the edit selectors page, in the column "Level", 0 = Off)

Custom Sensor

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=VALUE

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
VALUE = Value (like 12.345)

Opentherm Gateway Custom command

/json.htm?type=command&param=sendopenthermcommand&idx=IDX&cmnd=COMMAND

IDX = id of your hardware Opentherm device (This number can be found in the ID column in menu Setup-Hardware)
COMMAND = The actual custom OTGW command like TC=20

Note on counters

Usually, counters are updated daily to feed week/month/year history log views. Starting version 4.11774, if you want to disable that behavior to control everything from an external script or a plugin (already the case for managed counter), you can set the "DisableLogAutoUpdate" device option to "true", for instance in a Python plugin:

Domoticz.Device(Name="MyCounter", Unit=1, Type=0xfa, Subtype=0x01, Options={"DisableLogAutoUpdate" : "true").Create()

Starting version 4.11774, you can too directly insert data in in history log. Set the "AddDBLogEntry" device option to "true", for instance in a Python plugin:

Domoticz.Device(Name="MyCounter", Unit=1, Type=0xfa, Subtype=0x01, Options={"AddDBLogEntry" : "true").Create()

With a json the parameter AddDBLogEntry:true should first base64 encoded

/json.htm?type=setused&idx=DEVICE_IDX&name=SENSORNAME&switchtype=SUBTYPE_VALUE&used=true&options=CODE

To set AddDBLogEntry:true, you must call:

/json.htm?type=setused&idx=DEVICE_IDX&name=SENSORNAME&switchtype=SUBTYPE_VALUE&used=true&options=QWRkREJMb2dFbnRyeTp0cnVl

AddDBLogEntry can be combined with other entries in the options field if separated by a semicolon for example to set:

ValueQuantity:2;AddDBLogEntry:true

You call:

/json.htm?type=setused&idx=DEVICE_IDX&name=SENSORNAME&switchtype=SUBTYPE_VALUE&used=true&options=VmFsdWVRdWFudGl0eToyO0FkZERCTG9nRW50cnk6dHJ1ZQ==

Also please note if the device is edited using the domoticz device screen then this AddDBLogEntry disappears and needs to be added again.

Then, depending on counters, you can insert values in history log. For most counters:

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=COUNTER;USAGE;DATE

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
COUNTER = total cumulative counter energy (Wh)
USAGE = energy usage in Watt-hours (Wh)
DATE = date with %Y-%m-%d format (for instance 2019-09-24) to put data in last week/month/year history log, or "%Y-%m-%d %H:%M:%S" format (for instance 2019-10-03 14:00:00) to put data in last days history log

Note: COUNTER and USAGE should be positive. Any negative value will result in 0 instead

For multi meters (P1 Smart Meter, CM113, Electrisave and CM180i):

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=USAGE1;USAGE2;RETURN1;RETURN2;CONS;PROD;DATE

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
USAGE1= energy usage meter tariff 1, This is an incrementing counter
USAGE2= energy usage meter tariff 2, This is an incrementing counter
RETURN1= energy return meter tariff 1, This is an incrementing counter
RETURN2= energy return meter tariff 2, This is an incrementing counter
CONS= actual usage power (Watt)
PROD= actual return power (Watt)
DATE = date with %Y-%m-%d format (for instance 2019-09-24) to put data in last week/month/year history log, or "%Y-%m-%d %H:%M:%S" format (for instance 2019-10-03 14:00:00) to put data in last days history log

or

/json.htm?type=command&param=udevice&idx=IDX&nvalue=0&svalue=USAGE1;USAGE2;RETURN1;RETURN2;CONS;PROD;COUNTER1;COUNTER2;COUNTER3;COUNTER4;DATE

as previously, plus absolute counter values

Additional parameters (signal level & battery level)

There are two additional and optional parameters for the above commands, to specify the signal level (default 12) and the battery level (default 255)

 /json.htm?type=command&param=udevice&idx=<idx>&nvalue=<numeric value>&svalue=<string value>&rssi=<numeric value>&battery=<numeric value>

battery level 255 = no battery device, else 0-100
example: &rssi=10&battery=89

Security

Get Password

to be able to set the security status, the (encoded) password is required.

/json.htm?type=command&param=getsettings

{
"AcceptNewHardware": 0,
"ActiveTimerPlan": 2,
"AllowWidgetOrdering": 1,
"AuthenticationMethod": 1,
"BatterLowLevel": 0,
"CM113DisplayType": 0,
.....
"SecPassword": "bfa2bea3x",
....
"WindUnit": 4,
"cloudenabled": true,
"status": "OK",
"title": "settings"
}

get the value from key "SecPassword" ;for the purpose of this wiki we assume the value read is "bfa2bea3x"

Get security state

/json.htm?type=command&param=getsecstatus

{
    "secondelay": 2,
    "secstatus": 1,
    "status": "OK",
    "title": "GetSecStatus"
}

where secstatus is

0 = Disarmed
1 = Arm Home
2 = Arm Away
3 = Unknown

Set security state

/json.htm?type=command&param=setsecstatus&secstatus=<status>&seccode=bfa2bea3x

{
   "status": "OK",
   "title": "SetSecStatus"
}

Smoke Detection

Activate

/json.htm?type=command&param=switchlight&idx=<IDX>&switchcmd=On

{
   "status": "OK",
   "title": "SwitchLight"
}

Deactivate

/json.htm?type=command&param=switchlight&idx=<IDX>&switchcmd=Off

{
   "status": "OK",
   "title": "SwitchLight"
}

Reset

/json.htm?type=command&param=resetsecuritystatus&idx=<IDX>&switchcmd=Off

{
   "status": "OK",
   "title": "ResetSecurityStatus"
}

/json.htm?type=command&param=resetsecuritystatus&idx=3456&switchcmd=Normal

{
    "status": "OK",
    "title": "SwitchLight"
}

User variables

Add a new variable

USERVARIABLENAME with the name of the variable
USERVARIABLETYPE is a digit (0,1,2,3,4) or a string (Integer, Float, String, Date, Time)

0 = Integer, e.g. -1, 1, 0, 2, 10 
1 = Float, e.g. -1.1, 1.2, 3.1
2 = String
3 = Date in format DD/MM/YYYY
4 = Time in 24 hr format HH:MM

USERVARIABLEVALUE with the value

All formats are checked by the api, when the variable does not match the required format it is not stored.

/json.htm?type=command&param=adduservariable&vname=USERVARIABLENAME&vtype=USERVARIABLETYPE&vvalue=USERVARIABLEVALUE

{
	"status": "OK",
	"title": "AddUserVariable"
}

Update an existing variable

Remember to change:

USERVARIABLENAME with the name of your variable
USERVARIABLETYPE according to the table from "Add a new variable"
USERVARIABLEVALUE with the new value

Note: events will only be triggered when the variabletype and variablename are not changed by the update command.

/json.htm?type=command&param=updateuservariable&vname=USERVARIABLENAME&vtype=USERVARIABLETYPE&vvalue=USERVARIABLEVALUE

{
	"status": "OK",
	"title": "UpdateUserVariable"
}

List all variables

/json.htm?type=command&param=getuservariables

{
	"result": [
		{
			"LastUpdate": "2020-01-13 09:04:17",
			"Name": "setup-test",
			"Type": "2",
			"Value": "Hi",
			"idx": "1"
		},
		{
			"LastUpdate": "2020-02-17 16:48:03",
			"Name": "presence-test",
			"Type": "0",
			"Value": "1",
			"idx": "2"
		},
....
		{
			"LastUpdate": "2021-03-02 21:10:54",
			"Name": "UV_Night",
			"Type": "2",
			"Value": "21:11",
			"idx": "44"
		}
	],
	"status": "OK",
	"title": "GetUserVariables"
}

List one variable

/json.htm?type=command&param=getuservariable&idx=IDX

IDX = id of your variable (This number can be found using the "List all variables" call above)

{
	"result": [
		{
			"LastUpdate": "2021-03-02 21:10:54",
			"Name": "UV_Night",
			"Type": "2",
			"Value": "21:11",
			"idx": "44"
		}
	],
	"status": "OK",
	"title": "GetUserVariable"
}

Delete a variable

IDX = id of your variable (This number can be found using the "List all variables" call above)

/json.htm?type=command&param=deleteuservariable&idx=IDX

{
	"status": "OK",
	"title": "DeleteUserVariable"
}

trigger dzVents script using customEvent ^{dzVents 3.0.0}

/json.htm?type=command&param=customevent&event=MyEvent&data=MyData

{
	"status": "OK",
	"title": "Custom Event"
}

Room Plans

List all rooms

/json.htm?type=command&param=getplans&order=name&used=true

{
	"result": [
		{
			"Devices": 6,
			"Name": "Google Calendars",
			"Order": "2",
			"idx": "2"
		},
		{
			"Devices": 2,
			"Name": "Private",
			"Order": "3",
			"idx": "3"
		},
		{
			"Devices": 1,
			"Name": "EVOHome",
			"Order": "4",
			"idx": "4"
		},
		{
			"Devices": 0,
			"Name": "testPlan",
			"Order": "5",
			"idx": "5"
		}
	],
	"status": "OK",
	"title": "Plans"
}

List all devices in a room

IDX = id of your room

/json.htm?type=command&param=getplandevices&idx=IDX

Show idx, name of the device like:

{
"result": [
{
"DevSceneRowID": "492",
"Name": "device name",
"devidx": "492",
"idx": "9",
"order": "9",
"type": 0
}
],
"status": "OK",
"title": "GetPlanDevices"
}

/json.htm?type=devices&plan=IDX

show details of the devices like

{
"ActTime": 1569909986,
"AstrTwilightEnd": "21:14",
"AstrTwilightStart": "05:50",
"CivTwilightEnd": "19:54",
"CivTwilightStart": "07:09",
"DayLength": "11:39",
"NautTwilightEnd": "20:34",
"NautTwilightStart": "06:30",
"ServerTime": "2019-10-01 08:06:26",
"SunAtSouth": "13:32",
"Sunrise": "07:42",
"Sunset": "19:21",
"app_version": "4.11337",
"result": [
{
"AddjMulti": 1,
"AddjMulti2": 1,
"AddjValue": 0,
"AddjValue2": 0,
"BatteryLevel": 255,
"CustomImage": 0,
"Data": "19.5 C, (13.5 C), PermanentOverride",
"Description": "",
"Favorite": 1,
"HardwareID": 30,
"HardwareName": "Evohome",
"HardwareType": "Evohome via Web API",
"HardwareTypeVal": 75,
"HaveTimeout": false,
"ID": "1168736",
"LastUpdate": "2019-10-01 08:05:35",
"Name": "Device name",
"Notifications": "false",
"PlanID": "4",
"PlanIDs": [
4
],
"Protected": false,
"SetPoint": 13.5,
"ShowNotifications": true,
"SignalLevel": 10,
"Status": "PermanentOverride",
"SubType": "Zone",
"Temp": 19.5,
"Timers": "false",
"Type": "Heating",
"TypeImg": "override_mini",
"Unit": 7,
"Used": 1,
"XOffset": "0",
"YOffset": "0",
"idx": "492"
}
],
"status": "OK",
"title": "Devices"
}

Timer Plans

List all Timerplans

/json.htm?type=command&param=gettimerplans

{
"result": [
{
"Active": false,
"Name": "Default",
"idx": 0
},
{
"Active": true,
"Name": "Holiday",
"idx": 1
},
{
"Active": false,
"Name": "Day off (including weekend)",
"idx": 2
}
],
"status": "OK",
"title": "GetTimerPlans"
}

Add Timerplan

/json.htm?type=command&param=addtimerplan&name=newTimerplan

{
"status": "OK",
"title": "AddTimerPlan"
}

Change Timerplan name

/json.htm?type=command&param=updatetimerplan&idx=3&name=newname

{
"status": "OK",
"title": "UpdateTimerPlan"
}

Duplicate Timerplan

This will copy all existing timers from timerplan with idx 3 to a new plan

/json.htm?type=command&param=duplicatetimerplan&idx=3&name=duplicatename

{
"status": "OK",
"title": "DuplicateTimerPlan"
}

Make Timerplan active

This will make the timerplan with idx 2 the active one

/json.htm?type=command&param=setactivetimerplan&ActiveTimerPlan=2

{
"status": "OK",
"title": "SetActiveTimerPlan"
}

History

Switch devices

/json.htm?type=command&param=getlightlog&idx=IDX

Delete

/json.htm?type=command&param=clearlightlog&idx=<idx>

Text devices

/json.htm?type=command&param=gettextlog&idx=IDX

Delete

/json.htm?type=command&param=clearlightlog&idx=<idx>

Temperature

/json.htm?type=command&param=graph&sensor=temp&idx=IDX&range=[day|month|year]&actyear=YYYY

Custom sensor

Totals by period :

/json.htm?type=command&param=graph&sensor=Percentage&idx=IDX&range=day

{{
	"result" : 
	[
		{
			"d" : "2021-02-04 16:40",
			"v" : "308.6"
		},
		{
			"d" : "2021-02-04 16:45",
			"v" : "308.6"
		},
.....

	],
	"status" : "OK",
	"title" : "Graph Percentage day"
}

/json.htm?type=command&param=graph&sensor=Percentage&idx=IDX&range=[day|month|year|year&actyear=YYYY]

{
	"result" : 
	[
		{
			"d" : "2021-01-18",
			"v_avg" : "308.6",
			"v_max" : "309.6",
			"v_min" : "307.6"
		},
		{
			"d" : "2021-01-19",
			"v_avg" : "308.6",
			"v_max" : "310.6",
			"v_min" : "306.6"
		},
		{
			"d" : "2021-01-21",
			"v_avg" : "308.6",
			"v_max" : "310.6",
			"v_min" : "306.6"
		},
...

		{
			"d" : "2021-02-18",
			"v_avg" : "308.6",
			"v_max" : "310.6",
			"v_min" : "306.6"
		}
	],
	"status" : "OK",
	"title" : "Graph Percentage <...>"
}

Energy, Gas, Water

Instantaneous consumption :

/json.htm?type=command&param=graph&sensor=counter&idx=IDX&range=day&method=1

Totals by period : /json.htm?type=command&param=graph&sensor=counter&idx=IDX&range=[day|month|year|year&actyear=YYYY|YYYY-MM-DDTYYYY-MM-DD]

Only for counters it is possible to specify a date range for long history data (not for short log data):

&range=YYYY-MM-DDTYYYY-MM-DD

Notice the "T" between the dates in range.

Deleting History log entries

delete a single data point or day

/json.htm?type=command&param=deletedatapoint&idx=IDX&date=DATE

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
DATE = date in %Y-%m-%d format (for instance 2021-02-26) will delete history data of that particular day (one entry from long term history and max 120 entries from short term history log)
DATE = date in "%Y-%m-%d%20%H:%M:%S" format (for instance 2019-10-03%2014:00:00) will delete history data of that particular time (one entry from short term history log)

{
"status": "OK",
"title": "deletedatapoint"
}

delete a date range of data points

/json.htm?type=command&param=deletedaterange&idx=IDX&fromdate=FROMDATE&todate=TODATE  ^{V2020.2 build >= 13027}

IDX = id of your device (This number can be found in the devices tab in the column "IDX")
FROMDATE = date in %Y-%m-%d or date in "%Y-%m-%d%20%H:%M:%S"format (for instance 2021-02-26 / 2019-10-03%2014:00:00) will delete history data (from short and long history tables) starting with that day / time
TODATE = date in %Y-%m-%d or date in "%Y-%m-%d%20%H:%M:%S"format (for instance 2021-02-26 / 2019-10-03%2014:00:00) will delete history data (from short and long history tables) ending with that day / time

{
"status": "OK",
"title": "deletedaterange"
}

Device Timer Schedules

Get all schedules (timers)

/json.htm?type=command&param=getschedules

{
   "result" : [
      {
         "Active" : "true",
         "Date" : "",
         "Days" : 128,
         "DevName" : "Porch Light",
         "DeviceRowID" : 52,
         "Hue" : 0,
         "IsThermostat" : "false",
         "Level" : 100,
         "MDay" : 0,
         "Month" : 0,
         "Occurence" : 0,
         "Randomness" : "false",
         "ScheduleDate" : "2016-04-01 20:33:00",
         "Time" : "00:20",
         "TimerCmd" : 0,
         "TimerID" : 9,
         "TimerType" : 4,
         "TimerTypeStr" : "After Sunset",
         "Type" : "Device"
      },

Get all schedules(timers) for all Devices

/json.htm?type=command&param=getschedules&filter=device

{
	"result": [
		{
			"Active": "true",
			"Color": "",
			"Date": "",
			"Days": 128,
			"DevName": "coffeeSwitch",
			"DeviceRowID": 1014,
			"IsThermostat": "false",
			"Level": 100,
			"MDay": 0,
			"Month": 0,
			"Occurence": 0,
			"Randomness": "false",
			"ScheduleDate": "2021-03-11 06:01:00",
			"Time": "06:01",
			"TimerCmd": 0,
			"TimerID": 62,
			"TimerType": 2,
			"TimerTypeStr": "On Time",
			"Type": "Device"
		},
		{
			"Active": "true",
			"Color": "",
			"Date": "",

			"TimerType": 2,
			"TimerTypeStr": "On Time",
			"Type": "Device"
		}
	],
	"status": "OK",
	"title": "Schedules"
}

Get all schedules(timers) for one Device

/json.htm?type=command&param=gettimers&idx=timerID

Type returns

0: Before Sunrise
1: After Sunrise
2: On Time
3: Before Sunset
4: After Sunset
5: Fixed Date/Time
6: Odd Day Numbers
7: Even Day Numbers
8: Odd Week Numbers
9: Even Week Numbers
10: Monthly
11: Monthly (Weekday)
12: Yearly
13: Yearly (Weekday)
14: Before Sun at South
15: After Sun at South
16: Before Civil Twilight Start
17: After Civil Twilight Start
18: Before Civil Twilight End
19: After Civil Twilight End
20: Before Nautical Twilight Start
21: After Nautical Twilight Start
22: Before Nautical Twilight End
23: After Nautical Twilight End
24: Before Astronomical Twilight Start
25: After Astronomical Twilight Start
26: Before Astronomical Twilight End
27: After Astronomical Twilight End

{
	"result" : 
	[
		{
			"Active" : "true",
			"Cmd" : 0,
			"Color" : "",
			"Date" : "",
			"Days" : 128,
			"Level" : 100,
			"MDay" : 0,
			"Month" : 0,
			"Occurence" : 0,
			"Randomness" : "false",
			"Time" : "08:30",
			"Type" : 23,
			"idx" : "45"
		}
	],
	"status" : "OK",
	"title" : "Timers"
}

Get all schedules(timers) for all Scenes

/json.htm?type=command&param=getschedules&filter=scene

{
    "result" : 
    [
        {
            "Active" : "true",
            "Color" : "",
            "Date" : "",
            "Days" : 128,
            "DevName" : "Lights",
            "DeviceRowID" : 6,
            "IsThermostat" : "false",
            "Level" : 100,
            "MDay" : 0,
            "Month" : 0,
            "Occurence" : 0,
            "Randomness" : "false",
            "ScheduleDate" : "2021-03-12 07:01:00",
            "Time" : "00:03",
            "TimerCmd" : 1,
            "TimerID" : 4,
            "TimerType" : 0,
            "TimerTypeStr" : "Before Sunrise",
            "Type" : "Scene"
        },
        {
            "Active" : "true",
            "Color" : "",
            "Date" : "",
            "Days" : 128,
            "DevName" : "Garden lights",
            "DeviceRowID" : 6,
            "IsThermostat" : "false",
            "Level" : 100,
            "MDay" : 0,
            "Month" : 0,
            "Occurence" : 0,
            "Randomness" : "false",
            "ScheduleDate" : "2021-03-12 09:00:00",
            "Time" : "09:00",
            "TimerCmd" : 1,
            "TimerID" : 6,
            "TimerType" : 2,
            "TimerTypeStr" : "On Time",
            "Type" : "Scene"
        },
        {
            "Active" : "true",
            "Color" : "",
            "Date" : "",
            "Days" : 128,
            "DevName" : "Frontdoor",
            "DeviceRowID" : 5,
            "IsThermostat" : "false",
            "Level" : 100,
            "MDay" : 0,
            "Month" : 0,
            "Occurence" : 0,
            "Randomness" : "false",
            "ScheduleDate" : "2021-03-12 01:30:00",
            "Time" : "01:30",
            "TimerCmd" : 0,
            "TimerID" : 2,
            "TimerType" : 2,
            "TimerTypeStr" : "On Time",
            "Type" : "Scene"
        }
    ],
    "status" : "OK",
    "title" : "Schedules"
}

Get all schedules(timers) for one Scene

/json.htm?type=command&param=getscenetimers&idx=sceneID

{
     "result": [{
             "Active": "true",
             "Cmd": 0,
             "Date": "",
             "Days": 128,
             "Level": 100,
             "MDay": 0,
             "Month": 0,
             "Occurence": 0,
             "Randomness": "false",
             "Time": "01:30",
             "Type": 2,
             "idx": "2"
         }
     ],
     "status": "OK",
     "title": "SceneTimers"
}

Get all schedules(timers) for all Thermostats

/json.htm?type=command&param=getschedules&filter=thermostat

{
    "status": "OK",
    "title": "Schedules"
}

Get all schedules(timers) for one Thermostat

/json.htm?type=command&param=getsetpointtimers&idx=timerID

{
    "status": "OK",
    "title": "SetpointTimers"
}

Enable specific schedule(timer) for Devices

/json.htm?type=command&param=enabletimer&idx=timerID

{
    "status": "OK",
    "title": "EnableTimer"
}

Disable specific schedule(timer) for Devices

/json.htm?type=command&param=disabletimer&idx=timerID

{
    "status": "OK",
    "title": "DisableTimer"
}

Delete a specific schedule(timer) for Devices

/json.htm?type=command&param=deletetimer&idx=timerID

{
    "status": "OK",
    "title": "DeleteTimer"
}

Enable specific schedule(timer) for Thermostats

/json.htm?type=command&param=enablesetpointtimer&idx=timerID

{
    "status": "OK",
    "title": "EnableSetpointTimer"
}

Disable specific schedule(timer) for Thermostats

/json.htm?type=command&param=disablesetpointtimer&idx=timerID

{
    "status": "OK",
    "title": "DisableSetpointTimer"
}

Delete a specific schedule(timer) for Thermostats

/json.htm?type=command&param=deletesetpointtimer&idx=timerID

{
    "status": "OK",
    "title": "DeleteSetpointTimer"
}

Update parameters for a specific schedule(timer) for Devices

/json.htm?type=command&param=updatetimer&idx=timerID&active=true&timertype=3&hour=0&min=20&randomness=true&command=0&days=12345</source>

idx = timerID
active = true/false
timertype - see Get all schedules(timers) for one Device for timerTypeDefinition
hour = hour
min = minute
randomness = true/false
command = On=0 / Off=1 (inverted logic)
days = 1=Mon, 2=Tue, 3=Wed, 4=Thurs, 5=Fri, 6=Sat, 7=Sun

Create a new schedule(timer) for an existing device

/json.htm?type=command&param=addtimer&idx=DeviceRowID&active=true&timertype=2&hour=0&min=20&randomness=false&command=0&days=1234567

{
    "status": "OK",
    "title": "AddTimer"
}

idx = DeviceRowID = index of your device (other commands use a timerID as idx but here we use DeviceRowID).
active = true/false
timertype - see Get all schedules(timers) for one Device for timerTypeDefinition
hour = hour
min = minute
randomness = true/false
command = On=0 / Off=1 (inverted logic)
days = 1=Mon, 2=Tue, 3=Wed, 4=Thurs, 5=Fri, 6=Sat, 7=Sun

Clear all schedules(timers) for a particular device

/json.htm?type=command&param=cleartimers&idx=DeviceRowID

{
    "status": "OK",
    "title": "ClearTimer"
}

idx = DeviceRowID = index of your device (other commands use a timerID as idx but here we use DeviceRowID).

Enable specific schedule(timer) for Scenes/Groups

/json.htm?type=command&param=enablescenetimer&idx=sceneID

{
    "status": "OK",
    "title": "EnableSceneTimer"
}

Disable specific schedule(timer) for Scenes/Groups

/json.htm?type=command&param=disablescenetimer&idx=sceneID

{
    "status": "OK",
    "title": "DisableSceneTimer"
}

Delete a specific schedule(timer) for Scenes/Groups

/json.htm?type=command&param=deletescenetimer&idx=sceneID

{
    "status": "OK",
    "title": "DeleteSceneTimer"
}

Notifications

Get all notification types

/json.htm?type=command&param=getnotifications

{
    "notifiers": [{
            "description": "browser",
            "name": "browser"
        }, {
            "description": "clickatell",
            "name": "clickatell"
        }, {
            "description": "email",
            "name": "email"
        }, {
            "description": "fcm",
            "name": "fcm"
        }, {
            "description": "http",
            "name": "http"
        }, {
            "description": "kodi",
            "name": "kodi"
        }, {
            "description": "lms",
            "name": "lms"
        }, {
            "description": "prowl",
            "name": "prowl"
        }, {
            "description": "pushalot",
            "name": "pushalot"
        }, {
            "description": "pushbullet",
            "name": "pushbullet"
        }, {
            "description": "pushover",
            "name": "pushover"
        }, {
            "description": "pushsafer",
            "name": "pushsafer"
        }, {
            "description": "telegram",
            "name": "telegram"
        }
    ],
    "status": "OK",
    "title": "Notifications"
}

Get device notifications

/json.htm?idx=<deviceIDX>&param=getnotificationtypes&type=command

{
    "result": 
    [
      {
         "ptag": "S",
         "text": "Switch On",
         "val": 7
      }
    ],
    "status": "OK",
    "title": "GetNotificationTypes"
}

/json.htm?type=command&param=getnotifications&idx=<deviceIDX>

{
    "notifiers": [{
            "description": "browser",
            "name": "browser"
        }, {
            "description": "clickatell",
            "name": "clickatell"
        }, {
            "description": "email",
            "name": "email"
        }, {
            "description": "fcm",
            "name": "fcm"
        }, {
            "description": "http",
            "name": "http"
        }, {
            "description": "kodi",
            "name": "kodi"
        }, {
            "description": "lms",
            "name": "lms"
        }, {
            "description": "prowl",
            "name": "prowl"
        }, {
            "description": "pushalot",
            "name": "pushalot"
        }, {
            "description": "pushbullet",
            "name": "pushbullet"
        }, {
            "description": "pushover",
            "name": "pushover"
        }, {
            "description": "pushsafer",
            "name": "pushsafer"
        }, {
            "description": "telegram",
            "name": "telegram"
        }
    ],
    "result": [{
            "ActiveSystems": "clickatell;email;fcm;http;kodi;lms;prowl;pushalot;pushbullet;pushover;pushsafer;telegram",
            "CustomMessage": "test",
            "Params": "S",
            "Priority": 0,
            "SendAlways": false,
            "idx": 3
        }
    ],
    "status": "OK",
    "title": "Notifications"
}

Add device notification

/json.htm?idx=<deviceIDX>&param=addnotification&tmsg=test&tpriority=0&tsendalways=true&tsystems=fcm;http&ttype=7&tvalue=0&twhen=0&type=command

{
    "status": "OK",
    "title": "AddNotification"
}

Update device notifications

/json.htm?devidx=<DeviceID>&idx=<notificationID>&param=updatenotification&taction=<action command>&tactive=<true/false>&tmsg=<msgText>&tpriority=<pri>&tsendalways=<true/false>&tsystems=<list of notification subsystems>&ttype=<notificationType>&tvalue=0&twhen=0&type=command

{
    "status": "OK",
    "title": "UpdateNotification"
}

Delete device notification

json.htm?idx=<notificationID>&param=deletenotification&type=command

{
    "status": "OK",
    "title": "DeleteNotification"
}

Delete all device notifications

/json.htm?idx=<deviceID>&param=clearnotifications&type=command

{
    "status": "OK",
    "title": "ClearNotification"
}

LMS and Kodi (Media Players)

While both Logitech Media Server and Kodi can be controlled by JSON RPC commands sent directly to the URL of the LMS server or Kodi instance, it can be useful to use Domoticz as a tunnel/proxy to send a number of widely-used commands because you may have an external port already open for Domoticz and because Domoticz also supports HTTPS.

LMS

/json.htm?type=command&param=lmsmediacommand&idx=nnn&action=ACTION

where ACTION can be: Left, Right, Up, Down, Favorites, Browse, NowPlaying, Shuffle, Repeat, Play, Pause, Stop, Rewind, Forward, Mute, VolumeUp, VolumeDown, PowerOn and PowerOff.

Kodi

/json.htm?type=command&param=kodimediacommand&idx=nnn&action=ACTION

where ACTION can be: PlayPause, Stop, FastForward, BigStepForward, Rewind, BigStepBack, ShowSubtitles, FullScreen, VolumeUp, VolumeDown, ChannelUp, ChannelDown, Channels Home, Back, ContextMenu, Info, Select, Down, Right, Up, Left

Evohome

These commands work regardless of which of the 3 implementation-modes for Evohome you have chosen for your system (WebAPI, USB device, Scripting). Some of them will also work for e.g. the Honeywell Round WiFi thermostat.

Updating the evohome controller mode

  /json.htm?type=command&param=switchmodal&idx=<idx>&status=<status>&action=<action>&ooc=<ooc>

<idx> id number of the evohome controller device in Domoticz
<status> Auto, AutoWithReset, AutoWithEco, Away, DayOff, Custom, HeatingOff
<action> (1 = run on action script, 0 = disable)
<ooc> (1 = only trigger the event & log on change, 0 = always trigger & log)

Specify an until date

  /json.htm?type=command&param=switchmodal&idx=<idx>&status=<status>&action=<action>&ooc=<ooc>&until=<until>

as above
<until> ISO date time to run until. Format example 2018-09-15T15:53:00 or 2018-09-15T15:53:00+01:00 with timezone.

Note: most controller modes do not support the time part of the ISO data and will only act upon the date portion - this will require at least the next day to be reflected in the date number to successfully trigger an update.

Updating a zone setpoint

/json.htm?type=command&param=setsetpoint&idx=<idx>&setpoint=<setpoint>&mode=<mode>&used=true

<idx> id number of the relevant evohome zone device in Domoticz
<setpoint> set point in degrees (will be ignored for Auto)
<mode> Auto, TemporaryOverride, PermanentOverride, FollowSchedule
used must be true

Specifying a date/time for zone TemporaryOverride

/json.htm?type=command&param=setsetpoint&idx=<idx>&setpoint=<setpoint>&mode=TemporaryOverride&until=<until>&used=true

as above
<until> ISO date time for the set point override. Format example 2018-09-15T15:53:00 or 2018-09-15T15:53:00+01:00 with timezone.

In this case, any combination of a date portion and a time portion that are in the future will meet with success.

Turning HotWater ON/OFF

/json.htm?type=command&param=setused&idx=<idx>&setpoint=<setpoint>&state=<state>&mode=<mode>&used=true

<idx> id number of the evohome DHW temp device in Domoticz
<setpoint> set point in degrees (will be ignored)
<state> On, Off
<mode> Auto, TemporaryOverride, PermanentOverride, FollowSchedule
used must be true

Configuring zwave devices

Below mentioned commands are for the to be deprecated OpenZwave integration. Switch to Zwave-JS-UI as soon as possible!!

Listing zwave node parameters

  json.htm?type=command&param=getopenzwavenodes&idx=ControllerIDX

ControllerIDX = the idx of your OpenZWave USB controller device, as listed under the 'Setup --> Hardware' tab.

Example output:

{
   "NodesQueried" : true,
   "ownNodeId" : 1,
   "result" : [
      {
         "Description" : "Neo CoolCam Door/Window Detector",
         "HaveUserCodes" : false,
         "HomeID" : 3554707869,
         "IsPlus" : true,
         "LastUpdate" : "2018-08-04 20:09:02",
         "Manufacturer_id" : "0x0258",
         "Manufacturer_name" : "Neo CoolCam",
         "Name" : "Garage DOor",
         "NodeID" : 40,
         "PollEnabled" : "false",
         "Product_id" : "0x1082",
         "Product_name" : "Door/Window Detector",
         "Product_type" : "0x0003",
         "State" : "Sleeping",
         "Version" : 4,
         "config" : [
            {
               "LastUpdate" : "2018-08-01 09:06:45",
               "help" : "This configuration parameter that can be used to adjust the amount of delay before the OFF command is transmitted. This parameter can be configured with the value of 0 through 65535, where 0 means send OFF command immediately and 65535 means 65535 seconds of delay.",
               "index" : 1,
               "label" : "Configuring the OFF Delay",
               "type" : "short",
               "units" : "second",
               "value" : "0"
            },
            {
               "LastUpdate" : "2018-08-01 09:06:45",
               "help" : "Basic Set Command will be sent where contains a value when the door/window is opened or closed, the receiver will take it for consideration; for instance, if a lamp module is received the Basic Set Command of which value is decisive as to how bright of dim level of lamp module shall be.",
               "index" : 2,
               "label" : "Basic Set Level",
               "type" : "byte",
               "units" : "",
               "value" : "255"
            },
            {
               "LastUpdate" : "2018-08-03 07:55:52",
               "help" : "",
               "index" : 2000,
               "label" : "Wake-up Interval",
               "type" : "int",
               "units" : "Seconds",
               "value" : "43200"
            }
         ],
         "idx" : "11"
      },
     {
         "Description" : "FIBARO System FGWPE/F Wall Plug",
         "HaveUserCodes" : false,
         "HomeID" : 3554707869,
         "IsPlus" : false,
         "LastUpdate" : "2018-08-05 12:12:24",
         "Manufacturer_id" : "0x010f",
         "Manufacturer_name" : "FIBARO System",
         "Name" : "Studio",
         "NodeID" : 5,
         .
         .
         .

Note the node_idx towards the end of each device's entry (the "idx" : "11" in the example above for the Neo CoolCam Door/Window Detector). You don't see this node_idx in the regular devices tab for Domoticz, but it is the idx you'll need when changing a parameter through JSON (next section).

Getting the battery levels

  /json.htm?type=command&param=zwavegetbatterylevels&idx=controlleridx

controlleridx = the idx of your OpenZWave USB controller device, as listed under the 'Setup --> Hardware' tab.

Example output:

{
   "result" : [
      {
         "battery" : 255,
         "nodeID" : 17,
         "nodeName" : "Designlamp bij TV"
      },
      {
         "battery" : 255,
         "nodeID" : 19,
         "nodeName" : "Lichtknopje voorkamer"
      },
      {
         "battery" : 100,
         "nodeID" : 33,
         "nodeName" : "Rookmelder"
      }
   ],
   "status" : "OK",
   "title" : "GetBatteryLevels"
}

Note: a Battery level of 255 indicates either a non battery powered device, or a battery powered device which has not yet send a battery measurement to OpenZWave yet.

Changing a zwave device parameter

  /json.htm?type=command&param=applyzwavenodeconfig&idx=node_idx&valuelist=plist

node_idx = the value found by searching through the output of openzwavenodes for the node in question (see above)
plist = the (partially) URI encoded and BASE64 encoded parameter list

The plist entries start with an unencoded decimal item number preceded by and followed by an underscore (e.g. _7_), followed by the correctly-encoded string. You can check out the encodings at the following links: base64decode and at urlencode. In Base64, 'Enable' is written as 'RW5hYmxl', so it looks odd but it's easy once you grasp it.

For example, if you are configuring a NEO Coolcam Siren through JSON,

  /json.htm?type=command&param=applyzwavenodeconfig&idx=10&valuelist=7_QWxhcm0gbXVzaWM%3D

would change parameter 7 (Configure Default Siren On Mode) to 'Alarm music', while

  /json.htm?type=command&param=applyzwavenodeconfig&idx=10&valuelist=7_RG9vciBiZWxsIG11c2lj%3D

would change it to 'Door bell music' (because 'RG9vciBiZWxsIG11c2lj' is the result of Base64 encoding 'Door bell music'). Note: Any '%3D' and such in the plist are the result of URI encoding an '=' or other non-alphanumeric character.

The easiest way to learn about this is to change a zwave device parameter manually using your browser while you have developer tools enabled (hit 'ctrl-shift-i' in Chrome). Look under the network tab at the JSON sent back by the browser to Domoticz when you click on 'Apply Configuration for This Device'.

  /json.htm?type=command&param=applyzwavenodeconfig&idx=10&valuelist=3_MjU1_1_SGlnaA%3D%3D_
2_MSBtaW51dGU%3D_4_TG93_5_MTA%3D_6_MQ%3D%3D_7_QWxhcm0gbXVzaWM%3D_8_RW5hYmxl_9_RGlzYWJsZQ%3D%3D_

The browser will actually send the full parameter list to Domoticz, including the unchanged values of any parameters you didn't alter. If you modify one of them, however, you'll see that edit reflected in the Base64-encoded JSON string.

Language-specific JSON examples

The following tiny code snippets demonstrate the syntax for using JSON with Domoticz from some popular programming languages.

Bash

#!/bin/bash
curl -s 'http://192.168.178.12:8080/json.htm?type=devices&rid=104' | jq .result[0].Temp | sed 's/\"//g' | awk '{ print $1 }'

PHP

#!/usr/bin/php

 <?php
 $json_string = file_get_contents("http://192.168.178.12:8080/json.htm?type=devices&rid=110");
 $parsed_json = json_decode($json_string, true);
 $test_link = "/home/pi/output.txt";
 $test_data = fopen ($test_link, "w+");
 fwrite ($test_data, print_R($parsed_json, TRUE));
 fclose ($test_data);
 ?>

Python

#!/usr/bin/python

import urllib
import urllib2
import requests

...

url = 'http://192.168.178.12:8080/json.htm?type=command&param=udevice&nvalue=0&idx='+idx+'&svalue='+sval
try:
  request = urllib2.Request(url)
  response = urllib2.urlopen(request)
  except urllib2.HTTPError, e:
    print e.code; time.sleep(60)
  except urllib2.URLError, e:
    print e.args; time.sleep(60)

Perl

#!/usr/bin/perl

use LWP::UserAgent;
use JSON::XS;

$url{domo}=>'http://192.168.178.12:8080';
$idx=301;

$ua=LWP::UserAgent->new; $ua->timeout(5);
$retrieve=$ua->get($url{domo}.'/json.htm?type=devices&rid='.$idx);
$res=$retrieve->decoded_content;
if ($retrieve->is_success) { $jres = JSON::XS->new->allow_nonref->decode($res)  } else { warn $retrieve->status_line };
$state=$$jres{result}[0]->{Status}; # 'On', 'Off', 'Open', 'Closed', etc
print "The switch state for idx $idx is currently '$state'\n";

@@ Line 2,864: / Line 2,864: @@
 ==Update device notifications==
-  /json.htm?devidx=<DeviceID>&idx=<notificationID>&param=updatenotification&tmsg=<msgText>&tpriority=<pri>&tsendalways=<true/false>&tsystems=<list of notification subsystems>&ttype=<notificationType>&tvalue=0&twhen=0&type=command
+  /json.htm?devidx=<DeviceID>&idx=<notificationID>&param=updatenotification&taction=<action command>&tactive=<true/false>&tmsg=<msgText>&tpriority=<pri>&tsendalways=<true/false>&tsystems=<list of notification subsystems>&ttype=<notificationType>&tvalue=0&twhen=0&type=command
 <source lang="json">{
      "status": "OK",

Domoticz API/JSON URL's: Difference between revisions

Latest revision as of 18:02, 20 November 2024

Warning Stable 2023.2 (and newer)

Format

Making output more readable

Authorization

Users

Base64 encode

Response

General usage

A note on IDXes

Retrieve status of Domoticz instance

Get list of all defined users in the system

Get settings

Retrieve Domoticz logfile information

Add a log message to the Domoticz log

Retrieve status of specific device

Retrieve name / idx of all devices

Get status of all devices of a certain type

Get status of all devices, including hidden ones

Get status of all Favorite devices

Get server time

Get sunrise and sunset times

Use Notification Subsystem

Backup and database related

Event system

Accept new sensors

Get list of custom icons

Lights and switches

Get details of all lights/switches

Turn a light/switch on/off

Open-Close-Stop Blinds

General notes

Switching RFY Blinds sun/wind detector on/off

Set a dimmable light/selector to a certain level

Set a light to a certain color or color temperature

Set an RGB_CW_WW or CW_WW light to a certain color temperature

Toggle a switch state between on/off

Cameras

Get cameras

Add camera

Update camera

Send snapshot from camera

Scenes / Groups

Get current state of all scenes & groups

Turn a scene / group on or off

Add a scene (0)

Add a group (1)

Delete a scene or group

List devices in a scene

Add device to a scene

Delete device from a scene

List activation devices of a scene

Add activation devices for a scene

Add OnAction and OffAction to a scene or group

List timers of a scene

Add timer to a scene

Enable/disable/delete specific scene schedule(timer)

Setpoint/Thermostat control

Set Setpoint

Server control

Shutdown system

Reboot system

Create, delete, rename, action and disable commands

Create virtual hardware

Create a virtual sensor

Create a device

Rename hardware

Rename device / sensor

Enable hardware

Disable hardware

Delete hardware

Delete a device or sensor

Enable/Disable a device or sensor

Enable a disabled device or sensor

Add an On action and/or an Off action to a device or sensor

Transfer device

Update devices/sensors

Generic update API's

update a sensor device

change Icon ^{Not available for all device types}

trigger dzVents script using customEvent ^{dzVents 3.0.0}