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

FieldTypeDescriptionRequired
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

FieldTypeDescription
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 address 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.
softwareupdate 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

FieldTypeDescription
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

FieldTypeDescriptionRequired
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

FieldTypeDescriptionRequired
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

FieldTypeDescriptionRequired
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/<apikey>/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