API documentation (version 1)

General information


This documentation is about the version 1 of the Sens'it API. It has been released on 05/01/15.
The API can be accessed at the address https://api.sensit.io/v1 (referenced later as '{endpoint'}). It is only available using HTTPS.
The data exchange is performed using the JSON data format.
The date format is the ISO 8601 format.

Authentication


Authentication is performed by using the HTTP header Authorization. All requests except the authentication request have to contain this header:

Authorization : Bearer my_access_token
The access token can be found (and refreshed) in the UI on the "My account" page. It can also be obtained by making a POST request at '{endpoint'}/auth. This request has to contain the email and the hashed password. The password is hashed using the SHA1 algorithm.
Here is the format of the awaiting JSON:
POST {endpoint}/auth

{
	"email": "myemail@example.com",
	"password": "my_hashed_password"
}
			
Here is the format of the JSON response:
{
	"results": "1",
	"data": {
		"token": "my_access_token"
	},
	"links": {}
}
			

Response structure


The JSON result contains the number of results, the results themselves and pagination links to access other pages. The number of results per request is limited to 100; to access a specific page you can add a page parameter in the request. Here is the response structure as JSON:

{
	"results": 15,
	"data": [
		...
	],
	"links": {
		"first": "{endpoint}?page=1",
		"prev": "{endpoint}?page=3",
		"next": "{endpoint}?page=5",
		"last": "{endpoint}?page=15"
	}
}
			

Errors


If your request is malformed or an error occured during the process, the reponse will contain the following data:

{
	"err": 100, // Unique error code
	"details": "No Authorization header" // String description of the error
}
			
Here are the possible errors
100, "Error database access"
101, "Wrong Content-Type header : only accept application/json"
102, "Auth error : too many login attempts"
200, "No Authorization header"
201, "No Bearer for Authorization header"
202, "No token"
203, "Auth error on token"
204, "Auth error"
205, "Auth error generating token"
			

Modes


You can get the list of modes for a specific device model (useful to understand the attribute "mode" in the device object) by making a GET request at '{endpoint'}/modes/:id_device_model. Here is the format of the JSON response (data attribute):

GET {endpoint}/modes/1

{
	sensors: [
		{
			type: "BUTTON"
		}
	]
	name: "off"
	value: 0
}
{
	sensors: [
		{
			type: "TEMPERATURE"
		}
		{
			type: "BUTTON"
		}
	]
	name: "temperature"
	value: 1
}
{
	sensors: [
		{
			type: "MOTION"
		}
		{
			type: "BUTTON"
		}
	]
	name: "motion_temperature"
	value: 2
}
{
	sensors: [
		{
			type: "SOUND"
		}
		{
			type: "BUTTON"
		}
	]
	name: "sound_temperature"
	value: 3
}
{
	sensors: [
		{
			type: "SOUND"
		}
		{
			type: "MOTION"
		}
		{
			type: "TEMPERATURE"
		}
		{
			type: "BUTTON"
		}
	]
	name: "motion_sound_temperature"
	value: 4
}
			

List of devices


You can get the list of your devices by making a GET request at '{endpoint'}/devices. Here is the format of the JSON response (data attribute):

GET {endpoint}/devices

[
	{
		"id": 1,
		"serial_number": "BC123", // This serial is written on the back of the Sens'it
		"activation_date"; "2015-03-01 13:50:51Z",
		"last_comm_date"; "2015-03-01 13:50:51Z",
		"mode": 1,
		"battery": 65 // Percentage of battery
	},{
		"id": 2,
		"serial_number": "BC124", // This serial is written on the back of the Sens'it
		"activation_date"; "2015-03-01 13:50:51Z",
		"last_comm_date"; "2015-03-01 13:50:51Z",
		"mode": 4,
		"battery": 25
	}
]
			
For the possible mode values, please refer to the modes endpoint.

Device


Read info

