Casambi REST API

Overview

Casambi Restful API is used for accessing persistent Casambi bluetooth mesh network information from Casambi cloud services. This kind of information does not change very often and in most cases is tied to configuration of related network, luminaires and devices.

API Base URL: https://door.casambi.com

To gain access to Casambi WebSocket (and its events) use of information like session id and network id received from REST API are required.

note

Event information reveiced from the WebSocket is supplementing the information received from the REST API and in some parts may overlap.
All GET request parameter values (URL query parameters) must be URL encoded.

Version History

/v1 Create network/Casambi user sessions and request network-related information.

Recent Changes

13.05.2020 - Datapoints request updated to use string-based data type filter values; int-based sensor type values are deprecated
07.12.2020 - Datapoints support timezone offset parameter and ISO 8601 formatted time range parameters
16.12.2020 - Renamed mac property to address for clarity
04.03.2021 - Added CURL request examples and Datalogging documentation
15.08.2021 - Added XmlHttp JavaScript code examples; navigation split to sections
01.12.2022 - Added new Datapoint query endpoint; deprecated old version
22.03.2023 - Response now indicates availability of more data on server
04.09.2024 - Deprecated Datapoint query endpoint (v1) is no longer available
06.01.2026 - Added API endpoint for creating network session for given network entity ID
07.01.2026 - Added API endpoint for creating network session set from network entity ID list

Getting Started

To use the REST API:

Acquire API Key - Acquire API key, contact Casambi Support for more info.
Obtain Credentials - Acquire user (site) or network credentials with at least one network and connected devices (Casambi app).
Test Requests - Test how authentication and requests work with REST API web console.

note

API key availability is currently limited.

API Authentication

Overview

Use your Casambi user (site account) or network (admin) credentials to authenticate and to create a session. With Casambi (site) user session you will have access to all network, site and device data related to that site user account. With network session you will have access only to network and device data related to that network admin credentials.

note

The preferred method to create a network session is to always give a network entity ID as a parameter. In most cases this will allow the network session creation request to respond faster.

Casambi user and network sessions are both created with POST request where credentials are given in the payload of the request body. For a network session it is also possible to give a network entity ID as a URL parameter to limit the request to that network. In addition, API key must be set to custom request header property named X-Casambi-Key.

note

In general API session ID will be valid for a long time. When session ID expires then new one needs to be created.

Example:

X-Casambi-Key: 8aSdFG678M8nPL63FNe5fjrey42loASFWg64v29Se23GAm67576werQtyz1

API Key Use Limits

The API enforces the following limits per API key:

Size of request data per minute
Size of response data per minute
Amount of requests per minute
Amount of concurrent requests

If any limit is exceeded, the request will fail with HTTP status code.

Authentication endpoints

Create user session

Create Casambi user (site account) session identified by email & password, requires use of API key (Header: X-Casambi-Key).

note

Note that user session works only with site user credentials. If you don't know what site user is then you should use network session instead.
After 3 failed logins user has to wait one minute to try to login again. When trying to login during this wait time server will respond with status code: Forbidden 403.

HTTP Request:

POST https://door.casambi.com/v1/users/session

Request Body:

{
  "email": "name@address.com",
  "password": "password"
}

CURL Example:

curl -X POST "https://door.casambi.com/v1/users/session" \
  -H "Content-Type: application/json" \
  -H "X-Casambi-Key:API-KEY-HERE" \
  -d "{\"email\":\"EMAIL-HERE\",\"password\":\"PASSWORD-HERE\"}"

Response Example

{
  "sessionId": "hJK65SenmlL2354y.P822D76HufewNSloo780PvU-78DwdmnMA8exzIo9.mmNWD23whEqbPOsl11hjjWo03___",
  "sites": {
    "Rg5alx4BF41lSU2jK4r7T0Q7X0i00mQ": {
      "name": "Playground",
      "address": "",
      "role": "ADMIN",
      "networks": {
        "VcrTwqLZJ26UYMXxTClmpfZxELcrPUAa": {
          "id": "VcrTwqLZJ26UYMXxTClmpfZxELcrPUAa",
          "address": "a00f251f77cc",
          "name": "Dev Network",
          "type": "OPEN",
          "grade": "EVOLUTION",
          "role": "ADMIN"
        }
      }
    }
  },
  "networks": {
    "VcrTwqLZJ26UYMXxTClmpfZxELcrPUAa": {
      "id": "VcrTwqLZJ26UYMXxTClmpfZxELcrPUAa",
      "address": "a00f251f77cc",
      "name": "Dev Network",
      "type": "OPEN",
      "grade": "EVOLUTION",
      "role": "ADMIN"
    }
  }
}

note

Notice the "sessionId" and each "id" (networkId) of "networks" and "sites/networks" data within response data. These are needed in almost all further API requests.

Create Network Session(s)

Create network (admin) session identified by email & password, requires use of API key (Header: X-Casambi-Key).

note

Network session works only with network credentials. If you have site user credentials then you should use user session instead.
After 3 failed logins user has to wait one minute to try to login again. When trying to login during this wait time server will respond with status code: Forbidden 403.

HTTP Request:

POST https://door.casambi.com/v1/networks/session

Request Body:

{
  "email": "name@address.com",
  "password": "password"
}

CURL Example:

curl -X POST "https://door.casambi.com/v1/networks/session" \
  -H "Content-Type: application/json" \
  -H "X-Casambi-Key:API-KEY-HERE" \
  -d "{\"email\":\"EMAIL-HERE\",\"password\":\"PASSWORD-HERE\"}"

Response Example

