avi-on Cloud Platform Public API User Guide
- June 5, 2024
- avi-on
Table of Contents
avi-on Cloud Platform Public API
Information
- Product information is subject to change without notice. Check the Avi-on support website for the latest information.
- The Bluetooth® word mark and logos are registered trademarks owned by the Bluetooth SIG, Inc. and any use of such marks by Avi-on Labs, Inc. is under license.
- All trademarks are recognized as the property of their respective owners.
- To ensure optimal reliability and to meet warranty requirements, Avi-on products must be installed according to the instructions in this manual.
Audience
This manual is intended for use by skilled professional installation and
maintenance personnel. Safety and shock hazards may be present during
installation.
Overview
- This API is designed for application developers to access the platform via our cloud API to create mobile or web applications that connect through the Avi-on cloud service to operate devices within Avi-on Networks. The API also allows discovery of the devices, groups, and scenes to control, as well as the current status of devices.
- For the API to work, the user must have a Remote Access Bridge configured and online to connect their local Mesh network to the Avi-on cloud service.
- The key elements of the API include authentication and session token management, get account status information, get device configuration and available features, and post new states to devices, groups or scenes for dimming and color changing.
- The present release does not support the creation or modification of groups, schedules or scenes via the API. In many cases complex logic is required to assure changes are properly synchronized across all impacted devices. These should be set up using the Avi-on app, and then they can be operated via the API.
- To access the API, the remote system must independently have the current avi-on user email and password for each user account to be accessed. Other integrations, such as OATH2 are possible as a services engagement with Avi-on.
- Please contact Avi-on for licensing terms and services support cost and scope for a production integration.
- Public API includes every endpoint accessible to Users with role End User. The following instructions describe how to to authenticate a user created through the Avi-on app (or third party apps using our APIs) and consume the set of APIs defined as Public for third party developers.
Support
Support is available to Avi-on device licensees on a professional services
basis. Contact [email protected] for a customized support quote bas on your
needs.
Authentication
- Avi-on use based on HTTP Basic Authentication strategy to enforce access control to our API. The creation of a Session Token is done with a POST (only supported by HTTPS) with 0the email and password in the body as JSON. We don’t support sending this information in other formats.
- If the information provided (email and password) is correct, the API respond with a Token and a Refresh Token to be use in following requests in the header: Authorization: Token
. The expiration time of the token for the API is one week and the refresh token one month.
Create Session Token
- If the information provided (email and password) is correct, the API respond with a Token and a Refresh Token to be use in following requests in the header: Authorization: Token
. The expiration time of the token for the API is one week and the refresh token one month. - First step to use the Public API is to create an authorization token with the username and password.
- POST http://api.avi-on.com/sessions
Payload (JSON
| Name | Type | Description |
|---|---|---|
| User’s email | string | |
| string | password | User’s password |
Headers:
| Name | Value |
|---|---|
| Content-Type | application/json |
Response:
| Name | Type | Description |
|---|---|---|
| auth_token | String | Token for authentication |
| capabilities* | Array | List of capabilities |
| email_verified | Boolean | Email verification |
| phone_verified | Boolean | Phone verification |
| refresh_token** | String | Token to get new token when auth_token expires |
| expiration_date | Date/Time | Time after the auth_token requires refresh |
Response (Code 201):
Inside credential attribute. Ignore the rest of the response. It’s for internal use.
| Name | Type | Description |
|---|---|---|
| auth_token | String | Token for authentication |
| capabilities* | Array | List of capabilities |
| email_verified | Boolean | Email verification |
| phone_verified | Boolean | Phone verification |
| refresh_token** | String | Token to get new token when auth_token expires |
| expiration_date | Date | Date/Time when the Token requires refresh |
Errors:
| Code | Response | Reason |
|---|---|---|
| 401 | {“error”:{“auth”:[“Incorrect Email or Password.”]}} | Self descriptive. |
Credentials are wrong.
401| {“error”:{“credentials”:[“Missing credentials”]}}| The data was sent
(check the Content-Type).
Example:
curl -X POST http://api.avi-on.com/user/devices -H “Content-Type:
application/json” -d
“{\”email\”:\”[email protected]\”,\”password\”:\”password\”}”
Code 201
Refresh Session Token
To refresh the token once expired. It’s the same endpoint but must include an
Authorization header with the refresh token as value. See Headers below: PUT
http://api.avi-on.com/sessions
Headers:
| Name | Value |
|---|---|
| Content-Type | application/json |
| Authorization | RefreshToken |
Response:
The same as Create Session Token.
Errors:
| Code | Response | Reason |
|---|---|---|
| 401 | {“error”:{“auth”:[“Inco{“error”:{“refresh_token”:[“Invalid Refresh | |
| Token”]}} rrect Email or Password.”]}} | The refresh token is wrong | |
| 401 | {“error”:{“credentials”:[“Missing | |
| credentials”]}}{“error”:{“credentials”:[“Missing credentials”]}} | Refresh |
Token is missing
User’s Devices API
The purpose of this is to identify the current state of the device (not groups or scenes at this time). This includes:
- Current Dim level
- Current Color temperature (Kelvin)
- Active scenes
- Device Name and capabilities
Get Device State
GET http://api.avi-on.com/user/devices
Headers:
| Name | Value |
|---|---|
| Content-Type | application/json |
| Authorization | Token |
Errors:
| Code | Response | Reason |
|---|---|---|
| 401 | {“error”:{“auth_token”:[“Invalid Token”]}} | The token is not longer valid |
| 401 | {“error”:{“credentials”:[“Missing credentials”]}} | Refresh Token is |
missing
Response (Code 200):
State API
Get States
GET http://api.avi-on.com/
Parameters:
| Name | Value |
|---|---|
| operable | Oneoperablefrom:device, grouporscene |
| pid | Public ID |
Headers:
| Name | Value |
|---|---|
| Content-Type | application/json |
| Authorization | Token |
Response (Code 200):
| Field | Description |
|---|---|
| name | Standard name of the stateful feature |
| value | Current value in internal protocol format |
| humanized | The value in human readable format |
Errors:
| Code | Response | Reason |
|---|---|---|
| 401 | {“error”:{“auth_token”:[“Invalid Token”]}} | The token is not longer valid |
| 401 | {“error”:{“credentials”:[“Missing credentials”]}} | RefreshToken is |
missing
403| {“error”:{“authorization”:[“Forbidden access”]}}| Unauthorized access to
an operable
404| {“error”:”
Update States
POST http://api.avi-on.com/
Perameters:
| Name | Value |
|---|---|
| operable | Oneoperablefrom:device, grouporscene |
| pid | Public ID |
Payload (JSON): State
| Name | Type | Description |
|---|---|---|
| String | Standard name of the stateful feature | |
| value* | String | New Value in JSON |
- See more information about valid values for properties below.
Headers:
| Name | Value |
|---|---|
| Content-Type | application/json |
| Authorization | Token |
Response (Code 200):
Errors:
Response (Code 200):
| Field | Description |
|---|---|
| name | Standard name of the stateful feature |
| value | Current value in internal protocol format |
| humanized | The value in human readable format |
Featured Value Format:
| Code | Response | Reason |
|---|---|---|
| on_off | String in lowercase (on,off) or in integer (1,0) | “on”, “off”, “1”, “0” |
| dim | Percentage between 0-100% or between 0-255. Also supports delta | |
| incrementals. | “100%” (full dimming) or “0” (off ). “+10%”, “-25%” | |
| white | Kelvins between 1500-7000. Also supports delta incrementals. | “2200” |
(warm), “5500” (daylight). “-25%” (warmer), “+25%” (cooler)
rgb| [Red,Green,Blue]| “[255,0,0]” (for Red)
action| Only feature for scenes. Idem as on_off.| “on”, “off”, “1”, “0”
Analytics
This set of endpoints is available to provide historical information for devices under each location. We gather energy consumption and dimming events which can then be reported via the following.
Get Energy Consumption
GEThttp://api.avi-on.com/locations/{{location_pid}}/energy?
pids=60d4d8a06472,27460a8d4d06&type=device&from=2019-04-01&to=2019-04-07
Can be queried for both groups or sets of devices. Group query supports a
single group on each request, whereas queries for devices support a set of
devices. You will need to specify the type of request (device or group), start
and end dates for the report (inclusive) and the set of pids for the required
entities.
Will return a list of devices or groups with a set of pairs timestamp
Headers:
| Name | Value |
|---|---|
| Content-Type | application/json |
| Authorization | Token |
Parameters:
| Name | Value | Description |
|---|---|---|
| pid | 60d4d8a06472,27460a8d4d06 | Required – comma separated list of device |
pids, or a single group pid.
type| device| Required – one of, “device” or “group” to collect data for a set
of devices or a group.
from| 2019-04-01| Required – YYYY-MM-DD start date for the report.
to| 2019-04-07| Required – YYYY-MM-DD end date for the report.
Get Events for devices in location
GET http://api.avi-on.com/locations/{{location_pid}}/events?
pids=60d4d8a06472,27460a8d4d06&type=device&from=2019-04-01&to=2019-04-07&feature=dim
Can be queried for both groups or sets of devices. Group query supports a
single group on each request, whereas queries for devices support a set of
devices. You will need to specify the type of request (device or group), start
and end dates for the report (inclusive) and the set of pids for the required
entities.
Will return a list of devices or groups with a set of pairs timestamp
Headers:
| Name | Value |
|---|---|
| Content-Type | application/json |
| Authorization | Token |
Parameters:
| Name | Value | Description |
|---|---|---|
| pid | 60d4d8a06472,27460a8d4d06 | Required – comma separated list of device |
pids, or a single group pid.
type| device| Required – one of, “device” or “group” to collect data for a set
of devices or a group.
from| 2019-04-01| Required – YYYY-MM-DD start date for the report.
to| 2019-04-07| Required – YYYY-MM-DD end date for the report.
feature| dim|
ALL PRODUCT, PRODUCT SPECIFICATIONS AND DATA ARE SUBJECT TO CHANGE WITHOUT
NOTICE TO IMPROVE RELIABILITY, FUNCTION OR DESIGN OR OTHERWISE.
The information contained herein is believed to be reliable. Avi-on makes no
warranty, representation or guarantee regarding the information contained
herein, the suitability of the products for any particular purpose, or the
continuing production of any product. Avi-on assumes no responsibility or
liability whatsoever for the use of the information contained herein. The
information contained herein, or any use of such information does not grant,
explicitly or implicitly, to any party any patent rights, licenses, or any
other intellectual property rights, whether with regard to such information
itself or anything described by such information.