Octise API v1 Documentation

Welcome to the Octise API documentation. This API allows third party developers to create their own application with almost all essential functionality required. Here you can find all the necessary information to get started with the Octise API v1 and start making your own applications with integration for Octise Smart Home products.


Overview

The API is designed to work only with POST requests. All parameters are sent in body of the requests as JSON strings. The endpoint for this API is https://www.octise.com/api/v1/. All requests require client_id and client_secret as parameters for authentication.


Creating a New Octise App

All third party apps require a unique application id (client_id) and application secret key (client_secret) for authentication. You can obtain your client_id and client_secret from the Octise Developer Dashboard.

  1. Log in to the Octise Developer Dashboard.
  2. Click on 'Add Apps' button to create a new app.
  3. Enter the necessary details in the pop-up form and click Submit.
  4. You'll get a new entry in your dashboard with the newly generated unique client_id and client_secret.
Note: Keep the credentials private. Also, make sure to use different credentials for each app.


Generate OTP

Every instance of the app requires the user to sign in and allow access to the third party app. The first step is to raise a sign in request and generate an OTP for authentication.

Parameters:

  • client_id: From the developer dashboard.
  • client_secret: From the developer dashboard.
  • intent: LOGIN.GENERATE_OTP This specifies the action as initiating login and generating OTP.
  • email: Email id of the user registered with the official Octise app.


Request

{
	"client_id":"31lkndlk873tjh3bkenfklen",
	"client_secret":"b2b289128a6khcjke883ba7c0712767",
	"intent":"LOGIN.GENERATE_OTP",
	"email":"example@email.com"
}
									

Response

{
    "success": true,
    "message": "otp generated",
    "info": "You can find the generated otp in the official Octise app. Navigate to the OTP section from the side menu."
}
									

Get User Token

Once the login process is initiated and the OTP is generated, the token can be obtained by authenticating the user by using the OTP.

Parameters:

  • client_id: From the developer dashboard.
  • client_secret: From the developer dashboard.
  • intent: LOGIN.GET_USER_TOKEN This specifies the action to exchange OTP for a user token.
  • email: Email id of the user registered with the official Octise app.
  • OTP: OTP code generated from previous request. You can find the OTP in the OTP section in the side menu of the official Octise app.


Request

{
	"client_id":"31lkndlk873tjh3bkenfklen",
	"client_secret":"b2b289128a6khcjke883ba7c0712767",
	"intent":"LOGIN.GET_USER_TOKEN",
	"email":"example@email.com",
	"otp":"123456"
}
									

Response

{
    "success": true,
    "token": "d472975bc7753ebdbc9eccafd6ce553b",
    "info": "Use this token in all subsequent requests to authenticate user."
}
									

Discover Devices

Once acquired, the same user token can be used for subsequent requests. First, is naturally to discover all the devices accessible to the user.

Parameters:

  • client_id: From the developer dashboard.
  • client_secret: From the developer dashboard.
  • intent: DISCOVER_DEVICES This specifies the action to discover the devices accessible to the user.
  • uid: Unique user token received from the API.


Request

{
	"client_id":"31lkndlk873tjh3bkenfklen",
	"client_secret":"b2b289128a6khcjke883ba7c0712767",
	"intent":"DISCOVER_DEVICES",
	"uid":"d472975bc7753ebdbc9eccafd6ce553b"
}
									

Response

{
    "00000017": {
        "device_alias": "bedroom",
        "admin": "example@email.com",
        "nodes": [
            {
                "node": "0",
                "type": "0",
                "room": "bedroom",
                "alias": "Led",
                "actions": [
                    "ON_OFF"
                ]
            },
            {
                "node": "1",
                "type": "0",
                "room": "bedroom",
                "alias": "Big light",
                "actions": [
                    "ON_OFF",
                    "DIM"
                ]
            },
            {
                "node": "2",
                "type": "0",
                "room": "bedroom",
                "alias": "Lamp",
                "actions": [
                    "ON_OFF",
                    "DIM"
                ]
            },
            {
                "node": "3",
                "type": "1",
                "room": "bedroom",
                "alias": "Fan",
                "actions": [
                    "ON_OFF",
                    "DIM"
                ]
            }
        ],
        "group": "home"
    },
    "scenes": []
}
									
