Get Started   Developer Account   My Applications   My IoTs   API Overview
  ALL   command   energy   entry   light   meteo   movement   security   sensor   surveillance
  ALL   access   active   alert   brightness   detect   dim   dock   hue   humidity   mode   operation   position   position_vertical   pressure   protection   record   rgb   ring   saturation   show   snapshot   speed   status   temperature   trigger   unlock   wind_angle   wind_strength
  Customize your UI

API Overview


This section describes important resources found in the API and how everything works together. It is important to understand how the Comfort Life ecosystem works to use it or to build new features for it.


Authorization

Authorization is a HTTP header used for most of the available API endpoints. It must be set to identify the end user for which targeted resources are requested. Refer to the API Documentation to know when this value is mandatory.

To retrieve the authorization, you may use one of the following methods :

  • To use the API for your own user account which email is the same as your Developer account email, you may set the authorization value to your Developer Key
  • To use the API for any user, you may set the authorization value to 'Bearer ' followed by its JWT. JWT are retrieved through OAuth2 protocol usage with your application declaration informations
  • To use the API in the sandbox, you may set the authorization value to the authorization value found in the login sandbox API endpoint here


User & Family

A user is a structured resource identifying a single end user. A family is a structured resource aggregating multiple users with different roles. A role defines authorization within a family.


Location

A location is a structured layer of resources owned by a family. A location is identified by a unique identifier called uid. A name can be set for a location to be displayed in the Comfort Life client.

A location is defined by a level. A location can be placed in another location if that location level is strictly higher, ordering locations in multiple layers. Available levels are ordered as follow, from the highest to the lowest :

  • plant : a plant uid is mandatory for most of the API endpoints requesting user resources
  • floor
  • zone : in the Comfort Life client, a zone corresponds to a room
  • ambient
  • space
  • module : a module encapsulates one of the following resources :
    • a device
    • a scenario
    • a service
    • a group

Systems

A system is a non-user related resource. It describes common features among sets of resources definition. Resources found in modules belong to at least one system. If an entity belongs to a system, it means it is implementing at least one of this system features.

You may find an exhaustive list of existing systems and how to use them here.


Capabilities

A capability is a non-user related resource. A capability is an action that can be performed on or by a resource. Capabilities are features found in systems. It means a module resource belonging to a system can implement capabilities instances from that system. A module resource capability instance may have a value, which is always a string. The value may be one of mandatory values for this capability called states.

You may find an exhaustive list of existing capabilities and how to use them here.


Model

A model is a non-user related resource. It identifies resources of the same type. A model is defined to belong to one or more systems.

Models can be requested thanks to the following API endpoint : 

https://sandbox.api.iotcl.pro/v1.0/models

Device

A device is a structured resource identifying a single device associated to an end user account. A device may be found as an encapsulated resource of a module. Each device has a model. It means a device implements capabilities from systems its model belong to.

You may target devices owned by a family for a request as follow (parenthesis mean it is optional) : 

https://sandbox.api.iotcl.pro/v1.0/<MODEL>/<SYSTEM>/addressLocation/plants/<PLANT_ID>/(<COAL>/parameter/<PARAMETER_KEY>/value/<PARAMETER_VALUE>/)

where :

  • MODEL : the unique identifier of the targeted device model
  • SYSTEM : the unique identifier of a targeted device system
  • PLANT_ID : the unique identifier of the plant of the family. If the route ends here, all locations of this family are affected by this request
  • COAL : level of the targeted location. Every devices found in modules below this location will be affected by the request
  • PARAMETER_KEY : key of the targeted location on which request is applied. This value can be either id or name
  • PARAMETER_VALUE : value for the PARAMETER_KEY specified before. Once set, the request will target the locations and all locations found below with the specified COAL level and PARAMETER_KEY with PARAMETER_VALUE