EnOS API

https://support.enos-iot.com/docs/api/en/3.0.0/
Admin
EnOS provides open APIs that cover the core business processes of the system, allowing developers to...
Tokens:18,128
Snippets:67
Trust Score:4.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### EnOS API Example Request - GET Asset Information

Source: https://support.enos-iot.com/docs/api/en/3.0.0/overview

Illustrates how to make a GET request to retrieve asset information using the EnOS API. It specifies the HTTP method, the API endpoint with service and version, and query parameters like orgId and assetId.

```http
GET https://{apigw-address}/asset-service/v2.1/assets?action=get&orgId=1234&assetId=abcd

```

--------------------------------

### Asynchronous GET Request

Source: https://support.enos-iot.com/docs/api/en/3.0.0/gettingstarted

Shows how to perform an asynchronous GET request using the EnOS Java SDK (Poseidon) with a listener for handling responses and failures.

```java
Poseidon.config(PConfig.init().appKey(accessKey).appSecret(secretKey))
        .url("https://{apigw-address}/{service-name}/{api-version}/{api_name}?{param1=value1&param2=value2}")
        .method("GET").async( new PoseidonListener() {
              @Override
              public void onFailure(String errorMessage) {
                // TODO
              }

              @Override
              public void onResponse(String body) {
                // TODO
              }
            });
```

--------------------------------

### Get Asset API

Source: https://support.enos-iot.com/docs/api/en/3.0.0/gettingstarted

This endpoint retrieves asset details. The example demonstrates how to use the Java core SDK to call the API with logging disabled.

```APIDOC
## GET /asset-service/v2.1/assets

### Description
Retrieves detailed information about a specific asset.

### Method
GET

### Endpoint
`https://{apigw-address}/asset-service/v2.1/assets?action=get&orgId={org_id}&assetId={asset_id}`

### Parameters
#### Query Parameters
- **action** (string) - Required - Specifies the action to perform, should be 'get'.
- **orgId** (string) - Required - The ID of the organization.
- **assetId** (string) - Required - The ID of the asset to retrieve.

### Request Example
```java
import com.enosiot.apim.poseidon.config.PConfig;
import com.enosiot.apim.poseidon.core.Poseidon;

public class GetAsset {
    public static void main(String[] args) {
        String accessKey = "{access_key_of_the_application}";
        String secretKey = "{secret_key_of_the_application}";
        String response = Poseidon.config(PConfig.init().appKey(accessKey).appSecret(secretKey))
                .url("https://{apigw-address}/asset-service/v2.1/assets?action=get&orgId={org_id}&assetId={asset_id}")
                .method("GET")
                .sync();
        System.out.println(response);
    }
}
```

### Response
#### Success Response (200)
- **code** (integer) - 0 for success.
- **msg** (string) - "OK" for success.
- **data** (object) - Contains the asset details.
  - **modelId** (string) - The ID of the asset model.
  - **assetId** (string) - The ID of the asset.
  - **timezone** (string) - The timezone of the asset.
  - **name** (object) - The name of the asset.
    - **i18nValue** (object) - Internationalized names.
    - **defaultValue** (string) - Default name of the asset.
  - **attributes** (object) - Key-value pairs of asset attributes.
  - **modelIdPath** (any) - Path for the model ID.
  - **orgId** (string) - The organization ID.
  - **desc** (any) - Description of the asset.
  - **tags** (object) - Key-value pairs of asset tags.
- **requestId** (string) - Unique request ID.

#### Response Example
```json
{
  "msg": "OK",
  "code": 0,
  "data": {
    "modelId": "model_id",
    "assetId": "asset_id",
    "timezone": "+08:00",
    "name": {
      "i18nValue": {},
      "defaultValue": "asset_name"
    },
    "attributes": {
      "system": "System"
    },
    "modelIdPath": null,
    "orgId": "yourOrgId",
    "desc": null,
    "tags": {}
  },
  "requestId": "9a5cfbac-b2f8-4a37-b38d-8bccdd77d073"
}
```
```

--------------------------------

### Invoke EnOS API: Get Asset Details using Java SDK (GET)

Source: https://support.enos-iot.com/docs/api/en/3.0.0/gettingstarted

This Java code snippet demonstrates how to retrieve asset details by invoking the 'Get Asset' API using the EnOS core SDK. It requires application access and secret keys, along with organization and asset IDs. API logging is disabled in this example.

```java
import com.enosiot.apim.poseidon.config.PConfig;
import com.enosiot.apim.poseidon.core.Poseidon;

public class GetAsset {
    public static void main(String[] args) {

        String accessKey = "{access_key_of_the_application}";
        String secretKey = "{secret_key_of_the_application}";

        String response = Poseidon.config(PConfig.init().appKey(accessKey).appSecret(secretKey))
                .url("https://{apigw-address}/asset-service/v2.1/assets?action=get&orgId={org_id}&assetId={asset_id}")
                .method("GET")
                .sync();
        System.out.println(response);
        }
    }

