iHost Open API

Step 1. Please make sure the gateway is powered on and works properly.

The BLUE indicator is a normal network connection.

The RED indicator is an abnormal network connection.

Step 2. Make sure the gateway and the PC are connected to the same LAN. Then enter the URL http://ihost.local on your browser.

Notice:

If you have several gateways, you can get the corresponding IP address to access the specified gateway in the below two ways.

1. Log in to your wireless router and check the IP address of the gateway in DHCP.
2. iHost supports local discovery via mDNS.

• Call the [Access Token] interface, and get an error response, prompting to click <Done>. Note that after pressing, the interface access is valid for no more than 5 minutes.

// Request
curl --location --request GET 'http://<ip address>/open-api/v1/rest/bridge/access_token' --header 'Content-Type: application/json'
// Response
{
  "error": 401,
  "data": {},
  "message": "link button not pressed" 
}

• Click <Done> and call the [Access Token] interface again. The response is successful, and the token is obtained.

// Request
curl --location --request GET 'http://<ip address>/open-api/v1/rest/bridge/access_token' --header 'Content-Type: application/json'
// Response
{
  "error": 0,
  "data": {
    "token": "376310da-7adf-4521-b18c-5e0752cfff8d"
  },
  "message": "success"
}

• Verify token. Call the [Get Device List] interface. The response is successful, and the device list is obtained.
  

// Request
curl --location --request GET 'http://<ip address>/open-api/v1/rest/devices' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 376310da-7adf-4521-b18c-5e0752cfff8d'
// Response
{
  "error": 0,
  "data": {
    "device_list":  [
      {
        "serial_number": "ABCDEFGHIJK",
        "name": "device name",
        "manufacturer": "manufacturer name",
        "model": "model name",
        "firmware_version": "1.1.0",
        "display_category": "switch",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          }
        ],
        "protocol": "zigbee",
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ]
  }
  "message": "success"
}

• Get iHost access token method: After calling the [Access Token] interface, the iHost Web console page global pop-up box prompts the user to confirm the acquisition of the interface call credentials.
• Note: If you open more than one iHost web console page, the confirmation pop-up box will appear on multiple web console pages together, and the pop-up box of other web console pages will be closed after clicking the confirmation on one of the web console pages.
  

The gateway Web API interface has two access methods (based on IP or domain name), usually the root path is /open-api/v1/rest/< specific function module >

// IP access
http://<IP address>/open-api/v1/rest/bridge

// Domain name access
http://<domain address>/open-api/v1/rest/bridge

• Device display category (DisplayCategory). Device display category is used to identify (device) specific categories, such as switch, plug, light, etc. This information will determine the UI display effect of the device in the gateway.
• Device Capability. Device capability is used to describe the specific sub-functions of the device. Such as power control, brightness control, color temperature control, etc. A single device can support 1 or more capabilities.
  • Ability name. Identify a specific capability. For example power, brightness.
  • Ability permission. Identify whether the capability supports reading or writing.
    • Read-only (read). Obtain the status value or configuration information related to this capability. For example, the states of power are on (open) and off (closed).
    • Write-only (write). Update the status value or configuration information related to the capability. For example, the power status can be changed to off through the interface.
    • Read&Write (readWrite). This capability supports both reading and writing.

// Device capabilities description
{
  "capabilities": [
    // Power control
    {
      "capability": "power",
      "permission": "readWrite"
    },
    // Brightness adjustment
    {
      "capability": "brightness",
      "permission": "readWrite"
    }
  ]
}
// Obtain the status state structure returned by the device list interface
{
  "state"：{
    "[capability]": {
      "[capabilityState]"：[value]
      }
   } 
}
{
  "state": {
    "power": {
      "powerState": "on"
    },
    "brightness": {
      "brightness": 100
    }
  }
}
// Modify device state - power off
{
  "state": {
    "power": {
       "powerState": "off"
    }
  }
}

Type of Data

Generic Response Results

{
  "error": 0,
  "data": {
    "token": "376310da-7adf-4521-b18c-5e0752cfff8d"
  },
  "message": "success"
}

{
  "error": 400,
  "data": {},
  "message": "invalid parameters"
}

Resource List

a. Access Token

Allow users to access token. iHost Version ≥ 1.2.0
●  Notice: The token will be cleared after device reset.
●  Notice: After obtaining the token, you need to press the button again to successfully obtain a new token.