{
  "VcrTwqLZJ26UYMXxTClmpfZxELcrPUAa": {
    "id": "VcrTwqLZJ26UYMXxTClmpfZxELcrPUAa",
    "address": "a00f251f77aa",
    "name": "Dev Network",
    "type": "OPEN",
    "grade": "EVOLUTION",
    "sessionId": "KDRmwOqerOsTyrr0x9HLrGFe1nknEk3oRoT-Kz3DJ.wx97MTXQXC.ZbWwqt9ze0KwC6h3GCTlPsUemX8uvK5Ow__"
  }
}

note

Notice the "sessionId" and "id" (networkId) within response data. These both are needed in almost all further API requests.

Create Network Session Set

Create network (admin) session set identified by email & password (maximum of 100 networks), requires use of API key (Header: X-Casambi-Key).

note

Network session set returns only networks that can be accessed with given credentials. If you have site user credentials then you should use user session instead.
After 3 failed logins user has to wait one minute to try to login again. When trying to login during this wait time server will respond with status code: Forbidden 40

HTTP Request:

POST https://door.casambi.com/v1/networks/set/session

Request Body:

{
  "email": "name@address.com",
  "password": "password",
  "networks": ["networkId1", "networkId2", "..."]
}

CURL Example:

curl -X POST "https://door.casambi.com/v1/networks/set/session" \
  -H "Content-Type: application/json" \
  -H "X-Casambi-Key:API-KEY-HERE" \
  -d "{\"email\":\"EMAIL-HERE\",\"password\":\"PASSWORD-HERE\",\"networks\":[\"NETWORK-ID1\",\"NETWORK-ID2\"]}"

note

Notice the "sessionId" and "id" (networkId) values within response data. These details are needed in almost all further API requests.

Create Session for Network

Create network (admin) session identified by email & password for a single network. Requires use of API key (Header: X-Casambi-Key).

note

Network session works only with network credentials. If you have site user credentials then you should use user session instead.
After 3 failed logins user has to wait one minute to try to login again. When trying to login during this wait time server will respond with status code: Forbidden 403.

HTTP Request:

POST https://door.casambi.com/v1/networks/{networkId}/session

Path Parameters:

  id: "networkId"

Request Body:

{
  "email": "name@address.com",
  "password": "password"
}

CURL Example:

curl -X POST "https://door.casambi.com/v1/networks/NETWORK-ID-HERE/session"
  -H "Content-Type: application/json"
  -H "X-Casambi-Key:API-KEY-HERE"
  -d "{\"email\":\"EMAIL-HERE\",\"password\":\"PASSWORD-HERE\"}"

Response Example

{
    "VcrTwqLZJ26UYMXxTClmpfZxELcrPUAa": {
        "id": "VcrTwqLZJ26UYMXxTClmpfZxELcrPUAa",
        "address": "a00f251f77aa",
        "name": "Dev Network",
        "type": "OPEN",
        "grade": "EVOLUTION",
        "sessionId": "KDRmwOqerOsTyrr0x9HLrGFe1nknEk3oRoT-Kz3DJ.wx97MTXQXC.ZbWwqt9ze0KwC6h3GCTlPsUemX8uvK5Ow__"
    }
}

note

The "sessionId" and "id" (networkId) within response data. These both are needed in almost all further API requests.

Using Created Session

Successful create session API request will return JSON data object that includes different network related information and session ID. Note that network session has different session ID for each network included in the result set.

This session ID is required to be used as custom header property X-Casambi-Session along with the API key to access any related information from REST API.

Example:

X-Casambi-Key: 8aSdFG78678M8nPL63FSNe5fjrey45762loASFWg64v29Se23GWAm67576werQtyz1
X-Casambi-Session: hJK65SenmlL2354y.P822D76HufewNSloo780PvU-78DwdmnMA8exzIo9.mmNWD23whEqbPOsl11hjjWo03___

Endpoint definitions

Request Network Information

Retrieves network information identified by network ID, requires use of API key and sessionId (Header: X-Casambi-Key, X-Casambi-Session). Note that if unit (item of units list) is part of a group (groupId > 0) it will have position value of 0 as the actual position within the group will be found in related group information. See groups list of network data to find the actual position info of the group and its units.

HTTP Request:

GET https://door.casambi.com/v1/networks/{id}

Path Parameters:

id: "networkId"

CURL Example:

curl "https://door.casambi.com/v1/networks/NETWORK-ID-HERE" \
  -H "X-Casambi-Session:SESSION-ID-HERE" \
  -H "X-Casambi-Key:API-KEY-HERE"

Response Example

