About The API

When the word “can” is used, this implies that the inclusion is optional.
When the word “must” is used, this implies that the inclusion is mandatory.
In order to create a client for the iBricks Cloud API, a client id and secret are required. If you want to create a client which will access the iBricks Cloud API, please contact us at mail@ibricks.ch.

Request Guidelines

Initial Pairing

https://myibricks.com/id/connect/authorize
See https://openid.net/specs/openid-connect-core-1_0.html

Security

Each request to the API must include a bearer token, otherwise the API will return a 401 (unauthorized).
The bearer token is added into the header of the request “Authorization”, “Bearer eyJhbG{RETRACTED}”
A bearer token always starts with “ey”. The bearer token can be retrieved using the default OPENID connection path
https://myibricks.com/v1/id/connect/token

Structure

The requests are all structured following the same logic.
The base URL is: https://myibricks.com/api/v1/
The main separator is the HouseBase, a HouseBase contains all the actors and sensors of a home.
Users can have multiple HouseBases available to them, they may have created some themselves and may have had others shared with them. This can be done on the iBricks Cloud Portal.
https://www.myibricks.com/Manage Making the request https://myibricks.com/api/v1/housebases will return all HouseBases available to the user which has been linked with your requesting client.

Get requests

Get requests can append the following parameters to the request, please note that these parameters are ignored when requesting a single element. The Get request returns the requested element(s) or an ErrorApi item.

Parameter	Value	Required	Default
limit	0 - 10000	No	100
offset	0 - 10000	No	0

Put requests

In order to change the state of an actor, you must use PUT requests, the body should contain json formatted the values you want to adjust. The Put Request Response contains the actor which was modified, or an ErrorApi Item.

Base Api Item

This is the root API Item, each response contains these parameters.

Parameter	Value Type	Comments
ID	string	Contains the relative ID (which may not be used as a unique identifier)
UniqueID	string	Contains the absolute ID (which may be used as a unique identifier)
Type	string	The Type of the device
ApiType	enum	The API type
		0 (Unknown)= Not set or request not known
		1 (Discovery)= Find request
		2 (Sync)= Sync request
		3 (Query)= Get state request
		4 (Execute)= Set state request
		5 (Error)= something went wrong with the request
Version	int	The API version
Attributes	string array	Custom attributes may be returned here
CustomData	string array	Custom data may be returned here
Links	Array of Links	Contains links relevant to the object
		rel = helper string what the link is
		href = the url (relative)
createTimeUTC	DateTime	Contains a DateTime in UTC when the item was created

Errors

The iBricks Cloud API can return several errors, depending on the nature of the request, and where the error occurred. All of these errors are returned using the Error reply item; which returns a JSON structured object which contains the following information:

Parameter	Value Type	Comments
ErrorMsg	string	Contains a plaintext error message
StatusCode	HttpStatusCode	Contains the corresponding HTTP status code correlating to error

HouseBases (Homes)

The main separator is the HouseBase, a HouseBase contains all the actors and sensors of a home. Users can have multiple HouseBases available to them, they may have created some themselves and may have had others shared with them.

Parameters

Parameter	Value Type	Comments
MasterEmail	string	Who is the master of the HouseBase
MasterGuid	GUID	The GUID of the Master
Name	string	The Name of the HouseBase, maybe be used as display name

Get
api/v1/housebases/{XXXX}/Housebases/ –> get all housebases

Get Single
api/v1/housebases/{XXXX}/housebases/{id} –> get specific housebase

Sample Return

  [
  {
      "masterEmail": "test1@ibricks.ch",
      "masterId": "bc3d67fd-811b-4b27-93c0-4ec0d1eceb46",
      "name": "Cello Testkoffer 2",
      "id": "e6592e14-2ebc-48c7-990f-505e42ab17ac",
      "uniqueId": "e6592e14-2ebc-48c7-990f-505e42ab17ac",
      "type": null,
      "version": "1",
      "apiType": 0,
      "attributes": null,
      "customData": null,
      "links": [
          {
              "rel": "self",
              "href": "/api/v1/housebases/e6592e14-2ebc-48c7-990f-505e42ab17ac"
          },
          {
              "rel": "switches",
              "href": "/api/v1/housebases/e6592e14-2ebc-48c7-990f-505e42ab17ac/switches"
          },
          {
              "rel": "dimmers",
              "href": "/api/v1/housebases/e6592e14-2ebc-48c7-990f-505e42ab17ac/dimmers"
          },
          {
              "rel": "shutters",
              "href": "/api/v1/housebases/e6592e14-2ebc-48c7-990f-505e42ab17ac/shutters"
          },
          {
              "rel": "meteos",
              "href": "/api/v1/housebases/e6592e14-2ebc-48c7-990f-505e42ab17ac/meteos"
          },
          {
              "rel": "directors",
              "href": "/api/v1/housebases/e6592e14-2ebc-48c7-990f-505e42ab17ac/directors"
          },
          {
              "rel": "scenes",
              "href": "/api/v1/housebases/e6592e14-2ebc-48c7-990f-505e42ab17ac/scenes"
          }
      ],
      "createTimeUTC": "2020-02-17T08:07:19.6332894Z"
  }
  ]