You can get the information (including a list of sensors) for a specific device by making a GET request at '{endpoint'}/devices/:id. Here is the format of the JSON response (data attribute):

GET {endpoint}/devices/1			
			
{
	"id": 1,
	"serial_number": "BC123", // This serial is written on the back of the Sens'it
	"activation_date"; "2015-03-01 13:50:51Z",
	"last_comm_date"; "2015-03-01 13:50:51Z",
	"last_config_date"; "2015-03-01 13:50:51Z",
	"config_status": "ack", // Can be null and otherwise : not_sent, ack, downlink, downlink_ack, downlink_overusage, invalid_payload, network_error, error
	"mode": 1,
	"battery": 65,
	"sensors": [
		{
			"id": "10",
			"sensor_type": "temperature",
			"config": {
				"period" : 10 // {24: 24h, 12: 12h, 6:6h, 2:2h, 1:1h, 30: 30min, 15: 15min, 10:10min}
			},
			"signal_level": "good", // excellent, good, average or limit.
		},
		{
			"id": "11",
			"sensor_type": "motion",
			"config": {
				"threshold" : 1 // {0:very insensitive, 1:insensitive, 2:normal, 3:sensitive, 4:very sensitive} 
			},
			"signal_level": "average",
		},
		{
			"id": "12",
			"sensor_type": "sound",
			"config": {
				"threshold" : 3 // {0:very insensitive, 1:insensitive, 2:normal, 3:sensitive, 4:very sensitive} 
			},
			"signal_level": "excellent",
		},
		{
			"id": "13",
			"sensor_type": "button",
			"signal_level": "limit",
		}
	]
}
			

Write

You can update a device configuration by making a POST request at '{endpoint'}/devices/:id. Here is the format of the awaiting JSON:

POST {endpoint}/devices/1
	
{
	"sensors": [
		{
			"id": "10", // Temperature sensor
			"config": {
				"period" : 7 // {0: 24h, 1: 12h, 2:6h, 3:2h, 4:1h, 5: 30min, 6: 15min, 7:10min}
			}
		},
		{
			"id": "11", // Motion sensor
			"config": {
				"threshold" : 1 // {0:very insensitive, 1:insensitive, 2:normal, 3:sensitive, 4:very sensitive} 
			}
		},
		{
			"id": "12", // Sound sensor
			"config": {
				"threshold" : 3 // {0:very insensitive, 1:insensitive, 2:normal, 3:sensitive, 4:very sensitive} 
			}
		}
		// No configuration for button sensor
	]
}
			

Sensor information


You can get the information (including data history) for a specific sensor by making a GET request at '{endpoint'}/devices/:id/sensors/:id. Here is the format of the JSON response (data attribute):

GET {endpoint}/devices/1/sensors/10		
			
{
	"id": 10,
	"sensor_type"; "temperature",
	"history": [
		{
			"date": "2015-04-27 16:52:47Z",
			"date_period": "2015-04-27 15:52:47Z", // For the complete mode it is the beginning of the period during which the data has been measured.
			"data": "24.0",
			"signal_level": "good"
		},
		{
			"date": "2015-04-27 16:42:47Z",
			"data": "23.0",
			"signal_level": "good"
		},
		{
			"date": "2015-04-27 16:32:47Z",
			"data": "22.5",
			"signal_level": "good"
		},
	],
	"config": {} // See "Device info" part
}
			
The data field of the history has to be interpreted depending on the sensor type and the mode. It can contain multiple values separated by a column symbol. Here is the data interpretation for your V1 Sens'it:
Temperature sensor:
Temperature mode: it contains the minimum and the maximum temperatures measured during the period. For example 20.5:31.0
Complete mode: it contains the measured temperature. For example 24.0

Motion sensor:
Motion mode: it contains the number of motions detected. For example 4
Complete mode: it contains the threshold (between 0 and 4 as configured in the UI) and the number of motions detected. For example 2:8