```

--------------------------------

### Synchronous GET Request with Independent Path and Query Params

Source: https://support.enos-iot.com/docs/api/en/3.0.0/gettingstarted

Illustrates a synchronous GET request using the EnOS Java SDK (Poseidon) where the URL, path, and query parameters are set independently. Note that `.path()` must precede `.queryParam()`.

```java
Poseidon.config(PConfig.init().appKey(accessKey).appSecret(secretKey).debug())
            .url("https://{apigw-address}")
            .path("/{service-name}/{api-version}/{api_name}")
            .method("GET")
            .header("")
            .queryParam("param1","value1")
            .queryParam("param2","value2")
            .sync();
```

--------------------------------

### Synchronous GET Request (Logging Enabled)

Source: https://support.enos-iot.com/docs/api/en/3.0.0/gettingstarted

Shows a synchronous GET request with API logging enabled using the EnOS Java SDK (Poseidon). This returns both request parameters and the response.

```java
Poseidon.config(PConfig.init().appKey(accessKey).appSecret(secretKey).debug())
     .url("https://{apigw-address}/{service-name}/{api-version}/{api_name}?{param1=value1&param2=value2}")
     .method("GET")
     .sync();
```

--------------------------------

### EnOS API Token Get Request Sample

Source: https://support.enos-iot.com/docs/api/en/3.0.0/token/get_access_token

This is a sample request body for the EnOS API's Get Access Token endpoint. It includes the application key, the encrypted ciphertext, and a timestamp.

```json
{
    "appKey": "5acb82e7-a11e-4300-9164-c8b20b638e8b",
    "encryption": "87c6885cec7525e2f219f86a82b280cc8c2d6ff4040a4b5f8acf9aeeda37aba8",
    "timestamp": 1572574909697
}
```

--------------------------------

### itemFormat Parameter Examples

Source: https://support.enos-iot.com/docs/api/en/3.0.0/api_faqs

Illustrates the output format of device data returned by TSDB Data Service APIs based on the `itemFormat` parameter.

```APIDOC
## Item Format Examples

When calling TSDB Data Service APIs, you can use the `itemFormat` parameter to specify the displaying format of the returned device data. Available options are 0, 1, and 2.

### itemFormat=0
```json
{
  "code": 0,
  "msg": "OK",
  "data": {
    "items": [
      {
        "assetId": "4DXYH7nS",
        "localtime": "2019-06-11T18:35:12.123+08:00",
        "timestamp": 1560249312446,
        "power": "1.1236",
        "dataQuality": "1.1236"
      },
      {
        "assetId": "4DXYH7nS",
        "localtime": "2019-06-11T18:35:12.123+08:00",
        "timestamp": 1560249332446,
        "windspeed": "1.1236",
        "dataQuality": "1.1236"
      }
    ]
  }
}
```

### itemFormat=1
```json
{
  "code": 0,
  "msg": "OK",
  "data": {
    "items": [
      {
        "assetId": "4DXYH7nS",
        "timestamp": 1560249312446,
        "localtime": "2019-06-11T18:35:12.123+08:00",
        "windspeed": "1.1236",
        "power": "1.1236"
      },
      {
        "assetId": "4DXYH7nS",
        "timestamp": 1560249312446,
        "localtime": "2019-06-11T18:35:12.123+08:00",
        "windspeed": "1.1236",
        "power": "1.1236"
      },
      {
        "assetId": "4DXYH7nS",
        "timestamp": 1560249312444,
        "localtime": "2019-06-11T18:35:12.123+08:00",
        "windspeed": "1.1236"
      }
    ]
  }
}
```

### itemFormat=2
```json
{
   "code": 0,
   "msg": "OK",
   "submsg": " ",
   "data": {
      "items": [
         {
            "assetId": "xxx",
            "pointId": "power",
            "localTime": [
               "2020-03-09T20:29:45.222 +08:00",
               "2020-03-09T20:29:45.222 +08:00"
            ],
            "timestamp": [
               1583756985399,
               1583756985399
            ],
            "value": [
               "12.3",
               "17.8"
            ],
            "dataQuality": [
               0,
               1"
            ]
         }
      ]
   }
}
```
```

--------------------------------

### EnOS Pagination Request Structure Example

Source: https://support.enos-iot.com/docs/api/en/3.0.0/overview

Illustrates the structure for making paginated requests to EnOS APIs. It includes fields for page number, page size, and optional sorting parameters like field and order.

```json
{
    "pagination": {
        "pageNo": 2,
        "pageSize": 100,
        "sorters": [
            {
                "field": "assetId",
                "order": "ASC"
            }
        ]
    }
}
```

--------------------------------

### EnOS API Token Get Response Sample

Source: https://support.enos-iot.com/docs/api/en/3.0.0/token/get_access_token

This sample shows a successful response from the EnOS API's Get Access Token endpoint. It includes a status code, a success message, business information, and the access token with its expiry time.

```json
{
    "status": 0,
    "msg": "SUCCESS",
    "business": "apim-token-service",
    "data": {
        "accessToken": "Generated_Access_Token",
        "expire": 7200
    }
}
```

--------------------------------

### Synchronous GET Request (Logging Disabled)

Source: https://support.enos-iot.com/docs/api/en/3.0.0/gettingstarted

Demonstrates a synchronous GET request using the EnOS Java SDK (Poseidon) when API logging is disabled. Only the API result is returned.

```java
Poseidon.config(PConfig.init().appKey(accessKey).appSecret(secretKey))
     .url("https://{apigw-address}/{service-name}/{api-version}/{api_name}?{param1=value1&param2=value2}")
     .method("GET")
     .sync();