Directors

Directors are single setpoint actors which control temperature.

Parameters

Parameter	Value Type	Comments
TemperatureScale	string	The scale of temperature (only °C is currently supported)
SupportedModes	List<String>	All modes that the director supports (eg. ‘Heating’ ‘Cooling’)
SelectedMode	string	The current mode of the director

Get
api/v1/housebases/{XXXX}/directors/ –> get all directors

Get Single
api/v1/housebases/{XXXX}/directors/{id} –> get specific director

Put
api/v1/housebases/{XXXX}/directors/{id} –> Set director value

Put allows you to change the desired value of the director

Parameter	Value	Required	Comments
value	-100 ↔ 100	No
type	{‘relative’, ‘absolute’}	No	relative → change degree relative to current setpoint. absolute –> set absolute temperature
setMode	{‘COOL, ‘HEAT’}	No	Changes the mode of the director, if the director supports mode swithching
scale	{‘CELSIUS’}	No	Only Celsius is currently supported

Example PUT request:

{ “value”: “18”, “type”: “absolute” }
{ “value”: ”-2“, “type”: “relative” }

Example return from API

  {
  "temperatureScale": "CELSIUS",
  "supportedModes": [
      "HEAT",
      "COOL"
  ],
  "selectedMode": "HEAT",
  "displayName": "Thermostat Wohnzimmer",
  "manufacturer": null,
  "exists": true,
  "willReportState": false,
  "retrievable": true,
  "value": "19",
  "id": "cello_director_84F3EBA174FF",
  "uniqueId": "a80ef48f-8123-4df0-b440-cbe2b74f789d--Dir--cello_director_84F3EBA174FF",
  "type": null,
  "version": "1",
  "apiType": 0,
  "attributes": null,
  "customData": null,
  "links": [
      {
          "rel": "self",
          "href": "/api/v1/housebases/a80ef48f-8123-4df0-b440-cbe2b74f789d/directors/cello_director_84F3EBA174FF"
      }
  ]
  }

Dimmers

Dimmers are dimmable lamps. These can also be Color Dimmers or Color temperature dimmers.

Parameters

Parameter	Value Type	Comments
IsDimmable	bool	True = Can be dimmed
IsColor	bool	True = Has rgb color capabilities
IsTunableWhite	bool	True = Has color temperature capabilities
Value	floating number	Brightness in % (0-100%)
ProcValue	floating number	Desired Brightness in % (0-100%)
Color	Color	rgb color
ColorTemperature	integer	the color temperature in Kelvin
ProcColorTemperature	integer	the desired color temperature in Kelvin
MinColorTemperature	integer	the minimum supported color temperature in Kelvin
MaxColorTemperature	integer	the maximum supported color temperature in Kelvin
MyLightType	enum	The type of dimmer (0 =Unknown, 1= Switch dimmer , 2= Dimmer)

Get

api/v1/housebases/{XXXX}/dimmers/ –> get all dimmers

Get Single
api/v1/housebases/{XXXX}/dimmers/{id} –> get specific dimmer

Put
api/v1/housebases/{XXXX}/dimmers/{id} –> Set dimmer value
Put allows you to change the desired value of the dimmer

Parameter	Value	Required	Comments
value	-100 ↔ 100	No	Dimmer value in percentage (0-100)
type	{‘absolute’, ‘relative’, ‘OnX’, ‘On’ ‘Off’, ‘color’, ‘ct’}	No	Relative = Change dimmer value based on current brightness
			OnX = Turn on with last set brightness
			On = Turn on full brightness
			Off = Turn off
			Color = Set color (requires saturation and hue)
			Ct = Set color temp (in kelvin)
			If Type is not passed, absolute dimmer value is assumed
hue	0.0 ↔ 360.0	No	floating number
saturation	0.0 ↔ 1.0	No	floating number

Example PUT request:

{ “value”: ”-20“, “type”: “relative” }

