Configuration¶

This endpoint allows to retrieve and modify the current configuration of the gateway.

Acquire API key ¶

POST /api

Creates a new API key which provides authorized access to the REST-API.

Note

The request will only succeed if the gateway is unlocked or valid HTTP basic authentification credentials are provided in the HTTP request header see authorization.

Parameters¶

Field	Type	Description	Required
devicetype	String (0–40 chars)	Name of the client application.	required
username	String (10–40 chars)	Will be used as username. If not specified a random key will be generated.	optional

Example request data¶

{
    "username": "988112a4e198cc1211",
    "devicetype": "my application"
}

Response¶


HTTP/1.1 200 OK


[ { "success": { "username": "988112a4e198cc1211" } } ]

Possible errors¶

400 Bad Request

403 Forbidden

Delete API key ¶

DELETE /api/<apikey>/config/whitelist/<apikey2>

Deletes an API key so it can no longer be used.

Parameters¶

None

Possible errors¶

403 Forbidden

404 Not Found

Get configuration ¶

GET /api/<apikey>/config

Returns the current gateway configuration.

Parameters¶

None

Response¶


HTTP/1.1 200 OK
ETag: "203941fel3ds8ad61903224"


{
    "apiversion": "1.16.0",
    "bridgeid": "00212EFFFF00C5FB",
    "devicename": "ConBee II",
    "dhcp": true,
    "fwversion": "0x26660700",
    "gateway": "192.168.80.1",
    "ipaddress": "192.168.80.142",
    "linkbutton": false,
    "localtime": "2020-06-29T14:00:40",
    "mac": "74:46:a0:9e:92:c7",
    "modelid": "deCONZ",
    "name": "deCONZ-GW",
    "netmask": "255.255.255.0",
    "networkopenduration": 60,
    "ntp": "synced",
    "panid": 56889,
    "portalservices": false,
    "proxyaddress": "",
    "proxyport": 0,
    "rfconnected": true,
    "swupdate": {
        "notify": false,
        "text": "",
        "updatestate": 0,
        "url": "",
    },
    "swversion": "2.6.0",
    "timeformat": "12h",
    "timezone": "Europe/Berlin",
    "UTC": "2020-06-29T12:00:40",
    "uuid": "a65d80a1-975a-4598-8d5a-2547bc18d63b",
    "websocketnotifyall": true,
    "websocketport": 23765,
    "whitelist": {},
    "zigbeechannel": 20
}

Response fields¶

Field	Type	Description
apiversion	String	The version of the deCONZ Rest API
bridgeid	String	The unique identifier for the gateway.
devicename	String	The product name of the gateway. Valid values are "ConBee", "RaspBee", "ConBee II" and "RaspBee II".
dhcp	Bool	Whether the IP address of the bridge is obtained with DHCP.
fwversion	String	The current Zigbee firmware version.
gateway	String	IPv4 network gateway of the gateway.
ipaddress	String	IPv4 address of the gateway.
linkbutton	Bool	true if the gateway is unlocked.
localtime	String	The localtime of the gateway
mac	String	MAC address of the gateway.
modelid	String	Fixed string "deCONZ".
name	String	Name of the gateway.
netmask	String	Network mask of the gateway.
networkopenduration	Number (1–65535)	The duration in seconds used by lights and sensors search, see Modify configuration.
ntp	String	Only for gateways running on Linux. Tells if the NTP time is "synced" or "unsynced".
panid	Number (0–65535)	The Zigbee pan ID of the gateway.
portalservices	Bool	This indicates whether the bridge is registered to synchronize data with a portal account.
proxyaddress	String	Not supported
proxyport	Number	Not supported
rfconnected	Bool	Is true when the deCONZ is connected with the firmware and the Zigbee network is up.
swupdate2	Object	Contains information related to software updates.
swversion	String	The software version of the gateway.
timeformat	String	Stores a value of the timeformat that can be used by other applications. "12h" or "24h"
timezone	String	Timezone used by the gateway (only on Raspberry Pi). "None" if not further specified.
UTC	String	Current UTC time of the gateway in ISO 8601 format.
uuid	String	UPNP Unique Id of the gateway
websocketnotifyall	Bool	When true all state changes will be signalled through the Websocket connection (default true).
websocketport	Number	Port of the Websocket server.
whitelist	Object	An array of whitelisted API keys.
zigbeechannel	Number	The current wireless frequency channel used by the Gateway. Supported channels: 11, 15, 20, 25.