```

--------------------------------

### EnOS IoT API itemFormat=0 Example

Source: https://support.enos-iot.com/docs/api/en/3.0.0/api_faqs

Example JSON response for the TSDB Data Service API when 'itemFormat' is set to 0. This format displays device data with assetId, localtime, timestamp, and specific data points like power and dataQuality.

```json
{
  "code": 0,
  "msg": "OK",
  "data": {
    "items": [
      {
        "assetId": "4DXYH7nS",
        "localtime": "2019-06-11T18:35:12.123+08:00",
        "timestamp": 1560249312446,
        "power": "1.1236",
        "dataQuality": "1.1236"
      },
      {
        "assetId": "4DXYH7nS",
        "localtime": "2019-06-11T18:35:12.123+08:00",
        "timestamp": 1560249332446,
        "windspeed": "1.1236",
        "dataQuality": "1.1236"
      }
    ]
  }
}
```

--------------------------------

### EnOS Projection Parameter Example

Source: https://support.enos-iot.com/docs/api/en/3.0.0/overview

Shows how to use the projection parameter to filter the data returned by EnOS APIs. This allows specifying which fields or sub-fields should be included in the response.

```json
{
    "projection": [
        "assetPaths", "assets.*.assetId"
        ]
}
```

--------------------------------

### EnOS API Success Response Example

Source: https://support.enos-iot.com/docs/api/en/3.0.0/overview

Demonstrates a typical successful response from the EnOS API, including status code, message, request ID, and an empty data payload. This format is consistent across many EnOS API calls.

```json
{
  "code": 0,
  "msg": "OK",
  "requestId": "6cb7a013-7f83-4620-97c8-4695a892acdf",
  "data": {
  }
}
```

--------------------------------

### EnOS API Error Response Samples

Source: https://support.enos-iot.com/docs/api/en/3.0.0/overview

Provides examples of common error responses from the EnOS API, including invalid parameters, missing permissions, and internal server errors. Each sample shows the error code, message, and request ID.

```json
{
    "code": 99400,
    "msg": "Invalid Argument action:action is missing",
    "requestId": "4d4bfd4d-b5c5-4b9c-b452-833516153b49",
    "data": null
}
```

```json
{
    "code": 99400,
    "msg": "Invalid Argument orgId:  orgId does not exist",
    "requestId": "4d4bfd4d-b5c5-4b9c-b452-833516153b49",
    "data": null
}
```

```json
{
    "code": 99403,
    "msg": "Denied resource:  orgId o1558xxxxxxxxxx",
    "requestId": "4d4bfd4d-b5c5-4b9c-b452-833516153b49",
    "data": null
}
```

```json
{
    "code": 99500,
    "msg": " Internal Server Error",
    "requestId": "4d4bfd4d-b5c5-4b9c-b452-833516153b49",
    "data": null
}
```

--------------------------------

### EnOS IoT API itemFormat=1 Example

Source: https://support.enos-iot.com/docs/api/en/3.0.0/api_faqs

Example JSON response for the TSDB Data Service API when 'itemFormat' is set to 1. This format includes assetId, timestamp, localtime, and lists various data points like windspeed and power for each item.

```json
{
  "code": 0,
  "msg": "OK",
  "data": {
    "items": [
      {
        "assetId": "4DXYH7nS",
        "timestamp": 1560249312446,
        "localtime": "2019-06-11T18:35:12.123+08:00",
        "windspeed": "1.1236",
        "power": "1.1236"
      },
      {
        "assetId": "4DXYH7nS",
        "timestamp": 1560249312446,
        "localtime": "2019-06-11T18:35:12.123+08:00",
        "windspeed": "1.1236",
        "power": "1.1236"
      },
      {
        "assetId": "4DXYH7nS",
        "timestamp": 1560249312444,
        "localtime": "2019-06-11T18:35:12.123+08:00",
        "windspeed": "1.1236"
      }
    ]
  }
}
```

--------------------------------

### EnOS IoT API itemFormat=2 Example

Source: https://support.enos-iot.com/docs/api/en/3.0.0/api_faqs

Example JSON response for the TSDB Data Service API when 'itemFormat' is set to 2. This format groups data by pointId and provides arrays for localTime, timestamp, value, and dataQuality for each asset.

```json
{
   "code": 0,
   "msg": "OK",
   "submsg": " ",
   "data": {
      "items": [
         {
            "assetId": "xxx",
            "pointId": "power",
            "localTime": [
               "2020-03-09T20:29:45.222 +08:00",
               "2020-03-09T20:29:45.222 +08:00"
            ],
            "timestamp": [
               1583756985399,
               1583756985399
            ],
            "value": [
               "12.3",
               "17.8"
            ],
            "dataQuality": [
               0,
               1"
            ]
         }
      ]
   }
}
```

--------------------------------

### Update Asset API

Source: https://support.enos-iot.com/docs/api/en/3.0.0/gettingstarted

This endpoint updates the name, description, attributes, timezone, and tags of an asset. The example shows how to use the Java core SDK with API logging enabled.

```APIDOC
## POST /asset-service/v2.1/assets