{
    "id": "VcrTwqLZJ26UYMXxTClmpfZxELcrPUAa",
    "name": "Demo Room",
    "revision": 125,
    "grade": "EVOLUTION",
    "address": "b02ef7956bcc",
    "gateway": {
        "name": "Demo iPad"
    },
    "type": "OPEN",
    "timezone": "Europe/Helsinki",
    "photos": [
        {
            "name": "Photo",
            "controls": [],
            "image": "iR4aIP3vXcB348Pijif2d4Y7AnowFbdD",
            "position": 0
        },
        {
            "name": "Photo",
            "controls": [],
            "image": "KLejfitLiEFeiUnhak6ID69VzJhvWYER",
            "position": 1
        }
    ],
    "units": {
        "12": {
            "id": 12,
            "address": "80dfc3a5e41d",
            "name": "CBM #5656",
            "position": 0,
            "fixtureId": 5656,
            "firmwareVersion": "32.10",
            "groupId": 3,
            "labels": {},
            "type": "Luminaire"
        },
        "15": {
            "id": 15,
            "address": "b3e63c069abc",
            "name": "aBc (PIR)",
            "position": 3,
            "fixtureId": 1202,
            "firmwareVersion": "32.10",
            "groupId": 0,
            "labels": {},
            "type": "Sensor"
        },
        "18": {
            "id": 18,
            "address": "a01e6079c30f",
            "name": "TestZXY",
            "image": "7Fw3whiOxsfuE6GTR6utJl8OEAPkOd3",
            "position": 4,
            "fixtureId": 5124,
            "firmwareVersion": "32.10",
            "groupId": 0,
            "labels": {},
            "type": "Luminaire"
        }
    },
    "scenes": {
        "1": {
            "name": "Timer",
            "id": 1,
            "position": 0,
            "icon": 0,
            "color": "#FFFFFF",
            "type": "REGULAR",
            "hidden": false,
            "units": {
                "12": {
                    "id": 12
                }
            }
        },
        "4": {
            "name": "Presence",
            "id": 2,
            "position": 1,
            "icon": 0,
            "color": "#06FF29",
            "type": "REGULAR",
            "hidden": false,
            "units": {
                "18": {
                    "id": 18
                }
            }
        }
    },
    "groups": {
        "3": {
            "id": 3,
            "name": "Demo Group",
            "position": 2,
            "units": [
                {
                    "0": 12,
                    "position": 0
                }
            ]
        }
    }
}

Request Network Unit List

Retrieves information of units in network identified by network ID, requires use of API key and sessionId (Header: X-Casambi-Key, X-Casambi-Session). Note that if unit is part of a group (groupId > 0) it will have position value of 0 as the actual position within the group will be found in related group information.

HTTP Request:

GET https://door.casambi.com/v1/networks/{id}/units

Path Parameters:

id: "networkId"

CURL Example:

curl "https://door.casambi.com/v1/networks/NETWORK-ID-HERE/units" \
  -H "X-Casambi-Session:SESSION-ID-HERE" \
  -H "X-Casambi-Key:API-KEY-HERE"

Response Example

{
    "12": {
        "id": 12,
        "address": "80dfc3a5e41e",
        "name": "CBM #5656",
        "position": 0,
        "fixtureId": 5656,
        "firmwareVersion": "32.10",
        "groupId": 3,
        "labels": {},
        "type": "Luminaire"
    },
    "15": {
        "id": 15,
        "address": "b3e63c069abc",
        "name": "aBc (PIR)",
        "position": 3,
        "fixtureId": 1202,
        "firmwareVersion": "32.10",
        "groupId": 0,
        "labels": {},
        "type": "Sensor"
    },
    "18": {
        "id": 18,
        "address": "a01e6079c30f",
        "name": "TestZXY",
        "image": "7Fw3whiOxsfuE6GTR6utJl8OEAPkOd3",
        "position": 4,
        "fixtureId": 5124,
        "firmwareVersion": "32.10",
        "groupId": 0,
        "labels": {},
        "type": "Luminaire"
    }
}

Request Network Unit State

Retrieves information of current unit state in network identified by network ID and unit ID, requires use of API key and sessionId (Header: X-Casambi-Key, X-Casambi-Session). This information is similar to one received along with WebSocket unitChanged events. Note that if unit is part of a group (groupId > 0) it will have position value of 0 as the actual position within the group will be found in related group information.

HTTP Request:

GET https://door.casambi.com/v1/networks/{networkId}/units/{unitId}/state

Path Parameters:

networkId: "networkId"
unitId: unitId

CURL Example:

curl "https://door.casambi.com/v1/networks/NETWORK-ID-HERE/units/UNIT-ID-HERE/state" \
  -H "X-Casambi-Session:SESSION-ID-HERE" \
  -H "X-Casambi-Key:API-KEY-HERE"

Response Example

{
    "id": 18,
    "address": "dfe579c30e4f",
    "name": "TestUnit",
    "image": "456ghkOxsfuE6GTR6utJl8OEAPkSqh",
    "position": 4,
    "fixtureId": 16574,
    "firmwareVersion": "32.10",
    "groupId": 0,
    "priority": 3,
    "scene": 0,
    "online": true,
    "condition": 134,
    "status": "status_message",
    "activeSceneId": 4,
    "controls": [
        [
            {
                "type": "Dimmer",
                "value": 1
            },
            {
                "source": "XY",
                "type": "Colorsource"
            },
            {
                "x": 0.14753297508549096,
                "y": 0.13727405959941377,
                "rgb": "rgb(136, 255, 255)",
                "type": "Color"
            },
            {
                "tw": 23.52941,
                "min": 2700,
                "max": 6000,
                "type": "CCT",
                "value": 6000,
                "level": 1
            }
        ]
    ],
    "dimLevel": 1,
    "type": "Luminaire"
}

Request Network State

Retrieves information of current network state identified by network ID, requires use of API key and sessionId (Header: X-Casambi-Key, X-Casambi-Session). Related unit information is similar to one received along with WebSocket unitChanged events. Note that if unit is part of a group (groupId > 0) it will have position value of 0 as the actual position within the group will be found in related group information.

HTTP Request:

GET https://door.casambi.com/v1/networks/{networkId}/state

Path Parameters:

networkId: "networkId"

CURL Example:

curl "https://door.casambi.com/v1/networks/NETWORK-ID-HERE/state" \
  -H "X-Casambi-Session:SESSION-ID-HERE" \
  -H "X-Casambi-Key:API-KEY-HERE"

Response Example