Possible errors¶

304 Not Modified

403 Forbidden

Get full state ¶

GET /api/<apikey>

Returns the full state of the gateway including all its lights, groups, scenes and schedules.

Parameters¶

None

Response¶


HTTP/1.1 200 OK
ETag: "203941fel3ds8ad61903224"


{
    "config": {
        "dhcp": true,
        "gateway": "192.168.178.1",
        "ipaddress": "192.168.192.237",
        "linkbutton": true,
        "mac": "E0:69:95:58:06:7F",
        "name": "RaspBee GW",
        "netmask": "255.255.255.0",
        "portalservices": false,
        "proxyaddress": "",
        "proxyport": 0,
        "swupdate": {
            "notify": false,
            "text": "",
            "updatestate": 0,
            "url": ""
        },
        "swversion": "1.12.3",
        "UTC": "2013-05-22T12:02:30",
        "whitelist": {}
    },
    "groups": {
        "1": {
            "action": {
                "bri": 3945,
                "colormode": "hs",
                "ct": 500,
                "effect": "none",
                "hue": 0,
                "on": true,
                "sat": 17680,
                "xy": [0.0610457, 0.219979]
            },
            "devicemembership": [],
            "etag": "893f60b611274d1803207298cf26b1e1",
            "hidden": false,
            "lights": [ "1" ],
            "lightsequence": [ "1" ],
            "multideviceids": [],
            "name": "Office",
            "scenes": [ 
                "0": {
                    "id": "1",
                    "name": "blue moon"
                }
           ]
        }
    },
    "lights": {
        "1": {
            "etag": "030cf8c1c0025420f3a0659afab251f5",
            "name": "Desk Lamp",
            "modelid": "FLS-PP-01",
            "pointsymbol": {},
            "swversion": "14010400",
            "type": "Color Dimmable Light",
            "state": {
                "on": true,
                "bri": 190,
                "hue": 21672,
                "sat": 254,
                "ct": 500,
                "alert": "none",
                "colormode": "hs",
                "effect": "none",
                "reachable": true,
                "xy": [ 0.805343, 0.000612754 ]
            }
        }
    },
    "schedules": {
        "1": {
            "autodelete": false
            "command": {
            "address": "/api/AD4F14F244/groups/2/scenes/1/recall"
            "body": {}
            "method": "PUT"
            }
            "etag": "3dea322b33d34a9134e5632706448f8f"
            "name": "Good Morning"
            "status": "enabled"
            "time": "W124/T05:00:00"
        }
    },
    "sensors": {
        1: {
            "config": {
                "on": true
                "reachable": false
            }
            "etag": "01252de8b14f62a234a4680827cf1609"
            "manufacturername": "dresden elektronik"
            "mode": 2
            "modelid": "Lighting Switch"
            "name": "Lighting Switch 1"
            "state": {
                "lastupdated": "2016-06-29T13:16:41"
            }
            "swversion": "1.0"
            "type": "ZHASwitch"
            "uniqueid": "0x00212effff00a6bc"
            }
        }
    "rules": {}
    }

Response fields¶

Field	Type	Description
config	Object	Configuration of the gateway.
groups	Object	All groups of the gateway.
lights	Object	All lights of the gateway.
rules (as from deconz version > 2.04.12)	Object	All rules of the gateway.
schedules	Object	All schedules of the gateway.

Possible errors¶

304 Not Modified

403 Forbidden

Modify configuration ¶

PUT /api/<apikey>/config

Modify configuration parameters.

Parameters¶