### Description
Updates an existing asset's properties including its name, description, attributes, timezone, and tags.

### Method
POST

### Endpoint
`https://{apigw-address}/asset-service/v2.1/assets?action=update&orgId={org_id}`

### Parameters
#### Query Parameters
- **action** (string) - Required - Specifies the action to perform, should be 'update'.
- **orgId** (string) - Required - The ID of the organization to which the asset belongs.

#### Request Body
- **asset** (object) - Required - Contains the asset details to be updated.
  - **assetId** (string) - Required - The ID of the asset to update.
  - **name** (object) - Optional - The new name for the asset.
    - **defaultValue** (string) - Optional - The default name.
    - **i18nValue** (object) - Optional - Internationalized names for the asset.
      - **en_US** (string) - Optional - English name.
      - **zh_CN** (string) - Optional - Chinese name.
  - **description** (string) - Optional - The new description for the asset.
  - **attributes** (object) - Optional - Key-value pairs for updated attributes.
  - **timezone** (string) - Optional - The new timezone for the asset.
  - **tags** (object) - Optional - Key-value pairs for updated tags.

### Request Example
```java
import com.enosiot.apim.poseidon.config.PConfig;
import com.enosiot.apim.poseidon.core.Poseidon;

public class UpdateAsset {
    public static void main(String[] args) {
        String accessKey = "{access_key_of_the_application}";
        String secretKey = "{secret_key_of_the_application}";
        String data = "{\"asset\":{\"assetId\":\"{asset_id}\",\"name\":{\"defaultValue\":\"Device_Name\",\"i18nValue\":{\"en_US\":\"Device_Name\",\"zh_CN\":\"Chinese name\"}},\"description\":\"Device_Description\",\"attributes\":{\"Brand\":\"Brand_Name\"},\"timezone\":\"+07:00\",\"tags\":{\"year\":\"2019\",\"site\":\"Site_Name\"}}}";
        String response = Poseidon.config(PConfig.init().appKey(accessKey).appSecret(secretKey).debug())
                .url("https://{apigw-address}/asset-service/v2.1/assets?action=update&orgId={org_id}")
                .method("POST")
                .requestBody(data)
                .sync();
        System.out.println(response);
    }
}
```

### Response
#### Success Response (200)
- **code** (integer) - 0 for success.
- **msg** (string) - "OK" for success.
- **data** (any) - Usually null for update operations upon success.
- **requestId** (string) - Unique request ID.

#### Response Example
```json
{
  "code": 0,
  "msg": "OK",
  "requestId": "9d6b9869-4ffd-4964-a8ff-d150a0d1a91f",
  "data": null
}
```
```

--------------------------------

### Get Access Token API

Source: https://support.enos-iot.com/docs/api/en/3.0.0/token/get_access_token

Retrieves an access token using application credentials. The token is used for authenticating subsequent API requests. If a valid token already exists, it will be returned.

```APIDOC
## POST /apim-token-service/v2.0/token/get

### Description
Get the access token using the access key and secret key of your application. If the access token for your application is already generated, when you call the **Get Access Token** API again, the same access token will be returned if the access token has not expired.

### Method
POST

### Endpoint
`https://{apigw-address}/apim-token-service/v2.0/token/get` (EnOS Cloud API) or `http://{apigw-address}/apim-token-service/v2.0/token/get` (EnOS Edge API)

### Parameters
#### Request Body
- **appKey** (String) - Mandatory - The access key of the application.
- **encryption** (String) - Mandatory - The encrypted ciphertext. See Encryption Generation Rule for details.
- **timestamp** (Long) - Mandatory - The timestamp of the current system time (UNIX time, accurate to the millisecond), e.g. 1572574909697

### Encryption Generation Rule
1. Concatenate the values of `appKey`, `timestamp`, and `appSecret` to generate a string for encryption.
2. Encode the concatenated string in UTF-8 format and make a digest by **SHA256** algorithm.
3. Convert the digest to hexadecimal format to generate the encrypted ciphertext. Example: `sha256(appKey+timestamp+appSecret).toLowerCase()`

### Request Example
```json
{
    "appKey": "5acb82e7-a11e-4300-9164-c8b20b638e8b",
    "encryption": "87c6885cec7525e2f219f86a82b280cc8c2d6ff4040a4b5f8acf9aeeda37aba8",
    "timestamp": 1572574909697
}
```

### Response
#### Success Response (200)
- **status** (Integer) - The API request status code, with 0 indicating a successful request.
- **msg** (String) - The explanation of the status code.
- **business** (String) - The business parameter: 'apim-token-service' (Cloud API) or 'edge-iam' (Edge API).
- **data** (Data Struct) - The generated access token and its expiring time.
  