{
    "id": "VcrTwqLZJ26UYMXxTClmpfZxELcrPUAa",
    "name": "Demo Room",
    "revision": 125,
    "grade": "EVOLUTION",
    "address": "b02ef7956bcc",
    "gateway": {
        "name": "Demo iPad"
    },
    "type": "OPEN",
    "timezone": "Europe/Helsinki",
    "dimLevel": 0.5,
    "activeScenes": [3, 4],
    "photos": [
        {
            "name": "Photo",
            "controls": [],
            "image": "iR4aIP3vXcB348Pijif2d4Y7AnowFbdD",
            "position": 0
        }
    ],
    "units": {
        "15": {
            "id": 15,
            "address": "44363c069a45",
            "name": "Sensor Z",
            "position": 4,
            "fixtureId": 45602,
            "firmwareVersion": "32.10",
            "groupId": 0,
            "priority": 0,
            "scene": 0,
            "online": false,
            "condition": 0,
            "status": "ok",
            "activeSceneId": 0,
            "controls": [
                [
                    {
                        "type": "Presence",
                        "status": "absent"
                    },
                    {
                        "level": 0,
                        "type": "Lux",
                        "value": 0
                    },
                    {
                        "type": "Switch"
                    }
                ]
            ],
            "dimLevel": 0,
            "type": "Sensor"
        },
        "18": {
            "id": 18,
            "address": "dfe579c30c88",
            "name": "TestUnit",
            "image": "456ghkOxsfuE6GTR6utJl8OEAPkSqh",
            "position": 4,
            "fixtureId": 16574,
            "firmwareVersion": "32.10",
            "groupId": 0,
            "priority": 3,
            "scene": 0,
            "online": true,
            "condition": 134,
            "status": "status_message",
            "activeSceneId": 4,
            "controls": [
                [
                    {
                        "type": "Dimmer",
                        "value": 1
                    },
                    {
                        "source": "XY",
                        "type": "Colorsource"
                    },
                    {
                        "x": 0.14753297508549096,
                        "y": 0.13727405959941377,
                        "rgb": "rgb(136, 255, 255)",
                        "type": "Color"
                    },
                    {
                        "tw": 23.52941,
                        "min": 2700,
                        "max": 6000,
                        "type": "CCT",
                        "value": 6000,
                        "level": 1
                    }
                ]
            ],
            "dimLevel": 1,
            "type": "Luminaire"
        }
    },
    "scenes": {
        "1": {
            "name": "Timer",
            "id": 1,
            "position": 0,
            "icon": 0,
            "color": "#FFFFFF",
            "type": "REGULAR",
            "hidden": false,
            "units": {
                "12": {
                    "id": 12
                }
            }
        }
    },
    "groups": {
        "3": {
            "id": 3,
            "name": "Demo Group",
            "position": 2,
            "units": [
                {
                    "0": 12,
                    "position": 0
                }
            ]
        }
    }
}

Request Network Groups

Retrieves information of groups in network identified by network ID, requires use of API key and sessionId (Header: X-Casambi-Key, X-Casambi-Session).

HTTP Request:

GET https://door.casambi.com/v1/networks/{id}/groups

Path Parameters:

id: "networkId"

CURL Example:

curl "https://door.casambi.com/v1/networks/NETWORK-ID-HERE/groups" \
  -H "X-Casambi-Session:SESSION-ID-HERE" \
  -H "X-Casambi-Key:API-KEY-HERE"

Response Example

{
    "3": {
        "id": 3,
        "name": "Demo Group",
        "position": 2,
        "units": [
            {
                "id": 12,
                "position": 0
            }
        ]
    }
}

Request Network Scenes

Retrieves information of scenes in network identified by network ID, requires use of API key and sessionId (Header: X-Casambi-Key, X-Casambi-Session).

HTTP Request:

GET https://door.casambi.com/v1/networks/{id}/scenes

Path Parameters:

id: "networkId"

CURL Example:

curl "https://door.casambi.com/v1/networks/NETWORK-ID-HERE/scenes" \
  -H "X-Casambi-Session:SESSION-ID-HERE" \
  -H "X-Casambi-Key:API-KEY-HERE"

Response Example

{
    "1": {
        "name": "Timer",
        "id": 1,
        "position": 0,
        "icon": 0,
        "color": "#FFFFFF",
        "type": "REGULAR",
        "hidden": false,
        "units": {
            "12": {
                "id": 12
            }
        }
    },
    "4": {
        "name": "Presence",
        "id": 2,
        "position": 1,
        "icon": 0,
        "color": "#06FF29",
        "type": "REGULAR",
        "hidden": false,
        "units": {
            "18": {
                "id": 18
            }
        }
    }
}

Request Network Datapoints

Retrieves list of sensor data (sensor/luminaire) in network identified by network ID and filtered by data type or data keys and time range. Additionally can be filtered by unit id's as well (optional). Requires use of API key and sessionId (Header: X-Casambi-Key, X-Casambi-Session). Filtering parameters from and to are mandatory.

By default time range params and response time values are in UTC timezone. Time range value is given as a date with or without hours, minutes and seconds or as ISO 8601 formatted value. Note that the request URL is expected to be URL encoded. In most queries this doesn't make a difference, but at least when using a timezone offset like "+01:00" then the + character needs to be encoded, or otherwise the query will be considered invalid.

The hasMoreResults response field shall be true if the results were truncated because of an implicit or explicit limit option and more results would be available on the server for the same query with a higher limit, false otherwise.

Note that datapoint data is stored only for 60 days. If given filter values are invalid or mandatory value is missing will return HTTP status code 400 - Bad Request.