Field	Type	Description	Required
discovery	Bool	Set gateway discovery over the internet active or inactive.	optional
groupdelay	Number (0–5000)	Time between two group commands in milliseconds.	optional
lightlastseeninterval	Number (1–65535)	Sets the number of seconds where the timestamp for "lastseen" is updated at the earliest for light resources. For any such update, a seperate websocket event will be triggered. Default: 60	optional
name	String (0–16 chars)	Name of the gateway.	optional
networkopenduration	Number (1–65535)	Sets the lights and sensors search duration in seconds.	optional
otauactive	Bool	Set OTAU active or inactive.	optional
permitjoin	Number (0–255)	Open the network so that other zigbee devices can join. 0 = network closed, 255 = network open, 1–254 = time in seconds the network remains open. The value will decrement automatically.	optional
rfconnected	Bool	Set to true to bring the Zigbee network up and false to bring it down. This has the same effect as using the Join and Leave buttons in deCONZ.	optional
timeformat	String	Can be used to store the timeformat permanently. It can be either "12h" or "24h".	optional
timezone	String	Set the timezone of the gateway (only on Raspberry Pi). Format: tzdatabase e.g. “Europe/Berlin” Wikipedia:ListOfTimeZones	optional
unlock	Number (0–600)	Unlock the gateway so that apps can register themselves to the gateway (time in seconds).	optional
updatechannel	String	Set update channel ("stable"\|"alpha"\|"beta").	optional
utc \| UTC	String	Set the UTC time of the gateway (only on Raspbery Pi) in ISO 8601 format (yyyy-MM-ddTHH:mm:ss). For historical reasons both "utc" and "UTC" are supported as key.	optional
zigbeechannel	Number (11\|15\|20\|25)	Set the zigbeechannel of the gateway. Notify other Zigbee devices also to change their channel.	optional
websocketnotifyall	Bool	When true all state changes will be signalled through the Websocket connection (default true).	optional

Example request data¶


{
  "zigbeechannel": 25
}

Response¶


HTTP/1.1 200 OK
ETag: "203941fel3ds8ad61903224"


[
  { 
    "success": {"/config/zigbeechannel": 25 }
  }
]

Possible errors¶

400 Bad Request

Update software ¶

POST /api/<apikey>/config/update

Returns the newest software version available. Starts the update if available (only on Raspberry Pi).

Response¶


HTTP/1.1 200 OK


{
  "success": { 
    "/config/update": "2.04.05"
  }
}

Update firmware ¶

POST /api/<apikey>/config/updatefirmware

Starts the update firmware process if newer version is available.

Response¶


HTTP/1.1 200 OK


{
  "success": {
    "/config/updatefirmware": "26050500"
  }
}

Possible errors¶

503 Service Unavailable

Reset gateway ¶

POST /api/<apikey>/config/reset

Reset the gateway network settings to factory new and/or delete the deCONZ database (config, lights, scenes, groups, schedules, devices, rules).

Parameters¶

Field	Type	Description	Required
resetGW	Bool	Set the network settings of the gateway to factory new.	optional
deleteDB	Bool	Delete the Database.	optional

At least one parameter is required!

Response¶


HTTP/1.1 200 OK


{
  "success": { 
    "/config/reset": "success"
  }
}

Possible errors¶

400 Bad Request

503 Service Unavailable

Change password ¶

PUT /api/<apikey>/config/password

Change the Password of the Gateway. The parameter must be a Base64 encoded string of <username>:<password>.

Parameters¶

Field	Type	Description	Required
username	String	The user name (currently only “delight” is supported).	required
oldhash	String	The Base64 encoded combination of “username:old password”.	required
newhash	String	The Base64 encoded combination of “username:new password”.	required

Response¶


HTTP/1.1 200 OK


{
  "success": {
    "/config/password": "changed"
  }
}

Possible errors¶

400 Bad Request

401 Unauthorized

Reset password ¶

DELETE /api/config/password

Resets the username and password to default username = “delight” and password = “delight”. The request can only succeed within 10 minutes after gateway start.

Response¶

  
    HTTP/1.1 200 OK

{}

Possible errors¶

403 Forbidden