#### Data Struct
- **accessToken** (String) - The value of the generated access token.
- **expire** (Integer) - The expiring time of the access token in seconds, with an initial value of 7,200 (i.e. 2 hours).

#### Response Example
```json
{
    "status": 0,
    "msg": "SUCCESS",
    "business": "apim-token-service",
    "data": {
        "accessToken": "Generated_Access_Token",
        "expire": 7200
    }
}
```
```

--------------------------------

### EnOS API Example Request - Update Asset (POST Body)

Source: https://support.enos-iot.com/docs/api/en/3.0.0/overview

Demonstrates the structure of a POST request body for updating an asset in EnOS. It includes the API endpoint and a JSON payload containing asset details like modelId, assetId, timezone, description, and tags.

```json
POST
https://{apigw-address}/asset-service/v2.1/assets?action=update&orgId=1234&isPatchUpdate=fasle
{
  "asset": {
    "modelId": "testModel",
    "assetId": "123",
    "timezone": "+08:00",
    "description": "hahdesc",
    "tags": {
      "site": "Shanghai",
      "producer": "ABC"
    }
  }
}

```

--------------------------------

### Internationalized Name Struct Examples

Source: https://support.enos-iot.com/docs/api/en/3.0.0/api_faqs

Demonstrates the structure for representing internationalized names in API requests and responses. It shows two common formats: one with a default value and a map of locale-specific values, and another using locale codes as direct keys.

```json
{
   "defaultValue": "Turbine",
   "i18nValue": {"zh_CN": "Turbine 1", "en_US": "Turbine A"}
}
```

```json
{
        "default": "Turbine",
        "en_US": "Turbine",
        "zh_CN": "风机"
}
```

--------------------------------

### EnOS API Request URI Structure

Source: https://support.enos-iot.com/docs/api/en/3.0.0/overview

Defines the structure of a generic EnOS API request URI, including scheme, API gateway address, service name, version, endpoint, and query parameters. It supports HTTPS and provides examples for constructing valid URIs.

```plaintext
{URI-scheme}://{apigw-address}/{service-name}/{version}/{endpoint-URL}?{query-param=value}

```

--------------------------------

### SHA256 Encryption Pseudo-code

Source: https://support.enos-iot.com/docs/api/en/3.0.0/token/get_access_token

This pseudo-code demonstrates the SHA256 encryption process required for generating the 'encryption' parameter in the token request. It involves concatenating appKey, timestamp, and appSecret, then applying SHA256 and converting to lowercase hexadecimal.

```pseudocode
sha256(appKey+timestamp+appSecret).toLowerCase();
```

--------------------------------

### Add Java Core SDK (Poseidon) Dependency

Source: https://support.enos-iot.com/docs/api/en/3.0.0/gettingstarted

This snippet shows how to add the EnOS Java Core SDK (Poseidon) as a Maven dependency in your `pom.xml` file. Ensure you use the correct version number for your project.

```xml
<dependency>
  <groupId>com.enos-iot</groupId>
  <artifactId>apim-poseidon</artifactId>
  <version>0.2.4</version>
</dependency>
```

--------------------------------

### Synchronous POST Request

Source: https://support.enos-iot.com/docs/api/en/3.0.0/gettingstarted

Provides a sample for making a synchronous POST request using the EnOS Java SDK (Poseidon), including setting headers and the request body.

```java
Poseidon.config(PConfig.init().accessKey(accessKey).secretKey(secretKey).debug())
            .url("https://{apigw-address}/lily/0.0.1/getPublic")
            .method("POST")
            .header("Content-Type", "application/json")
            .header("Cookie", "global_id=IAM_S_S7Yd5WXssqEBCququgzeR9JLNBnWr99S")
            .requestBody(
                "{\n" + "  \"op\": \"pl\",\n" + "  \"offset\": 0,\n" + "  \"limit\": 10\n" + ")")
            .sync();
```

--------------------------------

### EnOS Cloud API Endpoint for Token Get

Source: https://support.enos-iot.com/docs/api/en/3.0.0/token/get_access_token

This snippet shows the POST request endpoint for the EnOS Cloud API to retrieve an access token. It requires the API gateway address and specific service path.

```plaintext
POST https://{apigw-address}/apim-token-service/v2.0/token/get
```

--------------------------------

### Connection Service APIs

Source: https://support.enos-iot.com/docs/api/en/3.0.0/releasenote/enhancement

Behavioral changes for Create Device, Batch Create Devices, and Remove Sub-Device APIs in EnOS 3.0.0.

```APIDOC
## Connection Service APIs

### Description
This section details changes in the Connection Service APIs for EnOS 3.0.0.

### Create Device / Batch Create Devices
#### Description
- When the request parameter `productKey` is empty, the request will fail and return a parameter error.
- Supports providing multiple values for the request parameter `productKey` to create devices for multiple products simultaneously in Batch Create Devices.

### Method
POST

### Endpoint
`/api/connection/devices` (example endpoint for create)
`/api/connection/devices/batch` (example endpoint for batch create)

### Parameters
#### Request Body (Create Device)
- **productKey** (string) - Required - The product key of the device.
- **deviceKey** (string) - Required - The unique key for the device.