• URL：/open-api/v1/rest/bridge/access_token
• Method：GET
• Header：
  • Content-Type: application/json

Request Parameters: 

iHost Version＜ 1.3.0

None

iHost Version ≥ 1.3.0

Successful data response:

Condition: User trigger the < command key > and access this interface within the valid time.

Status Code: 200 OK

{
  "error": 0,
  "data": {
    "token": "376310da-7adf-4521-b18c-5e0752cfff8d"
  },
  "message": "success"
}

Conditions：The user has not triggered the < command key >, or the valid time has expired.

Status Code:  200 OK

{
  "error": 401,
  "data": {},
  "message": "link button not pressed" 
}

• URL：/open-api/v1/rest/bridge/runtime
• Method：GET
• Header：
  • Content-Type: application/json
  • Autorization: Bearer <token>

Request Parameters: none

Successful data response:

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

{
  "error": 0,
  "data": {
    "ram_used": 40,
    "cpu_used": 30,
    "power_up_time": "2022-10-12T02:58:09.989Z"
  },
  "message": "success"
}

• URL：/open-api/v1/rest/bridge/config
• Method：PUT
• Header：
  • Content-Type: application/json
  • Autorization: Bearer <token>

Successful data response:empty Object {}

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

{
  "error": 0,
  "data": {},
  "message": "success"
}

• URL：/open-api/v1/rest/bridge
• Method：GET
• Header：
  • Content-Type: application/json

Successful data response:empty Object {}

{
  "error": 0,
  "data": {
    "ip": "192.168.31.25",
    "mac": "00:0A:02:0B:03:0C"
  },
  "message": "success"
}

• URL：/open-api/v1/rest/hardware/reboot
• Method：POST
• Header：
  • Content-Type: application/json
  • Autorization: Bearer <token>

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

{
  "error": 0,
  "data": {},
  "message": "success"
}

• URL：/open-api/v1/rest/hardware/speaker
• Method：POST
• Header：
  • Content-Type: application/json
  • Authorization: Bearer <token>

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

{
  "error": 0,
  "data": {},
  "message": "success"
}

c. Tags Description

• The special key toggle is used to set the name of the toggle subcomponent.

{
    "toggle": {
        '1': 'Chanel1',
        '2': 'Chanel2',
        '3': 'Chanel3',
        '4': 'Chanel4',
    },
}

{
    "temperature_unit":'c' // c-Celsius; f-Fahrenheit
}

d. Special Error Code and Description

e. Search for Sub-device

iHost Version ≥ 1.2.0
Allow authorized users to enable or disable gateway search for sub-devices through this interface

• URL：/open-api/v1/rest/devices/discovery
• Method: PUT
• Header：
  • Content-Type: application/json
  • Autorization: Bearer <token>

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

{
  "error": 0,
  "data": {},
  "message": "success"
}

f. Manually Add the Sub-device

iHost Version ≥ 1.2.0

Allow authorized users to add a single sub-device through this interface.

• Note: Only RTSP Camera and ESP32 Camera are supported now

• URL：/open-api/v1/rest/devices
• Method：POST
• Header：
  • Content-Type: application/json
  • Autorization: Bearer <token>

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

{
  "error": 0,
  "data": {
    "serial_number": "serial_number"
  },
  "message": "success"
}

Condition：
1. Camera stream address access error (format error, authorization failure, network exception, etc.)
2. Device already exists
3.If a single device fails to add, returns all devices fail to add.

Status Code: 200 OK
Error code：
● 110009 Camera IP address error
● 110010 Camera access authorization error
● 110011 Camera stream address error
● 110012 The Camera video encoding does not support
● 110013 Device already exists

{
"error": 110009,
"data": {},
"message": "camera ip access failed"
}

g. Get List of Sub-devices

iHost Version ≥ 1.2.0

Allow authorized users to obtain the list of gateway sub-device through this interface.

• URL：/open-api/v1/rest/devices
• Method: GET
• Header：
  • Content-Type: application/json
  • Autorization: Bearer <token>

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

{
  "error": 0,
  "data":{
    "device_list":  [
      {
        "serial_number": "ABCDEFGHIJK",
        "name": "My Device",
        "manufacturer": "SONOFF",
        "model": "BASICZBR3",
        "firmware_version": "1.1.0",
        "display_category": "switch",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          },
          {
            "capability": "rssi",
            "permission": "read"
          }
        ],
        "protocol": "zigbee",
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ],
  }
  "message": "success"
}