HTTP Request:

GET https://door.casambi.com/datapoints/networks/{id}/datapoints?{filterOptions}

Path Parameters:

id: "networkId"

Filter Options:

dataType: one or more of the following separated by a comma: sensors, vendor, control, energy, details, status
keys:     one or more of the following separated by a comma: dimmer, lux, presence, battery_level, ...
units:    one or more unit identifiers separated by a comma and optionally enclosed in brackets (optional)
from:     yyyyMMdd[hh[mm[ss[fff]]]] | ISO 8601 format: yyyy-MM-dd[Thh:mm[:ss[.fff]]][tz]
to:       yyyyMMdd[hh[mm[ss[fff]]]] | ISO 8601 format: yyyy-MM-dd[Thh:mm[:ss[.fff]]][tz]
limit:    Upper limit on the number of datapoints to return (optional, default is 10000 if omitted, allowed values 1-100000)

Changes

01.12.2022: introduced as a new version of the datapoints query endpoint.
04.09.2024: is now only available datapoint query endpoint.

CURL Example:

curl "https://door.casambi.com/datapoints/networks/NETWORK-ID-HERE/datapoints?dataType=status&from=20210206&to=20210208" \
  -H "X-Casambi-Session:SESSION-ID-HERE" \
  -H "X-Casambi-Key:API-KEY-HERE"

Response Example

{
    "resultCount": 3,
    "queryLimit": 10000,
    "processingTimeMs": 32,
    "hasMoreResults": false,
    "errors": "",
    "dataPoints": [
        {
            "unit": 3,
            "key": "priority",
            "value": "3",
            "time": "2022-10-31T08:45:02.685+00:00"
        },
        {
            "unit": 3,
            "key": "condition",
            "value": "ok",
            "time": "2022-10-31T08:45:02.685+00:00"
        },
        {
            "unit": 5,
            "key": "priority",
            "value": "3",
            "time": "2022-10-31T08:45:02.774+00:00"
        }
    ]
}

note

The "time" values within response data are in UTC. Datapoint data is stored only for 60 days, after that it will be deleted.

Request Network Unit Icon

Retrieve unit icon (or fixture icon if unit image not set) identified by network and unit ID, requires use of API key and sessionId (Header: X-Casambi-Key, X-Casambi-Session). Will return image blob data in png format or HTTP status 404 Not found.

HTTP Request:

GET https://door.casambi.com/v1/networks/{networkId}/units/{unitId}/icon

Path Parameters:

networkId: "networkId"
unitId: unitId

CURL Example:

curl "https://door.casambi.com/v1/networks/NETWORK-ID-HERE/units/UNIT-ID-HERE/icon" \
  -H "X-Casambi-Session:SESSION-ID-HERE" \
  -H "X-Casambi-Key:API-KEY-HERE"

Response: Image blob data in png format.

Request Network Gallery

Retrieves gallery information (photo list) of network identified by network ID, requires use of API key and sessionId (Header: X-Casambi-Key, X-Casambi-Session).

HTTP Request:

GET https://door.casambi.com/v1/networks/{id}/gallery

Path Parameters:

id: "networkId"

CURL Example:

curl "https://door.casambi.com/v1/networks/NETWORK-ID-HERE/gallery" \
  -H "X-Casambi-Session:SESSION-ID-HERE" \
  -H "X-Casambi-Key:API-KEY-HERE"

Response Example

[
    {
        "name": "Photo",
        "controls": [],
        "image": "iR4aIP3vXcB348Pijif2d4Y7AnowFbdD",
        "position": 0
    },
    {
        "name": "Photo",
        "controls": [],
        "image": "KLejfitLiEFeiUnhak6ID69VzJhvWYER",
        "position": 1
    }
]

Request Network Image

Retrieves image identified by network and image ID, requires use of API key and sessionId (Header: X-Casambi-Key, X-Casambi-Session). Will return image blob data in png format or HTTP status 404 Not found.

HTTP Request:

GET https://door.casambi.com/v1/networks/{networkId}/images/{imageId}

Path Parameters:

networkId: "networkId"
imageId: "imageId"

CURL Example:

curl "https://door.casambi.com/v1/networks/NETWORK-ID-HERE/images/IMAGE-ID-HERE" \
  -H "X-Casambi-Session:SESSION-ID-HERE" \
  -H "X-Casambi-Key:API-KEY-HERE"

Response: Image blob data in png format.

Request Fixture Information

Retrieves fixture information identified by fixture ID, requires use of API key (Header: X-Casambi-Key).

HTTP Request:

GET https://door.casambi.com/v1/fixtures/{id}

Path Parameters:

id: fixtureId

CURL Example:

curl "https://door.casambi.com/v1/fixtures/FIXTURE-ID-HERE" \
  -H "X-Casambi-Session:SESSION-ID-HERE" \
  -H "X-Casambi-Key:API-KEY-HERE"

Response Example

{
    "id": 23456,
    "type": "Driver",
    "vendor": "Oktalite Lichttechnik GmbH",
    "model": "Oktalite AGIRA PLUS",
    "translations": {},
    "controls": [
        {
            "type": "button",
            "name": "Button",
            "buttonLabel": "Button",
            "dataname": "button",
            "id": 0,
            "readonly": true
        },
        {
            "type": "dimmer",
            "id": 1,
            "readonly": false
        },
        {
            "type": "rgb",
            "id": 7,
            "readonly": false
        },
        {
            "type": "temperature",
            "id": 25,
            "readonly": false
        },
        {
            "type": "colorsource",
            "id": 31,
            "readonly": false
        },
        {
            "type": "slider",
            "name": "Slider",
            "unit": "",
            "id": 33,
            "readonly": false,
            "valueType": "FLOAT"
        }
    ]
}

