The configuration endpoint allows to retreive 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.0.0",
    "dhcp": true,
    "gateway": "192.168.80.1",
    "ipaddress": "192.168.80.142",
    "linkbutton": false,
    "localtime": "2016-06-29T14:00:40",
    "mac": "74:46:a0:9e:92:c7",
    "name": "deCONZ-GW",
    "netmask": "255.255.255.0",
    "networkopenduration": 60,
    "panid": 56889,
    "portalservices": false,
    "proxyaddress": "",
    "proxyport": 0,
    "swupdate": {
        "notify": false,
        "text": "",
        "updatestate": 0,
        "url": "",
    },
    "swversion": "20405",
    "timeformat": "12h",
    "timezone": "Europe/Berlin",
    "utc": "2016-06-29T12:00:40",
    "uuid": "a65d80a1-975a-4598-8d5a-2547bc18d63b",
    "whitelist": {},
    "zigbeechannel": 20
}

Response fields

FieldTypeDescription
apiversion String The version of the deCONZ Rest API
dhcp Bool Whether the IP address of the bridge is obtained with DHCP.
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.
name String Name of the gateway.
netmask String Network mask of the gateway.
networkopenduration Number (0..65535) Can be used to store the permitjoin (see Modify configuration) value permanently.
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
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 available on Raspberry Pi Gateway). "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
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
name String (0..16 chars) Name of the gateway. optional
rfconnected Bool Set connected state of the gateway. optional
updatechannel String Set update channel ("stable"|"alpha"|"beta"). 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
groupdelay Number (0..5000) Time between two group commands in milliseconds. optional
otauactive Bool Set OTAU active or inactive. optional
discovery Bool Set gateway discovery over the internet active or inactive. optional
unlock Number (0..600) Unlock the gateway so that apps can register themselves to the gateway (time in seconds). optional
zigbeechannel Number (11|15|20|25) Set the zigbeechannel of the gateway. Notify other ZigBee devices also to change their channel. optional
timezone String Set the timezone of the gateway (only on Raspberry Pi). Format: tzdatabase e.g. “Europe/Berlin” https://en.wikipedia.org/wiki/List_of_tz_database_time_zones optional
utc String Set the UTC time of the gateway (only on Raspbery Pi) in ISO 8601 format (yyyy-MM-ddTHH:mm:ss). optional
timeformat String ("12h"|"24h") Can be used to store the timeformat permanently. 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 firmware 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 combination 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 (“delight”,”delight”). Only possible within 10 minutes after gateway start.

Response

  
    HTTP/1.1 200 OK
  
  
    {}
  

Possible errors

403 Forbidden