Configuration

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 access to various REST-API endpoints.

Note: The request will only succeed if the gateway is unlocked. Either by using HTTP basic authentification, or by unlocking the gateway from within the Phoscon App.

Learn more about unlocking in the Authorization section.

Parameters

Name Type Description Required
devicetype String 1–40 chars Application name Required

Example request data

{
    "devicetype": "Lighthouse#Bobs Nexus"
}

Response

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

Possible errors

If the gateway is not unlocked the HTTP status 403 Forbidden will be returned with following error message:

[{
    "error": {
        "address": "/",
        "description": "link button not pressed",
        "type": 101
    }
}]

Delete API key

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

Deletes the entry <apikey2> from the whitelist. The apikey is marked invalid and can no longer be used for requests.

Response

[ { "success": "/config/whitelist/3896ADF3A0 deleted." } ]

Get configuration

GET /api/<apikey>/config

Returns the current gateway configuration.

Response

{
    "UTC": "2018-12-27T09:09:13",
    "bridgeid": "00212EFFFF00C5FB",
    "devicename": "ConBee",
    "dhcp": true,
    "fwversion": "0x26310500",
    "gateway": "192.168.2.1",
    "ipaddress": "192.168.2.4",
    "linkbutton": false,
    "localtime": "2018-12-27T10:09:13",
    "mac": "00:1f:c6:9b:e8:58",
    "modelid": "deCONZ",
    "name": "skull",
    "netmask": "255.255.255.0",
    "networkopenduration": 600,
    "panid": 56864,
    "proxyaddress": "none",
    "proxyport": 0,
    "rfconnected": true,
    "swversion": "2.5.52",
    "timezone": "Europe/Paris",
    "uuid": "048044f5-1129-4f82-80c8-dfdb75c9262d",
    "websocketport": 23765,
    "whitelist": {
        "03BC298E06": {
            "create date": "2017-07-23T12:38:31",
            "last use date": "2017-07-23T17:41:08",
            "name": "Phoscon"
        },
        "03E087A45B": {
            "create date": "2018-10-26T14:21:55",
            "last use date": "2018-12-08T00:22:25",
            "name": "Hue Essentials#EVA-L09"
        }
    },
    "zigbeechannel": 15
}

Response fields

Name Type Description
name String 4–16 Name of the gateway
devicename String Name of the device like ConBee or RaspBee
modelid String Software name: deCONZ
swversion String Software version of deCONZ
fwversion String Firmware version of the connected device
dhcp String Whether the IP address is obtained with DHCP
gateway String IP address of the router to which the gateway is connected to
ipaddress String IP address of the gateway
netmask String Network mask of the gateway
linkbutton Bool True when the gateway is unlocked
UTC String Global UTC time in ISO 8601 format
localtime String Localtime of the gateway in ISO 8601 format
timezone String Timezone of the gateway like “Europe/Paris”
panid Number 1–65534 The ZigBee network id
mac String MAC address of the gateway
bridgeid String Unique identifier of the gateway
proxyaddress String Proxy address, default "none"
proxyport Number Proxy port, 0 if proxy is not eabled
websocketport Number Port where the websocket server is listening
networkopenduration Number Light and sensor search duration in seconds
rfconnected Bool true when ZigBee network is operational
zigbeechannel Number 11–26 Currently active ZigBee channel
whitelist Object List of all registered apikeys

Note: The response contains more fields to provide compatibility to certain apps. These contain mostly dummy values and should be ignored.

Get full state

GET /api/<apikey>

Returns the full state of the gateway including config, lights, groups, rules, resourcelinks, sensors, scenes and schedules.

Response

{
    "config": { },
    "groups": { },
    "lights": { },
    "schedules": { },
    "sensors": { },
    "rules": { },
    "resourcelinks": { }
}

Response fields

Name Type Description
config Object All configuration attributes
groups Object All groups and their attributes
lights Object All lights and their attributes
rules Object All rules and their attributes
resourcelinks Object All resourcelinks and their attributes
schedules Object All schedules and their attributes
sensors Object All sensors and their attributes

Modify configuration

PUT /api/<apikey>/config

Modify configuration parameters.

Parameters

Name Type Description
name String 1–16 Name of the gateway
zigbeechannel Number The ZigBee channel to use: 11, 15, 20 or 25
timezone String The timezone in the tz database format like “Europe/Paris”
UTC String Global UTC time in ISO 8601 format

Example request data

{
    "name": "Ted"
}

Response

[{
      "success": {"/config/name": "Ted" }
}]