Request Fixture Icon

Retrieves fixture icon identified by fixture ID, requires use of API key (Header: X-Casambi-Key). Will return image blob data in png format or HTTP status 404 Not found.

HTTP Request:

GET https://door.casambi.com/v1/fixtures/{id}/icon

Path Parameters:

id: fixtureId

CURL Example:

curl "https://door.casambi.com/v1/fixtures/FIXTURE-ID-HERE/icon" \
  -H "X-Casambi-Session:SESSION-ID-HERE" \
  -H "X-Casambi-Key:API-KEY-HERE"

Response: Image blob data in png format.

Response Information

All request response data are in JSON object or array format except for image requests which will return image blob data in png format instead. If request was not successful will return HTTP status error code.

Successful request response data examples are listed with relevant endpoint definitions.

With valid API key you can test requests (and responses) with API web console.

Position Info

The view position of device, photos and scenes (used in Casambi App) are given as numeric value, where smaller position number should be shown first in the order and so forth. Note that there might be gaps between the position values. Also items like sensors and similar that are not shown within the Casambi App network luminaires view may have same position number as some group or device that is shown in the luminaires view.

Exception to this ordering is that if device (item of units list) is part of a group (groupId > 0) it will have its position value always set to 0 as the actual position within the related group will be found in the group information. See groups list of network data to find the actual position info of the group and its devices. Positioning of devices and groups used in Casambi App is only given as a reference and use of this info is fully optional.

Response Status Codes

200	Request OK.
400	Bad request, given parameters invalid.
401	Unauthorized. Invalid API key or credentials given.
403	Api not enabled by Casambi administrator or trying to create session after failed attempt too soon.
404	Requested data not found.
405	Method not allowed.
410	Invalid session.
416	Retrieval interval is too long.
429	Quota limits exceeded.
500	Server error.

JavaScript Examples (Axios)

Here are javascript (ES6) code examples how client can authenticate and then use API endpoints to receive information.

Example code uses axios for API requests. More information: https://github.com/axios/axios.

Creating (site) user session

const api_key = "API-KEY-HERE";
const login = {
	"email": "EMAIL-ADDRESS-HERE",
	"password": "PASSWORD-HERE",
};

axios.post("https://door.casambi.com/v1/users/session/", { ...login }, {
	headers: { "X-Casambi-Key": api_key }
}).then(response => {
	console.log(response.data);

	const session_data = response.data;
	const session_id = session_data.sessionId;

	for (let network in session_data) {
		const network_id = network.id;
		const network_name = network.name;
	}

	for (let site in session_data) {
		const networks = site.networks;
	}

	// Use session_id for further API requests..

}).catch(error => {
	console.log(error);

	if (error.response && error.response.status === 401) {
		if ("statusText" in error.response
			&& error.response.statusText === "Api authorization failed.") {
			// Given API key is invalid!
		} else {
			// User not found!
		}
	} else if (error.response) {
		// See error.response && status
	}
});

Creating network (admin) session

const api_key = "API-KEY-HERE";
const login = {
	"email": "EMAIL-ADDRESS-HERE",
	"password": "PASSWORD-HERE",
};

axios.post("https://door.casambi.com/v1/networks/session/", { ...login }, {
	headers: { "X-Casambi-Key": api_key }
}).then(response => {
	console.log(response.data);

	const network_session_data = response.data;
	for (let network_id in network_session_data) {
		const session_id = network_session_data[network_id].sessionId;
		const network_name = network_session_data[network_id].name;

		// Use session_id for further API requests..
	}

}).catch(error => {
	console.log(error);

	if (error.response && error.response.status === 401) {
		if ("statusText" in error.response
			&& error.response.statusText === "Api authorization failed.") {
			// Given API key is invalid!
		} else {
			// Network user not found!
		}
	} else if (error.response) {
		// See error.response && status
	}
});

Fetch network information

const api_key = "API-KEY-HERE";
const session_id = "SESSION-ID-HERE";
const network_id = "NETWORK-ID-HERE";

axios.get("https://door.casambi.com/v1/networks/" + network_id, {
	headers: { "X-Casambi-Session": session_id, "X-Casambi-Key": api_key }
}).then(response => {
	console.log(response.data);

	const network = response.data;
	const network_id = network.id;
	const network_name = network.name;
	const devices = network.units;
	const groups = network.groups;
	const scenes = network.scenes;

	// network info including information about groups, devices, scenes (if any)..

}).catch(error => {
	console.log(error);
});

Fetch unit state

const api_key = "API-KEY-HERE";
const session_id = "SESSION-ID-HERE";
const network_id = "NETWORK-ID-HERE";
const device_id = "DEVICE-ID-HERE";

axios.get("https://door.casambi.com/v1/networks/" + network_id + "/units/" + device_id + "/state", {
	headers: { "X-Casambi-Session": session_id, "X-Casambi-Key": api_key }
}).then(response => {
	console.log(response.data);

	const device = response.data;
	const device_id = device.id;
	const device_status = device.status;
	const device_dim_level = device.dimLevel;
	const device_controls = device.controls;

	// device info including information about status, fixture, controls (dim, color temperature, color etc. if any)..

}).catch(error => {
	console.log(error);
});

Fetch network state

const api_key = "API-KEY-HERE";
const session_id = "SESSION-ID-HERE";
const network_id = "NETWORK-ID-HERE";