Example reply

  [
  {
      "isDimmable": true,
      "isColor": false,
      "value": 95.0,
      "procValue": 75.0,
      "color": "",
      "isTunableWhite": false,
      "colorTemperature": 0,
      "procColorTemperature": 0,
      "minColorTemperature": 0,
      "maxColorTemperature": 0,
      "myLightType": 2,
      "validValue": true,
      "displayName": "Holzsäule Dimmer",
      "manufacturer": null,
      "exists": true,
      "willReportState": false,
      "retrievable": true,
      "allowed": true,
      "id": "cello_dimmer_6001944B3695",
      "uniqueId": "e6592e14-2ebc-48c7-990f-505e42ab17ac--Di--cello_dimmer_6001944B3695",
      "type": null,
      "version": "1",
      "apiType": 0,
      "attributes": null,
      "customData": null,
      "links": [
          {
              "rel": "self",
              "href": "/api/v1/housebases/e6592e14-2ebc-48c7-990f-505e42ab17ac/dimmers/cello_dimmer_6001944B3695"
          }
      ],
      "createTimeUTC": "2020-02-17T08:39:35.9559446Z"
  }
  ]

Meteo

A meteo is a sensor device which can be used to retrieve measurable data from a sensor. This can be temperatures, wind speed, humidity etc.

Parameters

Parameter	Value Type	Comments
ValueType	string	The type of meteo (eg. “TEMP”, “WIND”)
ValueUnit	string	The Unit set to the meteo sensor
TemperatureScale	string	hard coded to “CELSIUS””

Get
api/v1/housebases/{XXXX}/meteo/ –> get all meteos

Get Single
api/v1/housebases/{XXXX}/meteos/{id} –> get specific meteo

Sample Return

  [
  {
      "valueType": "TEMP",
      "valueUnit": "°C",
      "temperatureScale": "CELSIUS",
      "displayName": "Wohnraum",
      "manufacturer": null,
      "exists": true,
      "willReportState": false,
      "retrievable": true,
      "allowed": true,
      "value": "22.73",
      "procValue": null,
      "id": "cello_TEMP_6001944B4FFF",
      "uniqueId": "e6592e14-2ebc-48c7-990f-505e42ab17ac--Me--cello_TEMP_6001944B4FFF",
      "type": null,
      "version": "1",
      "apiType": 0,
      "attributes": null,
      "customData": null,
      "links": [
          {
              "rel": "self",
              "href": "/api/v1/housebases/e6592e14-2ebc-48c7-990f-505e42ab17ac/meteos/cello_TEMP_6001944B4FFF"
          }
      ],
      "createTimeUTC": "2020-02-17T09:02:19.2036337Z"
  }
  ]

Scenes

Scenes contains N actors and can turn these on or off based on what has been configured.

Parameters

Parameter	Value Type	Comments
DisplayName	string	The Display name of the Scene
IsActive	bool	Not active yet, would return if Scene is currently running
DeviceIdsInScene	custom	A list of all devices in the scene, currently not implemented
sceneStatus	enum	the current scene status. Currently only returns TurningOn (3) and Turning Off(4) for requests. Otherwise 0 (Unknown) is returned.

Get
api/v1/housebases/{XXXX}/scenes/ –> get all scenes

Get Single
api/v1/housebases/{XXXX}/scenes/{id} –> get specific scene

Put
api/v1/housebases/{XXXX}/scenes/{id} –> Set scene value

Put allows you to change the desired value of the dimmer

Parameter	Value	Required	Comments
value	{0,1}	Yes	0 = Deactivate Scene
value	{0,1}	Yes	1 = Activate Scene

Example PUT request:

{ “value”: 1}

Example reply

   {
      "isActive": false,
      "description": "Oben Rechs",
      "sceneStatus": 0,
      "deviceIdsInScene": [],
      "id": "TopRight",
      "uniqueId": "e6592e14-2ebc-48c7-990f-505e42ab17ac--Sc--TopRight",
      "type": null,
      "version": "1",
      "apiType": 0,
      "attributes": null,
      "customData": null,
      "links": [
          {
              "rel": "self",
              "href": "/api/v1/housebases/e6592e14-2ebc-48c7-990f-505e42ab17ac/scenes/TopRight"
          }
      ],
      "createTimeUTC": "2020-02-18T07:43:01.8403462Z"
      }

Shutters

Parameters

Parameter	Value Type	Comments
Value	float	The current position of the shutter (in percent 0-100)
ProcValue	float	The desired position of the shutter (in percent 0-100)
ValueBlinds	float	The current position of the blinds
ProcValueBlinds	float	The desired position of the blinds
Direction	string	The direction of the shutter
HasBlinds	bool	Describes if the shutter has blinds (True=has blinds)

