Cloud Phone Control API - Documentation

Feature Overview

Hive Cloud Box provides complete REST API interface, supporting remote control of cloud phones via HTTP, covering device information query, cloud phone CRUD, proxy management, system configuration updates and other functions, facilitating integration into automation systems or custom management platforms.

Base API address: http://deviceIP:3001/api/1_0

General Information

Item	Description
Protocol	HTTP
Response Format	JSON
Authorization	Some interfaces require authorization (see details below)
Device IP	Get from NestBrowser client

GET /systeminfo

Get device system information.

Requires Authorization: No

Response Parameters:

{
  "data": {
    "id": "1",
    "dev": "Device Serial Number",
    "mac": "02:42:53:7e:6b:88",
    "cpu": "3.38%",
    "mem": "57.44%--15.57GB",
    "version": "1.1.35",
    "sDisk": "13.52%-57.79GB",
    "nvmDisk": "11.87%-468.38GB",
    "temp": "52.69°C",
    "desc": "License valid, expiration time: 2024-10-12 15:48:20"
  }
}

Field	Description
cpu	CPU usage rate
mem	Memory usage rate and total amount
sDisk	System disk usage
nvmDisk	Data disk usage
temp	Device temperature
desc	License status and expiration time

POST /licenses

Set device license information.

Requires Authorization: No

Request Parameters:

{
  "license": "License string"
}

Response:

{ "valid": true }

GET /get_container_list

Get list of all current cloud phones.

Requires Authorization: No

Response Parameters:

[
  { "id": 1, "model": "Redmi-M2003J15SC" },
  { "id": 2, "model": "Redmi-M2003J15SC" }
]

GET /get_container_info/:id

Get detailed information of specified cloud phone.

Requires Authorization: Yes

Path Parameters: :id — Cloud Phone ID

Response Parameters:

{
  "id": 1,
  "model": "Redmi-M2003J15SC",
  "status": "created",
  "wifi_status": "created"
}

status value	Description
created	Powered off
running	Running

wifi_status value	Description
created	Initializing
running	Can screen cast

GET /get_online_index

Get index available for creating cloud phones.

Requires Authorization: Yes

Response: Number (available index position)

GET /get_img_list

Get list of images provided by MX.

Requires Authorization: Yes

GET /get_model_list

Get list of device models provided by MX.

Requires Authorization: Yes

POST /create_container

Create cloud phone instance.

Requires Authorization: Yes

Request Parameters:

{
  "tag": "mx-20250521-gms-normal",
  "model": "Redmi-Note-7",
  "amount": 1,
  "dns": "223.5.5.5"
}

Parameter	Required	Description
tag	Yes	Firmware version
model	Yes	Device model name
amount	Yes	Number to create (≥1)
dns	No	DNS server address

Response: true or false

GET /run/:id

Start cloud phone.

Requires Authorization: Yes

Response: true or false

GET /stop/:id

Stop cloud phone.

Requires Authorization: Yes

Response: true or false

GET /remove/:id

Delete cloud phone.

Requires Authorization: Yes

Response: true or false

GET /updatedeclare/:id/:declare

Update cloud phone description.

Requires Authorization: Yes

Path Parameters:

Parameter	Description
:id	Cloud Phone ID
:declare	New description text

Response: true or false

POST /s5_set

Set cloud phone SOCKS5 proxy information.

Requires Authorization: Yes

Request Parameters:

{
  "id": "1",
  "proxyurl": "Base64 encoded proxy info"
}

Proxy info needs to be Base64 encoded first, original format:

{
  "type": "socks5",
  "lookupUrl": "https://nestbrowser.com/api/cpi/ip-lookup",
  "proxy_status": 0,
  "host": "1.1.1.1",
  "port": "1000",
  "user": "Username",
  "password": "Password"
}

Response: { "valid": true }

GET /s5_query/:id

Query cloud phone proxy information.

Requires Authorization: Yes

Response: JSON data containing proxy status

GET /s5_start/:id

Start cloud phone proxy.

Requires Authorization: Yes

Response: true or false

GET /s5_stop/:id

Stop cloud phone proxy.

Requires Authorization: Yes

Response: true or false

GET /install_image/:tag

Install image.

Requires Authorization: Yes

Response: true or false

GET /remove_image/:tag

Remove image.

Requires Authorization: Yes

Response: true or false

POST /update_config

Modify cloud phone configuration, including OAID, IMEI, GPS and other parameters.

Requires Authorization: Yes

Request Parameters:

{
  "id": "12345",
  "data": {
    "oaid": {
      "oaid": "d8a8d7f0-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
      "vaid": "v1234567890",
      "uaid": "u9876543210",
      "aaid": "a1234567890abcdef"
    },
    "gsm": {
      "imei": "123456789012345",
      "phone": "+8613812345678",
      "modeType": "LTE"
    },
    "system": {
      "timezone": "Asia/Shanghai",
      "locale": "zh-CN"
    },
    "gps": [
      "LatitudeDegrees=25.041026818001678",
      "LongitudeDegrees=121.52334876982831",
      "AltitudeMeters=1.60062531",
      "BearingDegrees=0",
      "SpeedMetersPerSec=0"
    ]
  }
}

Response: true or false

ADB Port Rule

After obtaining cloud phone ID via API, you can calculate ADB connection port by the following formula:

ADB Port = Cloud Phone ID + 12000

Connection example:

# When Cloud Phone ID = 1
adb connect 192.168.0.100:12001