#### Request Body (Batch Create Devices)
- **products** (array of objects) - Required - List of products to create devices for.
  - **productKey** (string) - Required - The product key.
  - **devices** (array of objects) - Required - List of devices to create for this product.
    - **deviceKey** (string) - Required - The unique key for the device.

### Request Example (Batch Create)
```json
{
  "products": [
    {
      "productKey": "ProductA",
      "devices": [
        {"deviceKey": "DeviceA1"},
        {"deviceKey": "DeviceA2"}
      ]
    },
    {
      "productKey": "ProductB",
      "devices": [
        {"deviceKey": "DeviceB1"}
      ]
    }
  ]
}
```

### Remove Sub-Device
#### Description
When the request parameter `subDevices` is empty, the request will still succeed, but no sub-devices will be removed.

### Method
DELETE

### Endpoint
`/api/connection/devices/{parentId}/subdevices` (example endpoint)

### Parameters
#### Path Parameters
- **parentId** (string) - Required - The ID of the parent device.

#### Request Body
- **subDevices** (array of strings) - Optional - A list of sub-device keys to remove.
```

--------------------------------

### EnOS Edge API Endpoint for Token Get

Source: https://support.enos-iot.com/docs/api/en/3.0.0/token/get_access_token

This snippet shows the POST request endpoint for the EnOS Edge API to retrieve an access token. It requires the API gateway address and specific service path.

```plaintext
POST http://{apigw-address}/apim-token-service/v2.0/token/get
```

--------------------------------

### Asset Tree Service APIs

Source: https://support.enos-iot.com/docs/api/en/3.0.0/releasenote/enhancement

Changes for Search Asset Tree and Search Asset Path APIs in EnOS 3.0.0.

```APIDOC
## Asset Tree Service APIs

### Description
This section details changes in the Asset Tree Service APIs for EnOS 3.0.0.

### Search Asset Tree
#### Description
If the request parameter `pagination` is not specified, the default is 10 records per page.

### Method
GET

### Endpoint
`/api/asset/tree/search` (example endpoint)

### Parameters
#### Query Parameters
- **pagination** (object) - Optional - Pagination settings.
  - **pageSize** (integer) - Optional - Number of records per page (defaults to 10).
  - **pageNumber** (integer) - Optional - The page number to retrieve.

### Search Asset Path
#### Description
The response parameter `totalSize` will return the number of first-level child nodes, excluding the number of subordinate nodes under those child nodes.

### Method
GET

### Endpoint
`/api/asset/tree/path/{assetId}` (example endpoint)

### Parameters
#### Path Parameters
- **assetId** (string) - Required - The ID of the asset.

#### Response
#### Success Response (200)
- **totalSize** (integer) - The number of first-level child nodes.
- **path** (array) - The asset path.
```

--------------------------------

### Data Download Service API

Source: https://support.enos-iot.com/docs/api/en/3.0.0/releasenote/new_feature

APIs for managing data download tasks, including querying channels, creating requests, and monitoring status.

```APIDOC
## Data Download Service

### List Channels

Query the data read channels and data write channels authorized for the application.

### Method
GET

### Endpoint
/download/channels

### Response
#### Success Response (200)
- **channels** (object) - Object containing read and write channels.
  - **read_channels** (array) - List of available read channels.
  - **write_channels** (array) - List of available write channels.

#### Response Example
```json
{
  "channels": {
    "read_channels": ["channel_A", "channel_B"],
    "write_channels": ["channel_X", "channel_Y"]
  }
}
```

### Create Download Request

Create a file download task.

### Method
POST

### Endpoint
/download/requests

### Parameters
#### Request Body
- **channel** (string) - Required - The channel to use for downloading.
- **query** (object) - Required - The query parameters for the data to download.
- **filename** (string) - Required - The desired name for the downloaded file.

### Request Example
```json
{
  "channel": "channel_A",
  "query": {
    "device_id": "dev_001",
    "time_range": {
      "start": "2023-01-01T00:00:00Z",
      "end": "2023-01-01T23:59:59Z"
    }
  },
  "filename": "device_data.csv"
}
```

### Response
#### Success Response (200)
- **request_id** (string) - The ID of the created download request.

#### Response Example
```json
{
  "request_id": "req_abc"
}
```

### Get Download Status

Get the status of the file download task.

### Method
GET

### Endpoint
/download/status/{request_id}

### Parameters
#### Path Parameters
- **request_id** (string) - Required - The ID of the download request.

### Response
#### Success Response (200)
- **status** (string) - The current status of the download (e.g., 'pending', 'processing', 'completed', 'failed').
- **progress** (integer) - The progress of the download in percentage.
- **download_url** (string) - The URL to download the file if completed.

#### Response Example
```json
{
  "status": "completed",
  "progress": 100,
  "download_url": "http://example.com/downloads/device_data.csv"
}
```

### Cancel Download

Cancel the file download task.

### Method
DELETE

### Endpoint
/download/requests/{request_id}

### Parameters
#### Path Parameters
- **request_id** (string) - Required - The ID of the download request to cancel.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Download request cancelled successfully."
}
```
```