Get
api/v1/housebases/{XXXX}/shuters/ –> get all shutters

Get Single
api/v1/housebases/{XXXX}/shutters/{id} –> get specific shutter

Put
api/v1/housebases/{XXXX}/shutters/{id} –> Set shutter value

Put allows you to change the desired value of the dimmer

Parameter	Value	Required	Comments
value	-100 ↔ 100	No	Shutter value in percentage (0-100)
value	-100 ↔ 100	No	0 = completely open. 100 = completely closed
valueBlinds	-100 ↔ 100	No	Shutter blinds value in percentage (0-100)
valueBlinds	-100 ↔ 100	No	0 = completely open. 100 = completely closed
type	{‘relative’, ‘absolute, ‘Stop’ }	No	Relative = Change shutter / blinds value based on current position
			absolute = set absolute position in percentage of shutter /blinds
			Stop = Stop the shutter movement
			If Type is not passed, absolute shutter /blinds value is assumed

Example PUT request:

{ “value”: ”-20“, “type”: “relative” }

Example reply

   {
      "value": 255.0,
      "valueBlinds": 0.0,
      "procValueBlinds": 0.0,
      "procValue": 235.0,
      "direction": "",
      "hasBlinds": true,
      "displayName": "Küche",
      "manufacturer": null,
      "exists": true,
      "willReportState": false,
      "retrievable": true,
      "allowed": true,
      "id": "cello_shutter_60019458A075",
      "uniqueId": "e6592e14-2ebc-48c7-990f-505e42ab17ac--Sh--cello_shutter_60019458A075",
      "type": null,
      "version": "1",
      "apiType": 0,
      "attributes": null,
      "customData": null,
      "links": [
          {
              "rel": "self",
              "href": "/api/v1/housebases/e6592e14-2ebc-48c7-990f-505e42ab17ac/shutters/cello_shutter_60019458A075"
          }
      ],
      "createTimeUTC": "2020-02-18T07:55:55.5700797Z"
      }

Switches

Parameters

Parameter	Value Type	Comments
Value	float	The current position of the switch (0 = Off, 1 = On)
ProcValue	float	The desired position of the switch (0 = Off, 1 = On)
MyLightType	enum	The type of dimmer (0 =Unknown, 1= Switch dimmer , 2= Dimmer)

Get
api/v1/housebases/{XXXX}/switches/ –> get all switches

Get Single
api/v1/housebases/{XXXX}/switches/{id} –> get specific switch

Put
api/v1/housebases/{XXXX}/switches/{id} –> Set switch value

Put allows you to change the desired value of the dimmer

Parameter	Value	Required	Comments
value	{0,1}	Yes	1 = turn switch on
value	{0,1}	Yes	0 = turn switch off

Example PUT request:

{ “value”: “1”}

Example reply

   {
      "value": 0,
      "procValue": 1,
      "myLightType": 1,
      "validValue": true,
      "displayName": "Wohnzimmer",
      "manufacturer": null,
      "exists": true,
      "willReportState": false,
      "retrievable": true,
      "allowed": true,
      "id": "cello_relais_6001944B4FFF",
      "uniqueId": "e6592e14-2ebc-48c7-990f-505e42ab17ac--Re--cello_relais_6001944B4FFF",
      "type": null,
      "version": "1",
      "apiType": 0,
      "attributes": null,
      "customData": null,
      "links": [
          {
              "rel": "self",
              "href": "/api/v1/housebases/e6592e14-2ebc-48c7-990f-505e42ab17ac/switches/cello_relais_6001944B4FFF"
          }
      ],
      "createTimeUTC": "2020-02-18T07:55:02.1840292Z"
   }

iBricks DokuWiki

Sidebar

Table of Contents

About The API

Request Guidelines

Initial Pairing

Security

Structure

Get requests

Put requests

Base Api Item

Errors

HouseBases (Homes)

Parameters

Directors

Parameters

Dimmers

Parameters

Meteo

Parameters

Scenes

Parameters

Shutters

Parameters

Switches

Parameters

iBricks DokuWiki

User Tools

Site Tools

Sidebar

Table of Contents

About The API

Request Guidelines

Initial Pairing

Security

Structure

Get requests

Put requests

Base Api Item

Errors

HouseBases (Homes)

Parameters

Directors

Parameters

Dimmers

Parameters

Meteo

Parameters

Scenes

Parameters

Shutters

Parameters

Switches

Parameters

Page Tools