Sound sensor:
Sound mode: it contains the threshold, the number of sounds detected and the minimum and maximum sound data. For example 2:43:139:244
Complete mode: it contains the number of sounds detected and the minimum and maximum sound data. For example 0:114:217

Button sensor:
The data field is empty because only the date is important
			
Here is the data interpretation for your V2 Sens'it:
Temperature/humidity sensor:
it contains the measured temperature in °C or the temperature in °C and the humidity in %. For example 24 or 24.0:60
It contains the temperature and the humidity for the regular frames in temperature/humidity mode. Some other frames (in other modes) can contain only the temperature.

Door sensor:
it contains the number of door openings since the last frame. As the Sens'it has a limitation of 8 frames per hour, this value is not always equal to 1 

Light sensor:
it contains the number of light detections and the value in lux of the light. For example 1:25.

Vibration sensor:
it contains the number of vibrations since the last frame. As the Sens'it has a limitation of 8 frames per hour, this value is not always equal to 1

Magnet sensor:
it contains the number of magnet changes since the last frame and the state of the reed switch (for example 1:1 or 4:0). As the Sens'it has a limitation of 8 frames per hour, the counter value is not always equal to 1

Button mode:
The data field is empty because only the date is important
			

Callbacks


You can define a callback URL that will be called everytime your Sens'it communicate with our server (from the "My account" page). You can also specify a custom header (for authentication for example) that will be added to each request. The URL is called as a POST request and the data JSON contains the device information (id and updated last communication date and mode) and the new date received for each sensor:

Callback data for the complete mode			
			
{
  "id":"1",
  "serial_number":"BC123",
  "sensors":[
    {
      "id":"1",
      "history":[
        {"data":"40.5","date":"2015-04-30T14:02Z"}, // data  = temperature
        {"data":"23.5:32.5","date_period":"2015-04-29T14:02Z","date":"2015-04-30T14:02Z"} // data = min_temperature:max_temperature for the period 
      ],
      "sensor_type":"temperature",
      "signal_level": "good"
    },{
      "id":"2",
      "history":[
        {"data":"2:20","date_period":"2015-04-29T14:02Z","date":"2015-04-30T14:02Z"} // data = threshold:counter for the period
        {"data":"20","date_period":"2015-04-29T14:02Z","date":"2015-04-30T14:02Z"} // data = counter for the period
      ],
      "sensor_type":"motion",
      "signal_level": "good"
    },{
      "id":"3",
      "history":[
      	{"data":"2:22:20:21","date_period":"2015-04-29T14:02Z","date":"2015-04-30T14:02Z"} // data = threshold:counter:min:max for the period
        {"data":"22:20:21","date_period":"2015-04-29T14:02Z","date":"2015-04-30T14:02Z"} // data = counter:min:max for the period
      ],
      "sensor_type":"sound",
      "signal_level": "good"
    },{
      "id":"4",
      "history":[
      	{"date":"2015-04-30T14:02Z"}
      ],
      "sensor_type":"button",
      "signal_level": "good"
    }
  ],
  "activation_date":"2015-01-08T12:33Z",
  "last_comm_date":"2015-04-30T14:02Z",
  "mode":"0"
}
			
If the history object contains an "date_period" attribute then the data is for the period between "date_period" and "date". Otherwise it is an punctual value at the date "date".
The "sensors" array contains only the sensors that have received new data.
When your callback URL is called, the "signal_level" data is incomplete because this value is computed based on many factors including the number of stations which received the signal (there is only 1 station when the callback is called).

Callbacks notifications


You can define a callback URL for each notification. This URL will be called everytime the notification conditions are fulfilled. It is called as a GET request. You can customize the parameter list by specifying param={{variable}} in the URL. The available variables are :


The notification type can be :
The data field contains different information depending on the notification_type and the current mode : If the data object contains an "date_period" attribute then the data is for the period between "date_period" and "date". Otherwise it is an punctual value at the date "date".