--------------------------------

### Data Subscription Service API

Source: https://support.enos-iot.com/docs/api/en/3.0.0/releasenote/new_feature

APIs for managing data subscriptions, including retrieving subscription lists, details, and updating jobs.

```APIDOC
## Data Subscription Service

### Get Subscription List

Get the list of the subscription jobs in the OU.

### Method
GET

### Endpoint
/subscriptions

### Parameters
#### Query Parameters
- **ou_id** (string) - Required - The organization unit ID.

### Response
#### Success Response (200)
- **subscriptions** (array) - A list of subscription jobs.
  - **id** (string) - The subscription job ID.
  - **name** (string) - The subscription job name.

#### Response Example
```json
{
  "subscriptions": [
    {
      "id": "sub_123",
      "name": "Sales Data Subscription"
    }
  ]
}
```

### Update Subscription Job

Update a subscription job.

### Method
PUT

### Endpoint
/subscriptions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the subscription job to update.

#### Request Body
- **name** (string) - Optional - The new name for the subscription job.
- **status** (string) - Optional - The new status for the subscription job (e.g., 'active', 'inactive').

### Request Example
```json
{
  "name": "Updated Sales Data Subscription",
  "status": "active"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Subscription job updated successfully."
}
```
```

--------------------------------

### Tag Usage

Source: https://support.enos-iot.com/docs/api/en/3.0.0/api_faqs

Details on how tags are used for object management and searching within the EnOS service.

```APIDOC
## Tag Usage

Tags are used to manage and search for objects. They are structured as a Map with String keys and String values.

### Key Constraints

- Allowed characters: letters, numbers, underscores, hyphens (-), and slashes (/)
- Maximum length: 50 characters

### Value Constraints

- Cannot start or end with a space
- Maximum length: 200 characters

**Note**: When updating tags, the entire tag set must be provided. For example, to add a new tag, include existing tags along with the new one in the request.
```

--------------------------------

### Invoking API with Access Token

Source: https://support.enos-iot.com/docs/api/en/3.0.0/token/invoke_api_with_access_token

This section outlines the procedure for making API requests to EnOS using an access token. It covers constructing the necessary data for authentication and signing the request.

```APIDOC
## Invoking API with Access Token

Follow the instructions below to invoke EnOS APIs with the generated access token.

### Before You Start

*   Before invoking an EnOS API with the access token, you need to have the values of **appKey**(`AccessKey`), **appSecret**(`SecretKey`), **accessToken** , and **timestamp** ready.

### Procedure

#### Constructing `paramsData`

1.  Sort all the parameters of the API in the URL by ASCII order.
2.  Concatenate the sorted parameters and their values into a string.
3.  If the API request requires a JSON formatted request body, append the request body after the concatenated string to form the `paramsData`.

    *Note: The request body that is included in the paramsData must be identical with what is set in the API request. Otherwise, the verification will fail.*

#### Constructing `apim-sign`

1.  Concatenate the values of `accessToken`, `paramsData`, `timestamp`, and `appSecret` into a string to form the `signData`.
2.  Encode the concatenated string `signData` in UTF-8 format and make a digest by **SHA256** algorithm.
3.  Convert the digest to hexadecimal format to generate the encrypted ciphertext `apim-sign`.
    ```
    sha256(signData).toLowerCase();
    ```

#### Constructing the Request Header

Include the following parameters in the API request header:

```
apim-accesstoken: accessToken
apim-signature: apim-sign
apim-timestamp: timestamp
```

### Error Codes

Code | Description  
---|---
0 | Success  
1001 | Repeated requests with duplicated `encryption`.  
1002 | The `appKey` does not exist.  
1003 | The `encryption` is not valid.  
1004 | Invalid parameter.  
1005 | Internal service exception.  
1202 | The parameter is empty.  
1203 | The access token has expired.  
1204 | Failed to refresh access token.  

### Sample

The following example shows the steps of invoking an API with the access token.

#### Request URL

```
https://{apigw-address}/m/v1/b?k3=v3&k1=v1&k2=v2
```

#### Request Body

```json
{
  "count": 20,
  "page": 1,
  "desc": "description"
}
```

#### Request Parameters

Parameter | Value  
---|---
accessToken | xxxxaaaxxxx  
appSecret | xxxappSecretxxx  
timestamp | 1572574909697  

#### Request Steps

1.  Sort the parameters k3, k1, k2 in the URL by ASCII order into k1, k2, k3.
2.  Concatenate the sorted parameters and their values into a string, for example, `k1v1k2v2k3v3`.
3.  Concatenate the string `k1v1k2v2k3v3` and the request body to form the `paramsData`.
    ```
    k1v1k2v2k3v3{
    "count": 20,
    "page": 1,
    "desc": "description"
    }
    ```
4.  Concatenate the values of `accessToken`, `paramsData`, `timestamp`, and `appSecret`.
    ```
    xxxxaaaxxxxk1v1k2v2k3v3{
    "count": 20,
    "page": 1,
    "desc": "description"
    }1572574909697xxxappSecretxxx
    ```
5.  Encode the above concatenated string in UTF-8 format and make a digest by **SHA256** algorithm. Convert the digest to hexadecimal format to generate a signature as the `apim-signature`.
    ```
    59828328f6c1f9771015dc74e4929ae30f518a35a3d2353972c2ea46556fc981
    ```
6.  Send the API request, for example:
    ```bash
    curl https://{apigw-address}/m/v1/b?k3=v3&k1=v1&k2=v2 -X POST \
    -H 'apim-accesstoken:xxxxaaaxxxx' \
    -H 'apim-signature:59828328f6c1f9771015dc74e4929ae30f518a35a3d2353972c2ea46556fc981' \
    -H 'apim-timestamp:1572574909697' \
    -d '{
    "count": 20,
    "page": 1,
    "desc": "description"
    }'
    ```
```