h. Update Specified Device Information or State

iHost Version ≥ 1.2.0

Allow authorized users to modify the basic information of sub-device and issue control commands through this interface.

• URL：/open-api/v1/rest/devices/{serial_number}
• Method：PUT
• Header：
  • Content-Type: application/json
  • Autorization: Bearer <token>

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

Error Code:

• 110000 The sub-device/group corresponding to the id does not exist
• 110006 Failed to update device status

{
  "error": 0,
  "data": {},
  "message": "success"
}

import axios from 'axios';
const serial_number = 'serial_number';
const access_token = 'access_token';
(async function main() {
    // turn on device
    await axios({
        url: `http://ihost.local/open-api/v1/rest/devices/${serial_number}`,
        method: 'PUT',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${access_token}`
        },
        data: {
            state: {
                power: {
                    powerState: 'on'
                }
            }
        }
    });
})()

i. Delete Sub-device

iHost Version ≥ 1.2.0

Allow authorized users to delete sub-devices through this interface.

• URL：/open-api/v1/rest/devices/{serial_number}
• Method：DELETE
• Header：
  • Content-Type: application/json
  • Autorization: Bearer <token>

Conditions: The request parameters are legal, and the user identity verification is passed.

Status Code: 200 OK

{
  "error": 0,
  "data": {},
  "message": "success"
}

Third-Party Request Gateway Interface

Request Format

Allow authorized users to send event requests to the gateway through this interface.

• URL：/open-api/v1/rest/thirdparty/event
• Method：POST
• Header：
  • Content-Type: application/json
  • Autorization: Bearer <token>

Request Parameters:

EventObject Object

{
  "event": {
    "header": {
      "name": "DiscoveryRequest",
      "message_id": "Unique identifier, preferably a version 4 UUID",
      "version": "1"
    },
    "payload": {
      "endpoints": [
        {
          "third_serial_number": "third_serial_number_1",
          "name": "my plug",
          "display_category": "plug",
          "capabilities": [
            {
              "capability": "power",
              "permission" "readWrite"
            }
          ],
          "state": {
            "power": {
              "powerState": "on"
            }
          },
          "tags": {
            "key": "value"
          },
          "manufacturer": "manufacturer name",
          "model": "model name",
          "firmware_version": "firmware version",
          "service_address": "http://192.168.31.14/service_address"
        }
      ]
    }
  }
}

{
  "header": {
    "name": "Response",
    "message_id": "Unique identifier, preferably a version 4 UUID",
    "version": "1"
  },
  "payload": {
    "endpoints": [
      {
        "serial_number": "serial number",
        "third_serial_number": "third_serial_number"
      }
    ]
  }
}

{
  "header": {
    "name": "ErrorResponse",
    "message_id": "Unique identifier, preferably a version 4 UUID",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "webhook cannot be empty" 
  }
}

{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Unique identifier, preferably a version 4 UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}

Response parameters:

PayloadObject Object: Empty Object

Example of a successful response:

  "header": {
    "name": "Response",
    "message_id": "Unique identifier, preferably a version 4 UUID",
    "version": "1"
  },
  "payload": {}
}

{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Unique identifier, preferably a version 4 UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "online": true
    }
  }
}

Response parameters:

PayloadObject Object: Empty Object

Example of a successful response:

{
  "header": {
    "name": "Response",
    "message_id": "Unique identifier, preferably a version 4 UUID",
    "version": "1"
  },
  "payload": {}
}

Gateway sends the instruction interface through the device service address

• Note:

1. The three parties need to respond to the gateway’s request within 3s. Otherwise, the gateway will judge the command processing timeout.
2. If the third-party service is offline, the gateway will set the device to an offline state, and the third-party service needs to report the device state (DeviceStatesChangeReport) or the online state (DeviceOnlineChangeReport) before returning to the online state. iHost Version ≥ 3.1

Request format

Gateway sends instructions to the third-party through the device service address interface.

Request parameters:

DirectiveObject Object

HeaderObject Object

EndpointObject Object

{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Unique identifier, preferably a version 4 UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number",
      "tags": {}
    },
    "payload": {
      "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}

  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Unique identifier, preferably a version 4 UUID",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "state": : {
         "power": {
           "powerState": "on"
         }
       }
    }
  }
}

{
  "header": {
    "name": "Response",
    "message_id": "Unique identifier, preferably a version 4 UUID",
    "version": "1"
  },
  "payload": {}
}

const evtSource = new EventSource("http://ihost.local/open-api/v1/sse/bridge?access_token=xxxxxx");
evtSource.addEventListener('device#v1#addDevice',function (event) {
  try {
    const data = JSON.parse(event.data);
    console.log('data', data);
  } catch (error) {
    console.error(`parse error`,error);
  }
}

// event.data
{
  "payload": {
    "serial_number": "ABCDEFGHIJK",
    "third_serial_number": "third_serial_number",
    "name": "My device",
    "manufacturer": "SONOFF",
    "model": "BASICZBR3",
    "firmware_version": "1.1.0",
    "display_category": "switch",
    "capabilities": [
      {
        "capability": "power",
        "permission": "readWrite"
      },
      {
        "capability": "rssi",
        "permission": "read"
      }
    ],
    "protocol": "zigbee",
    "state": {
      "power": {
        "powerState": "on"
      }
    },
    "tags": {
      "key": "value"
    },
    "online": true
  }
}

// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  },
  "payload": {
    "power": {
      "powerState": "on"
    },
    "brightness": {
      "brightness": 100
    }
  }
}

// event.data
{
"endpoint": {
"serial_number": "serial_number",
"third_serial_number": "third_serial_number"
},
"payload": {
"name": "device name"
}
}

// event.data
{
"endpoint": {
"serial_number": "serial_number",
"third_serial_number": "third_serial_number"
}
}

// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  },
  "payload": {
    "online": false
  }
}

Key Role

• TTS Service Provider: The TTS service engine service provider is responsible for registering the TTS engine on the gateway and providing TTS services

• Gateway Server：iHost

• Gateway Open API Client

6.1.1 Registering TTS Engine Service

1. 【TTS Service Provider】Call the interface to register the TTS engine on the gateway.

2. 【Gateway Server】After successful registration, the gateway will store the basic information of the TTS engine (including the service address server_address, and subsequent communication between the gateway and the TTS Service Provider will be carried out through the server_address address), and allocate the TTS engine service ID within the gateway.

6.1.2 Get the List of Synthesized Audio

1. 【Gateway Open API Client】Call the interface to obtain the list of registered TTS engine service. You can obtain the current list of registered TTS engines (including the ID of the TTS engine allocated by the gateway).

2. 【Gateway Open API Client】Call the interface to obtain the list of a specified TTS engine audio. The gateway will issue a synchronous audio list instruction to the specified TTS Service Provider and return the result.

6.1.3 Speech Synthesis by Specifying a Speech Engine

1. 【Gateway Open API Client】Call the interface to obtain the list of registered TTS engine service. You can obtain the current list of registered TTS engines (including the ID of the TTS engine allocated by the gateway).

2. 【Gateway Open API Client】Call the interface to obtain the list of a specified TTS engine audio. The gateway will issue a synchronous audio list instruction to the specified TTS Service Provider and return the result.

6.1.4 Synthesize Audio and Play TTS Speech.

1. 【Gateway Open API Client】Call the interface to obtain the list of registered TTS engine service. You can obtain the current list of registered TTS engines (including the ID of the TTS engine allocated by the gateway).

2. 【Gateway Open API Client】Call the interface to obtain the list of a specified TTS engine audio. The gateway will issue a synchronous audio list instruction to the specified TTS Service Provider and return the result. (including the TTS audio file address)

3. 【Gateway Open API Client】Record the TTS audio file address from the result returned in the previous step, call the play audio file interface, and play it through the gateway.

6.2.1 Gateway Open Capability

a. Get the list of registered TTS engine services

b. Get list of specified TTS engine audio

AudioObject Structure

c .Perform speech synthesis using the specified TTS engine

6.2.2 Communication Between Gateway and TTS Service

a. Registering TTS engine service

Send request to gateway by TTS Service Provider

b. Synchronize audio list command

Send command to the TTS Service Provider by gateway.

HeaderObject Object

PayloadObject Object:

c. Speech synthesis command

Send request to gateway by TTS Service Provider