axios.get("https://door.casambi.com/v1/networks/" + network_id + "/state", {
	headers: { "X-Casambi-Session": session_id, "X-Casambi-Key": api_key }
}).then(response => {
	console.log(response.data);

	const network = response.data;
	const network_id = network.id;
	const network_name = network.name;
	const devices = network.units;
	const groups = network.groups;
	const scenes = network.scenes;
	const dim_level = network.dimLevel;
	const active_scene_ids = network.activeScenes;

	for (let device in devices) {
		const device_id = device.id;
		const device_status = device.status;
		const device_dim_level = device.dimLevel;
		const device_controls = device.controls;

		// device info including information about status, fixture, controls (dim, color temperature, color etc. if any)..
	}

	// network info including information about groups, device states, scenes (if any)..

}).catch(error => {
	console.log(error);
});

Fetch datapoints

const api_key = "API-KEY-HERE";
const session_id = "SESSION-ID-HERE";
const network_id = "NETWORK-ID-HERE";

// Note that filter options are mandatory for datapoints requests. In addition optional units value can be used as well.
// Time range and datatype (or keys) value must be given. Note that datapoint data is stored only for 60 days.
// Time range parameters and response time values are always in UTC.

const filter_options = {
	"dataType": "control,status",
	"keys": "dimmer,lux",
	"units": "15,22",
	"from": 201907221013,
	"to": 201907290431,
	"limit": 20000
};
const query_params = Object.keys(filter_options).map(key => key + '=' + encodeURIComponent(filter_options[key])).join('&');

axios.get("https://door.casambi.com/datapoints/networks/" + network_id + "/datapoints?" + query_params, {
	headers: { "X-Casambi-Session": session_id, "X-Casambi-Key": api_key }
}).then(response => {
	console.log(response.data);

	const datapoints = response.data;

	// Datapoints result in JSON object, please refer to the Response Example in the endpoint definition for more info...

}).catch(error => {
	console.log(error);
});

Fetch image

const api_key = "API-KEY-HERE";
const session_id = "SESSION-ID-HERE";
const network_id = "NETWORK-ID-HERE";
const image_id = "IMAGE-ID-HERE";

axios.get("https://door.casambi.com/v1/networks/" + network_id + "/images/" + image_id, {
	headers: { "X-Casambi-Session": session_id, "X-Casambi-Key": api_key}, "responseType": "arraybuffer"
}).then(response => {
	console.log(response.data);

	const bytes = new Uint8Array(response.data);
	const binary = bytes.reduce((data, byte) => data + String.fromCharCode(byte), '');
	const image_src = "data:image/png;base64," + btoa(binary);

	// use image_src to show the image with img html element..

}).catch(error => {
	console.log(error);
});

JavaScript Examples (XmlHttp)

Here are javascript (ES6) examples how client can authenticate and then use API endpoints to receive information.

Example code uses XmlHttp for API requests. More information: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest.

Creating (site) user session

const api_key = "API-KEY-HERE";
const login = {
	"email": "EMAIL-ADDRESS-HERE",
	"password": "PASSWORD-HERE",
};

const xmlhttp = new XMLHttpRequest();
xmlhttp.open("POST", "https://door.casambi.com/v1/users/session", "true");
xmlhttp.setRequestHeader("X-Casambi-Key", api_key);
xmlhttp.setRequestHeader("Content-Type", "application/JSON");
xmlhttp.onload = function () {
	console.log(JSON.parse(this.responseText), this.status, this.statusText);

	const user_session_data = JSON.parse(this.responseText);
	const session_id = user_session_data.sessionId;

	for (let network in user_session_data) {
		const network_id = network.id;
		const network_name = network.name;
	}

	for (let site in user_session_data) {
		const networks = site.networks;
	}
};
xmlhttp.send(JSON.stringify(login));

Creating network (admin) session

const api_key = "API-KEY-HERE";
const login = {
	"email": "EMAIL-ADDRESS-HERE",
	"password": "PASSWORD-HERE",
};

const xmlhttp = new XMLHttpRequest();
xmlhttp.open("POST", "https://door.casambi.com/v1/networks/session", "true");
xmlhttp.setRequestHeader("X-Casambi-Key", api_key);
xmlhttp.setRequestHeader("Content-Type", "application/JSON");
xmlhttp.onload = function () {
	console.log(JSON.parse(this.responseText), this.status, this.statusText);

	const network_session_data = JSON.parse(this.responseText);
	for (let network_id in network_session_data) {
		const session_id = network_session_data[network_id].sessionId;
		const network_name = network_session_data[network_id].name;

		// Use session_id for further API requests..
	}
};
xmlhttp.send(JSON.stringify(login));

Fetch network information

const api_key = "API-KEY-HERE";
const session_id = "SESSION-ID-HERE";
const network_id = "NETWORK-ID-HERE";

const xmlhttp = new XMLHttpRequest();
xmlhttp.open("GET", "https://door.casambi.com/v1/networks/" + network_id);
xmlhttp.setRequestHeader("X-Casambi-Session", session_id);
xmlhttp.setRequestHeader("X-Casambi-Key", api_key);
xmlhttp.onload = function () {
	console.log(JSON.parse(this.responseText), this.status, this.statusText);

	const network = JSON.parse(this.responseText);
	const network_id = network.id;
	const network_name = network.name;
	const devices = network.units;
	const groups = network.groups;
	const scenes = network.scenes;

	// network info including information about groups, devices, scenes (if any)..
};
xmlhttp.send();

Fetch unit state