--------------------------------

### Device Specification

Source: https://support.enos-iot.com/docs/api/en/3.0.0/api_faqs

Outlines the methods for specifying a device in API requests.

```APIDOC
## Device Specification

Devices can be specified in API requests using one of the following methods:

1.  **Using `assetId`**:
    *   **Name**: `assetId`
    *   **Data Type**: String
    *   **Mandatory/Optional**: Optional
    *   **Description**: The unique asset ID.

2.  **Using `productKey` and `deviceKey`**:
    *   **Name**: `productKey`
    *   **Data Type**: String
    *   **Mandatory/Optional**: Optional
    *   **Description**: The product key. Must be used with `deviceKey`.
    *   **Name**: `deviceKey`
    *   **Data Type**: String
    *   **Mandatory/Optional**: Optional
    *   **Description**: The device key. Must be used with `productKey`.

At least one of these methods must be used to specify the device.
```

--------------------------------

### EnOS API Request Structure

Source: https://support.enos-iot.com/docs/api/en/3.0.0/overview

Explains the structure of an EnOS API request, including the Request URI, Request Header, and Request Body.

```APIDOC
## EnOS API Request Structure

### Request URI

```
{URI-scheme}://{apigw-address}/{service-name}/{version}/{endpoint-URL}?{query-param=value}
```

- `URI-scheme`: The protocol, supporting HTTPS.
- `apigw-address`: The IP address or domain name of the EnOS API service (e.g., `apim-eu2.enos-iot.com`).
- `service-name`: The name of the service (e.g., `asset-service`).
- `version`: The API version (e.g., `v2.0`).
- `endpoint-URL`: The resources and operations on resources (e.g., `assets/update`).
- `query-param`: Parameters and values for the target resource (e.g., `orgId=1234`). Multiple parameters are connected by `&`.

**Example:**
```
GET https://{apigw-address}/asset-service/v2.1/assets?action=get&orgId=1234&assetId=abcd
```

### Request Header

Includes fields required by REST API and HTTP specifications. Commonly used is `Content-Type` (e.g., `application/json;charset=UTF-8`, `Multipart/form-data;charset=UTF-8`).

### Request Body

Supplements the Request URI for complex input parameters.

**Example for updating an asset:**
```
POST
https://{apigw-address}/asset-service/v2.1/assets?action=update&orgId=1234&isPatchUpdate=fasle
{
  "asset": {
    "modelId": "testModel",
    "assetId": "123",
    "timezone": "+08:00",
    "description": "hahdesc",
    "tags": {
      "site": "Shanghai",
      "producer": "ABC"
    }
  }
}
```
```

--------------------------------

### Public Request Parameters

Source: https://support.enos-iot.com/docs/api/en/3.0.0/overview

Details common parameters used across various EnOS API services, including pagination and projection.

```APIDOC
## Public Request Parameters

### Pagination Request Struct
Used for paginating results. Default page size is 10.

#### Parameters
- **pageNo** (Integer) - Mandatory - The requested page number, starting from 1 (or 0 for Application Portal).
- **pageSize** (Integer) - Mandatory - The number of records per page (must be > 0).
- **sorters** (Sorter struct) - Optional - Specifies sorting criteria.
  
  **Sorter struct**:
  - **field** (String) - Mandatory - The field to sort by.
  - **order** (String) - Optional - Sort order ('ASC' or 'DESC'). Defaults to 'ASC'.

#### Pagination Parameter Sample
```json
{
    "pagination": {
        "pageNo": 2,
        "pageSize": 100,
        "sorters": [{
            "field": "assetId",
            "order": "ASC"
        }]
    }
}
```

### Projection Parameter
Used to filter the fields returned in the response.

#### Parameters
- **projection** (String Array) - Optional - An array of strings, where each string specifies a field to include in the response. Symbols `[*]`, `*`, and `.` have special meanings for array elements, any field, and sub-fields respectively.

#### Projection Parameter Sample
```json
{
    "projection": [
        "assetPaths", 
        "assets.*.assetId"
    ]
}
```
```

--------------------------------

### Public Response Parameters

Source: https://support.enos-iot.com/docs/api/en/3.0.0/overview

Details common response parameters applicable to several EnOS API services.

```APIDOC
## Public Response Parameters

### Response Fields
- **pagination** (Pagination response struct) - Information about the pagination of the returned results.
```
Tokens:
Raw