Understanding the Response:
  • device_id: The response JSON will have device IDs as keys, for example "00000017" as seen here. These IDs are unique to each device and are used to address the devices while sending commands or identifying the devices while getting a response from them. All important data for the devices are provided in response. However, the last key will always be "scenes". More information on this can be found in the last point.
  • device_alias: A user friendly name given to the device by the device admin.
  • group: User friendly name of the group to which the device belongs. A group is generally used to club devices by their location. For example: home, office, first floor, beach house, etc.
  • admin: User id of the admin of this device.
  • nodes: A JSON array of all the nodes, or channels to which appliances can be connected to, under this device. This array provides with a JSON object for each node.
  • node: This specifies the node number of the device.
  • type: Can be ignored for now.
  • room: Room name to which the node is assigned to. For example: bedroom, living room, terrace, lawn, etc.
  • alias: User friendly name given to the node. For example: fan, lamp, TV, night lamp, etc.
  • actions: An array (of strings) to enlist capabilities of each node.
    • ON_OFF: The node can be turned on and off.
    • DIM: The node can be dimmed. This is useful to set fan speed or light brightness for dimmable lights.
  • scenes: An array of all the scenes set by the user from the official Octise app. They are in the format of group_name-scene_name. For example, home-good night, office-meeting room on, etc.

Set Node On/Off

You can set the appliances (nodes) on or off by using this intent.

Parameters:

  • client_id: From the developer dashboard.
  • client_secret: From the developer dashboard.
  • intent: SET_ON_OFF This specifies the action to activate a scene.
  • uid: Unique user token received from the API.
  • devId: Device id of the node to be toggled.
  • node: Node number to be toggled.
  • state: Value of the state for the node. The value has to be between 0 (off) and 9 (full brightness/intensity) for nodes with dimmability and either 0 (off) or 9 (on) for nodes without dimmability.


Request

{
	"client_id":"31lkndlk873tjh3bkenfklen",
	"client_secret":"b2b289128a6khcjke883ba7c0712767",
	"intent":"SET_ON_OFF",
	"uid":"d472975bc7753ebdbc9eccafd6ce553b",
	"devId":"00000017",
	"node":"0",
	"state":"9"
}
									

Response

{
	"success":true,
	"message":"Node command sent successfully"
}
									

Set Scene

You can use this intent to activate scenes set by user.

Parameters:

  • client_id: From the developer dashboard.
  • client_secret: From the developer dashboard.
  • intent: SET_SCENE This specifies the action to activate a scene.
  • uid: Unique user token received from the API.
  • scene: Scene name as received in DISCOVER_DEVICES.


Request

{
	"client_id":"31lkndlk873tjh3bkenfklen",
	"client_secret":"b2b289128a6khcjke883ba7c0712767",
	"intent":"SET_SCENE",
	"uid":"d472975bc7753ebdbc9eccafd6ce553b",
	"scene":"home-my room all off"
}
									

Response

{
	"success":true,
	"message":"Mode set successfully"
}
									

Get Live States

You can use this intent to get live states of all devices accessible to the user. The values in the response will specify if the node is on or off, and running at what exact value.

Paramaters:

  • client_id: From the developer dashboard.
  • client_secret: From the developer dashboard.
  • intent: GET_LIVE_STATES This specifies the action to discover the devices accessible to the user.
  • uid: Unique user token received from the API.


Request

{
	"client_id":"31lkndlk873tjh3bkenfklen",
	"client_secret":"b2b289128a6khcjke883ba7c0712767",
	"intent":"GET_LIVE_STATES",
	"uid":"d472975bc7753ebdbc9eccafd6ce553b"
}
									

Response

{
    "00000017": {
        "last_by": "example@email.com",
        "last_time": "1537874603",
        "last_ack_time": "1537875101",
        "nodes": [
            "0",
            "5",
            "9",
            "0"
        ],
        "timers": []
    }
}
									
Understanding the response:
  • device_id: The response JSON will have device IDs as keys, for example "00000017" as seen here. These IDs are unique to each device and are used to address the devices while sending commands or identifying the devices while getting a response from them.
  • last_by: Email ID of the user who last accessed (sent an on/off or scene command) the device remotely.
  • last_time: Unix timestamp of last remote access to the device.
  • last_ack_time: Unix timestamp of last acknowledgement signal from the device. This is useful to check if the device is still online.
  • nodes: A JSON array of all the nodes, or channels, of a device to which the appliances can be connected. This array provides with a state value for each node. Each value is in the same order as the nodes. Thus, the first value will be for node 0, second for node 1 and so on.
  • timers: This array enlists all active timers stored in the devices. Additional functionality for timers will be released soon for third party developers.

Conclusion

There will be additional functionality available in the APIs soon. We are working everyday to improve the APIs for our third party developers. If you have suggestions, please reach out to us at care@octise.com.