const api_key = "API-KEY-HERE";
const session_id = "SESSION-ID-HERE";
const network_id = "NETWORK-ID-HERE";
const device_id = "DEVICE-ID-HERE";

const xmlhttp = new XMLHttpRequest();
xmlhttp.open("GET", "https://door.casambi.com/v1/networks/" + network_id + "/units/" + device_id + "/state");
xmlhttp.setRequestHeader("X-Casambi-Session", session_id);
xmlhttp.setRequestHeader("X-Casambi-Key", api_key);
xmlhttp.onload = function () {
	console.log(JSON.parse(this.responseText), this.status, this.statusText);

	const device = JSON.parse(this.responseText);
	const device_id = device.id;
	const device_status = device.status;
	const device_dim_level = device.dimLevel;
	const device_controls = device.controls;

	// device info including information about status, fixture, controls (dim, color temperature, color etc. if any)..
};
xmlhttp.send();

Fetch network state

const api_key = "API-KEY-HERE";
const session_id = "SESSION-ID-HERE";
const network_id = "NETWORK-ID-HERE";

const xmlhttp = new XMLHttpRequest();
xmlhttp.open("GET", "https://door.casambi.com/v1/networks/" + network_id + "/state");
xmlhttp.setRequestHeader("X-Casambi-Session", session_id);
xmlhttp.setRequestHeader("X-Casambi-Key", api_key);
xmlhttp.onload = function () {
	console.log(JSON.parse(this.responseText), this.status, this.statusText);

	const network = JSON.parse(this.responseText);
	const network_id = network.id;
	const network_name = network.name;
	const devices = network.units;
	const groups = network.groups;
	const scenes = network.scenes;
	const dim_level = network.dimLevel;
	const active_scene_ids = network.activeScenes;

	for (let device in devices) {
		const device_id = device.id;
		const device_status = device.status;
		const device_dim_level = device.dimLevel;
		const device_controls = device.controls;

		// device info including information about status, fixture, controls (dim, color temperature, color etc. if any)..
	}

	// network info including information about groups, device states, scenes (if any)..
};
xmlhttp.send();

Fetch datapoints

const api_key = "API-KEY-HERE";
const session_id = "SESSION-ID-HERE";
const network_id = "NETWORK-ID-HERE";

// Note that filter options are mandatory for datapoints requests. In addition optional units value can be used as well.
// Time range and datatype (or keys) value must be given. Note that datapoint data is stored only for 60 days.
// Time range parameters and response time values are always in UTC.

const filter_options = {
	"dataType": "control,status",
	"keys": "dimmer,lux",
	"units": "15,22",
	"from": 201907221013,
	"to": 201907290431,
	"limit": 20000
};
const query_params = Object.keys(filter_options).map(key => key + '=' + encodeURIComponent(filter_options[key])).join('&');

xmlhttp = new XMLHttpRequest();
xmlhttp.open("GET", "https://door.casambi.com/datapoints/networks/" + network_id + "/datapoints?" + query_params);
xmlhttp.setRequestHeader("X-Casambi-Session", session_id);
xmlhttp.setRequestHeader("X-Casambi-Key", api_key);
xmlhttp.onload = function () {
	console.log(JSON.parse(this.responseText), this.status, this.statusText);

	const datapoints = JSON.parse(this.responseText);

	// Datapoints result in JSON object, please refer to the Response Example in the endpoint definition for more info...
};
xmlhttp.send();

Fetch image

const api_key = "API-KEY-HERE";
const session_id = "SESSION-ID-HERE";
const network_id = "NETWORK-ID-HERE";
const image_id = "IMAGE-ID-HERE";

const xmlhttp = new XMLHttpRequest();
xmlhttp.open("GET", "https://door.casambi.com/v1/networks/" + network_id + "/images/" + image_id);
xmlhttp.setRequestHeader("X-Casambi-Session", session_id);
xmlhttp.setRequestHeader("X-Casambi-Key", api_key);
xmlhttp.responseType = "arraybuffer";
xmlhttp.onload = function () {
	console.log(this.response, this.status, this.statusText);

	const bytes = new Uint8Array(this.response);
	const binary = bytes.reduce((data, byte) => data + String.fromCharCode(byte), '');
	const image_src = "data:image/png;base64," + btoa(binary);

	// use image_src to show the image with img html element..
};
xmlhttp.send();

Overview​

Version History​

Recent Changes​

Getting Started​

API Authentication​

Overview​

API Key Use Limits​

Authentication endpoints​

Create user session​

Create Network Session(s)​

Create Network Session Set​

Create Session for Network​

Using Created Session​

Endpoint definitions​

Request Network Information​

Request Network Unit List​

Request Network Unit State​

Request Network State​

Request Network Groups​

Request Network Scenes​

Request Network Datapoints​

Request Network Unit Icon​

Request Network Gallery​

Request Network Image​

Request Fixture Information​

Request Fixture Icon​

Response Information​

Position Info​

Response Status Codes​

JavaScript Examples (Axios)​

JavaScript Examples (XmlHttp)​

Overview

Version History

Recent Changes

Getting Started

API Authentication

Overview

API Key Use Limits

Authentication endpoints

Create user session

Create Network Session(s)

Create Network Session Set

Create Session for Network

Using Created Session

Endpoint definitions

Request Network Information

Request Network Unit List

Request Network Unit State

Request Network State

Request Network Groups

Request Network Scenes

Request Network Datapoints

Request Network Unit Icon

Request Network Gallery

Request Network Image

Request Fixture Information

Request Fixture Icon

Response Information

Position Info

Response Status Codes

JavaScript Examples (Axios)

JavaScript Examples (XmlHttp)