API Documentation

Last Updated: December 4, 2025

Document Introduction

This document provides a complete API interface specification for CBS (Cloud Box Service) edge computing box service. CBS service is used to manage and control Android container instances running on edge devices, supporting full lifecycle management including instance creation, startup, shutdown, configuration, etc.

Quick Start

Basic Information

Service Address: http://{ip}:{port}
Default Port: 18182
Data Format: All interfaces use JSON format for data exchange
Request Method: Supports both GET and POST request methods

API Categories

This document contains the following API categories:

Host APIs - Host hardware information, system status, image management, etc.
Instance APIs - Instance lifecycle management including creation, startup, shutdown, deletion, etc.
Proxy Operations - Configure network proxy for instances
Android Control APIs - Various operations on Android instances (ADB commands, GPS, video injection, etc.)
Interface Logs - Interface call records and statistics
SSD Management - Storage device management and configuration
Version Update - CBS service version update

Usage Instructions

Replace {ip} in the document with the actual CBS service host IP address
Replace {port} in the document with the actual port number (default is 18182)
Replace {db_id} in the document with the actual instance ID (format: EDGE + 12 random characters)

Host APIs

Host-related APIs

Get Host Configuration Information

API Description: Returns device hardware and basic runtime information.

Request URL: http://{ip}:{port}/v1/get_hardware_cfg

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
-	-	-	None

Request Example:

GET http://192.168.30.2:18182/v1/get_hardware_cfg

Response Example:

Success:

json


{
    "code": 200,
    "msg": "success",
    "data": {
        "cpuload": "24%",
        "cputemp": 38,
        "device_id": "b00133052a52c46f",
        "hwaddr": "4e:d8:06:98:07:f4",
        "ip": "192.168.11.235",
        "kernel_version": "1.0.86_marsbox",
        "mem_total": "31764",
        "mem_use": "5797",
        "mmc_total": "25923",
        "mmc_use": "819",
        "model": "L1",
        "os_version": "1.0.1",
        "ssd_total": "239280",
        "ssd_use": "10333",
        "version": "1.0.12.2.1"
    }
}

Failure:

json


{
    "code": 0,
    "error": "Error reason"
}

Get Host System Information

API Description: Returns CPU usage, disk/memory usage, temperature, swap, and other metrics.

Request URL: http://{ip}:{port}/v1/systeminfo

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
-	-	-	None

Request Example:

GET http://192.168.30.2:18182/v1/systeminfo

Response Example:

Success:

json


{
    "code": 200,
    "msg": "success",
    "data": {
        "cpu": 18.6,
        "mem_percent": 18.3,
        "mem_total": 31764,
        "mmc_percent": 3.2,
        "mmc_total": 25923,
        "ssd_percent": 4.3,
        "ssd_total": 239280,
        "swap_percent": 0.7,
        "swap_total": 4095,
        "temperatures": 38
    }
}

Failure:

json


{
    "code": 0,
    "error": "Error reason"
}

Get Host Network Configuration

API Description: Returns the host's current gateway, subnet mask, and subnet segment.

Request URL: http://{ip}:{port}/v1/net_info

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
-	-	-	None

Request Example:

GET http://192.168.30.2:18182/v1/net_info

Response Example:

Success:

json


{
    "code": 200,
    "msg": "success",
    "data": {
        "gateway": "192.168.10.1",
        "host_ip": "192.168.11.235",
        "netmask": "255.255.254.0",
        "subnet": "192.168.10.0/23"
    }
}

Failure:

json


{
    "code": 0,
    "error": "Error reason"
}

Host Heartbeat Check

API Description: Checks host HTTP/Docker/Ping availability.

Request URL: http://{ip}:{port}/v1/heartbeat

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
-	-	-	None

Request Example:

GET http://192.168.30.2:18182/v1/heartbeat

Response Example:

Success:

json


{
    "code": 200,
    "msg": "Host is normal",
    "data": {
        "docker_status": true,
        "http_status": true,
        "ping_status": true
    }
}

Failure:

json


{
    "code": 0,
    "error": "Error reason"
}

Get Host Image List

API Description: Returns the repository and image_id of the docker images list.

Request URL: http://{ip}:{port}/v1/get_img_list

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
-	-	-	None

Request Example:

GET http://192.168.30.2:18182/v1/get_img_list

Response Example:

Success:

json


{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "repository": "armcloud/demo:latest",
            "image_id": "sha256:..."
        }
    ]
}

Failure:

json


{
    "code": 0,
    "error": "Error reason"
}

Prune Unused Images

API Description: Cleans up unused Docker images on the host

Request URL: http://{ip}:{port}/v1/prune_images

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
-	-	-	None

Request Example:

GET http://192.168.30.2:18182/v1/prune_images

Response Example:

Success:

json


{
    "code": 200,
    "msg": "success",
    "data": {
        "freed_mb": "2957.40",
        "host_ip": "192.168.11.235",
        "images": [
            "vcloud_android13_edge_20251130185425"
        ]
    }
}

Failure:

json


{
    "code": 0,
    "error": "Error reason"
}

Import Image

API Description: Upload image file to host and load image

Streaming Response Description: The interface uses NDJSON format to stream progress information (Content-Type: application/x-ndjson), one JSON object per line.

Stage Description:

Uploading: Uploading (upload_progress=100%, load_progress=0%)
Loading: Loading (upload_progress=100%, load_progress=1-99%)
Success: Success (upload_progress=100%, load_progress=100%)
Failed: Failed (upload_progress=100%, load_progress=0%)

Request URL: http://{ip}:{port}/v1/import_image

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
file	Yes	file	Image file (.tar.gz or .tar format)

Request Example:

POST http://192.168.30.2:18182/v1/import_image

Request Body: multipart/form-data

file: (file)

Response Example:

Streaming Response (NDJSON format, one JSON object per line):

{"stage":"Uploading","upload_progress":100,"load_progress":0,"message":"File upload completed: android13.tar.gz (542.15 MB)"}
{"stage":"Loading","upload_progress":100,"load_progress":1,"message":"Loading image to Docker..."}
{"stage":"Loading","upload_progress":100,"load_progress":2,"message":"Loading image... (2%)"}
{"stage":"Loading","upload_progress":100,"load_progress":3,"message":"Loading image... (3%)"}
...
{"stage":"Success","upload_progress":100,"load_progress":100,"message":"Image imported successfully: vcloud_android13_edge_20250925011125:latest","data":{"host_ip":"192.168.10.20","image_name":"vcloud_android13_edge_20250925011125:latest","file_size":568524800}}

Failure:

json


{
    "code": 0,
    "data": {},
    "msg": "File upload failed: request Content-Type isn't multipart/form-data"
}

Set Swap Switch

API Description: Sets the host swap partition status: 1 to enable, 0 to disable. Default is disabled; can be enabled after inserting SSD; swap partition default size is 8G (located at /container_nswc_lv/.swapfile).

Request URL: http://{ip}:{port}/v1/swap/{enable}

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
enable	Yes	string	1=enable 0=disable

Request Example:

GET http://192.168.30.2:18182/v1/swap/example_value

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "host_ip": "192.168.11.235"
    },
    "msg": {
        "swap_percent": 0,
        "swap_total": 8589930496
    }
}

Failure:

json


{
    "code": 0,
    "error": "Error reason"
}

Reboot Host

API Description: Asynchronously reboots the host after the command is issued.

Request URL: http://{ip}:{port}/v1/reboot_for_arm

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
-	-	-	None

Request Example:

GET http://192.168.30.2:18182/v1/reboot_for_arm

Response Example:

Success:

json


{
    "code": 200,
    "msg": "rebooting"
}

Failure:

json


{
    "code": 0,
    "error": "Error reason"
}

Reset Host

API Description: Destroys containers, cleans mappings, formats and mounts data disk, cleans root partition, then reboots.

Request URL: http://{ip}:{port}/v1/reset

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
-	-	-	None

Request Example:

GET http://192.168.30.2:18182/v1/reset

Response Example:

Success:

json


{
    "code": 200,
    "msg": "resetting and rebooting"
}

Failure:

json


{
    "code": 0,
    "error": "Error reason"
}

Discovery Service Status

API Description: Returns UDP responder status.

Request URL: http://{ip}:{port}/v1/discover

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
-	-	-	None

Request Example:

GET http://192.168.30.2:18182/v1/discover

Response Example:

Success:

json


{
    "code": 200,
    "msg": "UDP discovery service status",
    "data": {
        "udp_responder": {
            "device_id": "b00133052a52c46f",
            "friendly_name": "marsbox",
            "port": 7678,
            "running": true,
            "service": "UDP responder"
        }
    }
}

Failure:

json


{
    "code": 0,
    "error": "Error reason"
}

Instance APIs

Instance lifecycle APIs

Rename Instance

API Description: Modifies user_name, i.e., cloud machine name.

Request URL: http://{ip}:{port}/container_api/v1/rename/{db_id}/{new_user_name}

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
db_id	Yes	string	Instance unique identifier (EDGE + 12 random characters)
new_user_name	Yes	string	New user_name (display name, length 2-40)

Request Example:

GET http://192.168.30.2:18182/container_api/v1/rename/EDGE0A1B2C3D4E5/new_name

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "db_id": "EDGEF58PN1AB43UA",
        "host_ip": "192.168.11.235",
        "name": "EDGEF58PN1AB43UA",
        "old_user_name": "vmos",
        "user_name": "test-rename"
    },
    "msg": "success"
}

Failure:

json


{
    "code": 202,
    "data": {
        "db_id": "EDGEINVALID12345",
        "host_ip": "192.168.11.235"
    },
    "msg": "container not found"
}

Create Instance

API Description: Creates Android instance (bridge network, sandbox storage, dynamic port allocation).

Request URL: http://{ip}:{port}/container_api/v1/create

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
user_name	Yes	string	Required, instance username, 2-36 characters of numbers/letters, supports _.-
count	No	int	Optional, batch creation count, default 1, maximum 16
bool_start	No	boolean	Optional, whether to start instance immediately, default false
bool_macvlan	No	boolean	Optional, whether to enable macvlan dual network card mode (bridge+macvlan), default false. When enabled, instance will get independent LAN IP
macvlan_network	No	string	Optional, macvlan network name, default macvlan100. Only effective when bool_macvlan=true
macvlan_start_ip	No	string	Optional, macvlan starting IP address, only effective when bool_macvlan=true. When count=1, directly use specified IP (requires ARP detection), when count>1, incrementally allocate from starting IP. For example 192.168.10.100
image_repository	No	string	Local image name (without tag), default value is vcloud_android13_edge_20250925011125
resolution	No	object	Resolution configuration object, contains dpi, fps, height, width fields
selinux	No	boolean	Whether to enable SELinux
dns	No	array<string>	DNS server list
adiName	No	string	Optional, ADI template file name (must be uploaded to /etc/adi/ via /v1/import_adi first)
adiPass	No	string	Optional, ADI extraction password
lon	No	float	Optional, longitude. For example 121.5
lat	No	float	Optional, latitude. For example 31.2
locale	No	string	Optional, language. For example zh-CN
timezone	No	string	Optional, timezone. For example Asia/Shanghai
country	No	string	Optional, country code (ISO Alpha-2) used for random Android property generation. Defaults to CN when not specified.
bool_gms_disabled	No	boolean	Optional, whether to disable GMS when creating container, true=disable, false=don't disable, if not passed, use value from game.info

Request Example:

POST http://192.168.30.2:18182/container_api/v1/create

Request Body:

json


{
    "user_name": "test-001",
    "bool_start": false,
    "image_repository": "vcloud_android13_edge_20250925011125",
    "adiName": "template.zip",
    "adiPass": "password",
    "resolution": {
        "dpi": 560,
        "fps": 60,
        "height": 3040,
        "width": 1440
    },
    "selinux": false,
    "dns": [
        "8.8.8.8",
        "1.1.1.1"
    ],
    "bool_gms_disabled": false
}

Response Example:

Success:

json


{
    "code": 200,
    "msg": "success",
    "data": {
        "host_ip": "192.168.10.102",
        "list": [
            {
                "db_id": "EDGE0A1B2C3D4E5",
                "name": "EDGE0A1B2C3D4E5",
                "user_name": "test-001",
                "status": "creating",
                "message": "Creating...",
                "short_id": "",
                "id": "",
                "adb": 21000,
                "ip": "",
                "data": "/container_nswc_lv/EDGE0A1B2C3D4E5/data",
                "dns": "8.8.8.8",
                "dpi": "560",
                "fps": "60",
                "height": "3040",
                "width": "1440",
                "image": "vcloud_android13_edge_20250925011125:latest",
                "memory": 3072,
                "aosp_version": "13",
                "s5": {
                    "status": 0,
                    "statusText": "Not started"
                },
                "state": "creating",
                "created": "2025-10-11 12:00:00",
                "host_ip": "192.168.10.102"
            }
        ]
    }
}

Failure:

json


{
    "code": 0,
    "data": "Image not found locally: vcloud_android13_edge_20250925011125:latest",
    "msg": "Image does not exist"
}

json


{
    "code": 2,
    "msg": "invalid user_name: length must be 2-36"
}

Batch Start Instances (Async)

Request URL: http://{ip}:{port}/container_api/v1/run

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
db_ids	Yes	array<string>	Instance ID array, supports single or multiple instance IDs

Request Example:

POST http://192.168.30.2:18182/container_api/v1/run

Request Body:

json


{
    "db_ids": [
        "dev_0",
        "dev_1"
    ]
}

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "host_ip": "192.168.11.235",
        "list": [
            {
                "db_id": "EDGEF58PN1AB43UA",
                "name": "EDGEF58PN1AB43UA",
                "state": "starting",
                "user_name": "test-rename"
            }
        ]
    },
    "msg": "success"
}

Failure:

json


{
    "code": 460,
    "data": {
        "host_ip": "192.168.11.235"
    },
    "msg": "Another run task is in progress"
}

json


{
    "code": 1,
    "data": {
        "host_ip": "192.168.11.235"
    },
    "msg": "Invalid db_id value detected."
}

Batch Stop Instances (Async)

Request URL: http://{ip}:{port}/container_api/v1/stop

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
db_ids	Yes	array<string>	Instance ID array, supports single or multiple instance IDs

Request Example:

POST http://192.168.30.2:18182/container_api/v1/stop

Request Body:

json


{
    "db_ids": [
        "deviceId_0_test-001",
        "deviceId_1_test-002"
    ]
}

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "host_ip": "192.168.11.235",
        "list": [
            {
                "db_id": "EDGEF58PN1AB43UA",
                "name": "EDGEF58PN1AB43UA",
                "state": "stopping",
                "user_name": "test-rename"
            }
        ]
    },
    "msg": "success"
}

Failure:

json


{
    "code": 1,
    "data": {
        "host_ip": "192.168.11.235"
    },
    "msg": "Invalid db_id value detected."
}

Batch Reboot Instances (Async)

Request URL: http://{ip}:{port}/container_api/v1/reboot

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
db_ids	Yes	array<string>	Instance ID array, supports single or multiple instance IDs

Request Example:

POST http://192.168.30.2:18182/container_api/v1/reboot

Request Body:

json


{
    "db_ids": [
        "deviceId_0_test-001",
        "deviceId_1_test-002"
    ]
}

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "host_ip": "192.168.11.235",
        "list": [
            {
                "db_id": "EDGEF58PN1AB43UA",
                "name": "EDGEF58PN1AB43UA",
                "state": "rebooting",
                "user_name": "test-rename"
            }
        ]
    },
    "msg": "success"
}

Failure:

json


{
    "code": 2,
    "data": {
        "host_ip": "192.168.11.235"
    },
    "msg": "Some instances are not in the 'running' state"
}

json


{
    "code": 1,
    "data": {
        "host_ip": "192.168.11.235"
    },
    "msg": "Invalid db_id value detected."
}

Batch Reset Instances (Async)

Request URL: http://{ip}:{port}/container_api/v1/reset

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
db_ids	Yes	array<string>	Instance ID array, supports single or multiple instance IDs

Request Example:

POST http://192.168.30.2:18182/container_api/v1/reset

Request Body:

json


{
    "db_ids": [
        "EDGE0A1...",
        "EDGE6F7..."
    ]
}

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "host_ip": "192.168.11.235",
        "list": [
            {
                "db_id": "EDGEF58PN1AB43UA",
                "name": "EDGEF58PN1AB43UA",
                "state": "rebuilding",
                "user_name": "test-rename"
            }
        ]
    },
    "msg": "success"
}

Failure:

json


{
    "code": 2,
    "data": {
        "host_ip": "192.168.11.235"
    },
    "msg": "Some instances are not in the 'running' state"
}

json


{
    "code": 1,
    "data": {
        "host_ip": "192.168.11.235"
    },
    "msg": "Invalid db_id value detected."
}

Batch Delete Instances (Async)

Request URL: http://{ip}:{port}/container_api/v1/delete

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
db_ids	Yes	array<string>	Instance ID array, supports single or multiple instance IDs

Request Example:

POST http://192.168.30.2:18182/container_api/v1/delete

Request Body:

json


{
    "db_ids": [
        "EDGE0A1...",
        "EDGE6F7..."
    ]
}

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "host_ip": "192.168.11.235",
        "list": [
            {
                "db_id": "EDGEF58PN1AB43UA",
                "name": "EDGEF58PN1AB43UA",
                "state": "deleting",
                "user_name": "test-rename"
            }
        ]
    },
    "msg": "success"
}

Failure:

json


{
    "code": 1,
    "data": {
        "host_ip": "192.168.11.235"
    },
    "msg": "Invalid db_id value detected."
}

Upgrade Instance Image

API Description: Upgrades specified instances to new image version. Upgrade process: stop container → delete container → rebuild with new image → start container. Data will be preserved.

Request URL: http://{ip}:{port}/container_api/v1/upgrade_image

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
db_ids	Yes	array<string>	db_id array (supports single or multiple)
repository	Yes	string	Image repository name (without tag, defaults to latest)
adiName	No	string	Optional, ADI template file name (must be uploaded to /etc/adi/ via /v1/import_adi first)
adiPass	No	string	Optional, ADI extraction password

Request Example:

POST http://192.168.30.2:18182/container_api/v1/upgrade_image

Request Body:

json


{
    "db_ids": [
        "EDGE0A1...",
        "EDGE6F7..."
    ],
    "repository": "vcloud_android13_edge_20250925011125",
    "adiName": "template.zip",
    "adiPass": "password"
}

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "host_ip": "192.168.11.235",
        "list": [
            {
                "db_id": "EDGEF58PN1AB43UA",
                "name": "EDGEF58PN1AB43UA",
                "repository": "vcloud_android15_edge_20251130184807",
                "short_id": "1094f35df4f3",
                "status": "success",
                "user_name": "test-rename"
            }
        ]
    },
    "msg": "success"
}

Failure:

json


{
    "code": 0,
    "data": {
        "host_ip": "192.168.11.235"
    },
    "msg": "The following instances are using the target image: EDGEF58PN1AB43UA"
}

json


{
    "code": 0,
    "data": {
        "host_ip": "192.168.11.235"
    },
    "msg": "Image does not exist: test:latest"
}

Batch Device Refresh (Async)

API Description: Only allows running or stopped. Sets state=renewing then asynchronously executes shutdown→clear data→startup; preserves db_id and user_name.

Request URL: http://{ip}:{port}/container_api/v1/replace_devinfo

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
db_ids	Yes	array<string>	Instance ID array, supports single or multiple instance IDs
adiName	No	string	Optional, ADI template file name (must be uploaded to /etc/adi/ first)
adiPass	No	string	Optional, ADI extraction password
country	No	string	Optional, country code (ISO Alpha-2) used for random Android property generation, such as CN. When not specified, infers from instance locale first, otherwise defaults to CN.
wipeData	No	boolean	Optional, whether to clear data disk and reset debug_ramdisk, default true. When false, only refreshes configuration and preserves data.
lon	No	float	Optional, longitude. For example 121.5
lat	No	float	Optional, latitude. For example 31.2
locale	No	string	Optional, language. For example zh-CN
timezone	No	string	Optional, timezone. For example Asia/Shanghai

Request Example:

POST http://192.168.30.2:18182/container_api/v1/replace_devinfo

Request Body:

json


{
    "db_ids": [
        "EDGE0A1...",
        "EDGE6F7..."
    ],
    "adiName": "template.zip",
    "adiPass": "password",
    "country": "CN",
    "wipeData": true,
    "lon": 121.5,
    "lat": 31.2,
    "locale": "zh-CN",
    "timezone": "Asia/Shanghai"
}

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "host_ip": "192.168.11.235",
        "list": [
            {
                "db_id": "EDGEF58PN1AB43UA",
                "is_macvlan": false,
                "macvlan_ip": "172.17.0.2",
                "macvlan_network": "",
                "name": "EDGEF58PN1AB43UA",
                "state": "renewing",
                "user_name": "test-rename"
            }
        ]
    },
    "msg": "success"
}

Failure:

json


{
    "code": 1,
    "data": {
        "host_ip": "192.168.11.235"
    },
    "msg": "The following instances do not exist: EDGEINVALID12345"
}

Modify Instance IP (macvlan only)

API Description: Only accepts instances in macvlan mode, modifies their LAN IP. Checks if db_id exists and if IP is already occupied before modification.

Request URL: http://{ip}:{port}/container_api/v1/set_ip

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
db_id	Yes	string	Instance unique identifier (EDGE + 12 random characters)
ip	Yes	string	New LAN IP, must be within macvlan network segment

Request Example:

POST http://192.168.30.2:18182/container_api/v1/set_ip

Request Body:

json


{
    "db_id": "EDGE0A1B2C3D4E5",
    "ip": "192.168.10.120"
}

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "db_id": "EDGEF58PN1AB43UA",
        "host_ip": "192.168.11.235"
    },
    "msg": "success"
}

Failure:

json


{
    "code": 1004,
    "data": {
        "db_id": "EDGEF58PN1AB43UA",
        "host_ip": "192.168.11.235"
    },
    "msg": "instance is not in macvlan mode"
}

json


{
    "code": 1001,
    "data": {
        "db_id": "EDGEINVALID12345",
        "host_ip": "192.168.11.235"
    },
    "msg": "instance not found"
}

Get ADB Connection Command

Request URL: http://{ip}:{port}/container_api/v1/adb_start/{db_id}

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
db_id	Yes	string	Container id

Request Example:

GET http://192.168.30.2:18182/container_api/v1/adb_start/EDGE0A1B2C3D4E5

Response Example:

Success:

json


{
    "code": 200,
    "msg": "adb connect 192.168.11.235:21000"
}

Failure:

json


{
    "code": 202,
    "msg": "container not found"
}

json


{
    "code": 0,
    "msg": "fail"
}

Get Instance Details

Request URL: http://{ip}:{port}/container_api/v1/get_android_detail/{db_id}

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
db_id	Yes	string	Container id

Request Example:

GET http://192.168.30.2:18182/container_api/v1/get_android_detail/EDGE0A1B2C3D4E5

Response Example:

Success:

json


{
    "code": 200,
    "msg": "success",
    "data": {
        "adb_port": 21000,
        "aosp_version": "15",
        "cpuset": "1-7",
        "dns": "8.8.8.8",
        "dpi": "480",
        "fps": "60",
        "height": "2414",
        "id": "1094f35df4f314a397bca2a5da44720b558792ffb2d77214d4fbf6a6bb771724",
        "image": "vcloud_android15_edge_20251130184807:latest",
        "ip": "172.17.0.2",
        "mac": "02:42:ac:11:00:02",
        "memory": 4096,
        "name": "EDGEF58PN1AB43UA",
        "network": "bridge",
        "short_id": "1094f35df4f3",
        "status": "running",
        "user_name": "EDGEF58PN1AB43UA",
        "width": "1080"
    }
}

Failure:

json


{
    "code": 0,
    "error": "Error reason"
}

Get Screenshot (jpg)

Request URL: http://{ip}:{port}/container_api/v1/screenshots/{db_id}

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
db_id	Yes	string	Container id

Request Example:

GET http://192.168.30.2:18182/container_api/v1/screenshots/EDGE0A1B2C3D4E5

Response Example:

Success: Returns JPEG image binary data (Content-Type: image/jpeg)

Failure:

json


{
    "code": 200,
    "msg": "not running"
}

json


{
    "code": 202,
    "msg": "container not found"
}

Query Instance Information

API Description: Queries instance information, supports custom parameters.

Request URL: http://{ip}:{port}/container_api/v1/get_db

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
name	No	string	Instance name (optional)
fields	No	string	Field list, comma-separated (optional)

Request Example:

POST http://192.168.30.2:18182/container_api/v1/get_db

Response Example:

Success:

json


{
    "code": 200,
    "msg": "success",
    "data": {
        "host_ip": "192.168.10.20",
        "count": 2,
        "list": [
            {
                "name": "eef543d81720102b_0_test1",
                "user_name": "test1",
                "state": "running",
                "ip": "172.17.0.2",
                "dns": [
                    "8.8.8.8",
                    "114.114.114.114"
                ],
                "adb": 5555,
                "image": "vcloud_android13_edge_20250925011125:latest",
                "created": "2025-10-13 10:30:00",
                "updated_at": "2025-10-13 10:35:00"
            }
        ]
    }
}

Failure:

json


{
    "code": 0,
    "error": "Error reason"
}

Query All Container IDs

API Description: Returns db_id/user_name/adb list of all instances.

Request URL: http://{ip}:{port}/container_api/v1/list_names

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
-	-	-	None

Request Example:

GET http://192.168.30.2:18182/container_api/v1/list_names

Response Example:

Success:

json


{
    "code": 200,
    "msg": "success",
    "data": {
        "host_ip": "192.168.11.235",
        "list": [
            {
                "adb": 21000,
                "db_id": "EDGEF58PN1AB43UA",
                "name": "EDGEF58PN1AB43UA",
                "state": "running",
                "tcp_audio_port": 23000,
                "tcp_control_port": 24000,
                "tcp_port": 22000,
                "user_name": "vmos"
            },
            {
                "adb": 21001,
                "db_id": "EDGERWRZ7FU6YWCZ",
                "name": "EDGERWRZ7FU6YWCZ",
                "state": "stopped",
                "tcp_audio_port": 23001,
                "tcp_control_port": 24001,
                "tcp_port": 22001,
                "user_name": "vmos-001"
            }
        ]
    }
}

Failure:

json


{
    "code": 0,
    "error": "Error reason"
}

Clone Instance Task Status

API Description: Queries clone instance task status

Request URL: http://{ip}:{port}/container_api/v1/clone_status

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
-	-	-	None

Request Example:

GET http://192.168.30.2:18182/container_api/v1/clone_status

Response Example:

Success:

json


{
    "code": -1,
    "data": null,
    "msg": "No cloning tasks"
}

Failure:

json


{
    "code": 0,
    "error": "Error reason"
}

Clone Instance (Async)

API Description: Clones Android instance. count is the clone quantity, maximum is 12; db_id is the db_id of the source machine to clone; user_name is the name of the cloned instance.

Request URL: http://{ip}:{port}/container_api/v1/clone

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
user_name	Yes	string	Required, name of the cloned instance
db_id	Yes	string	Required, db_id of the container to clone
count	Yes	int	Required, clone quantity, maximum is 12
update_prop	No	boolean	Optional, whether to automatically refresh Android properties after cloning completes, default false. When true, generates random androidProp based on source instance country.

Request Example:

POST http://192.168.30.2:18182/container_api/v1/clone

Request Body:

json


{
    "user_name": "test-001",
    "db_id": "EDGE0A1B2C3D4E5",
    "count": 1,
    "update_prop": true
}

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "host_ip": "192.168.11.235"
    },
    "msg": "cloning is in progress..."
}

Failure:

json


{
    "code": 202,
    "data": {
        "db_id": "EDGEF58PN1AB43UA",
        "host_ip": "192.168.11.235"
    },
    "msg": "The cloud machine to be cloned is not shut down, please shut down the cloud machine before cloning."
}

json


{
    "code": 202,
    "data": {
        "db_id": "EDGEINVALID12345",
        "host_ip": "192.168.11.235"
    },
    "msg": "container not found"
}

Proxy Operations

Proxy settings and management

Set Proxy

API Description: Sets proxy configuration for specified container instance.

Request URL: http://{ip}:{port}/android_api/v1/proxy_set/{db_id}

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
db_id	Yes	string	Instance unique identifier (EDGE + 12 random characters, e.g. EDGE0A1B2C3D4E5)
ip	Yes	string	Proxy server IP or domain name
port	Yes	int	Proxy port number
account	No	string	Username / account
password	No	string	Password, used as key for shadowsocks
proxyName	No	string	Protocol type, e.g. vpn / socks5
udpDisabled	No	boolean	Whether to disable UDP
dnsOverProxyDisabled	No	boolean	Whether to disable DNS over proxy

Request Example:

POST http://192.168.30.2:18182/android_api/v1/proxy_set/EDGE0A1B2C3D4E5

Request Body:

json


{
    "ip": "1.2.3.4",
    "port": 2222,
    "account": "demo",
    "password": "demo123",
    "proxyName": "vpn",
    "udpDisabled": false,
    "dnsOverProxyDisabled": false
}

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "container_ip": "172.17.0.2",
        "host_ip": "192.168.11.235",
        "name": "EDGEF58PN1AB43UA",
        "proxy_info": {
            "enable": true,
            "ip": "1.2.3.4",
            "port": 2222,
            "proxyName": "socks5"
        },
        "user_name": "test-rename"
    },
    "msg": "Success"
}

Failure:

json


{
    "code": 0,
    "data": {
        "db_id": "EDGEINVALID12345",
        "host_ip": "192.168.11.235"
    },
    "msg": "Instance does not exist: EDGEINVALID12345"
}

Stop Proxy

API Description: Stops SOCKS5 proxy for specified container instance. CBS will forward the request to the HTTP service inside the container (port 18183), and automatically clean up proxy configuration information in the database.

Request URL: http://{ip}:{port}/android_api/v1/proxy_stop/{db_id}

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
db_id	Yes	string	Instance unique identifier (EDGE + 12 random characters)

Request Example:

GET http://192.168.30.2:18182/android_api/v1/proxy_stop/EDGE0A1B2C3D4E5

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "enable": false,
        "host_ip": "192.168.11.235",
        "name": "EDGEF58PN1AB43UA"
    },
    "msg": "Proxy has been stopped"
}

Failure:

json


{
    "code": 0,
    "data": {
        "db_id": "EDGEINVALID12345",
        "host_ip": "192.168.11.235"
    },
    "msg": "Instance does not exist: EDGEINVALID12345"
}

Query Proxy

API Description: Queries the real IP and geographic location information of the specified container instance after proxy takes effect. CBS will forward the request to the HTTP service inside the container (port 18183).

Request URL: http://{ip}:{port}/android_api/v1/proxy_get/{db_id}

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
db_id	Yes	string	Instance unique identifier (EDGE + 12 random characters)

Request Example:

GET http://192.168.30.2:18182/android_api/v1/proxy_get/EDGE0A1B2C3D4E5

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "container_ip": "172.17.0.2",
        "host_ip": "192.168.11.235",
        "name": "EDGEF58PN1AB43UA",
        "proxy_config": null,
        "user_name": "test-rename"
    },
    "msg": "Proxy not set"
}

Failure:

json


{
    "code": 0,
    "data": {
        "db_id": "EDGEINVALID12345",
        "host_ip": "192.168.11.235"
    },
    "msg": "Instance does not exist: EDGEINVALID12345"
}

Android Control APIs

Android system control related APIs

Stop Current Foreground App

API Description: Automatically gets the package name of the current foreground app in the container, and uses am force-stop command to force close the app.

Request URL: http://{ip}:{port}/android_api/v1/stop_front_app/{db_id}

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
db_id	Yes	string	Instance unique identifier (EDGE + 12 random characters)

Request Example:

GET http://192.168.30.2:18182/android_api/v1/stop_front_app/EDGE0A1B2C3D4E5

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "container_name": "EDGEF58PN1AB43UA",
        "package_name": "com.android.armlauncher3"
    },
    "msg": "Currently on desktop, did not execute close"
}

Failure:

json


{
    "code": 201,
    "msg": "Instance EDGEINVALID12345 does not exist"
}

Execute ADB Command

API Description: Synchronously executes custom ADB Shell command in the container. Command executes in background, interface returns immediately, non-blocking. Execution results are recorded in logs.

Request URL: http://{ip}:{port}/android_api/v1/shell/{db_id}

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
db_id	Yes	string	Instance unique identifier (EDGE + 12 random characters)
cmd	Yes	string	Shell command to execute

Request Example:

POST http://192.168.30.2:18182/android_api/v1/shell/EDGE0A1B2C3D4E5

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "cmd": "echo test",
        "db_id": "EDGEF58PN1AB43UA",
        "host_ip": "192.168.11.235",
        "message": "test"
    },
    "msg": "success"
}

Failure:

json


{
    "code": 201,
    "msg": "Instance EDGEINVALID12345 does not exist"
}

Get Latitude and Longitude by IP

API Description: Queries latitude and longitude based on instance or proxy IP; if query.ip is provided, it takes priority. If instance has proxy enabled, uses ProxyRealIP first, then ProxyIP; otherwise uses instance IP (private IP will return unlocatable).

Request URL: http://{ip}:{port}/android_api/v1/ip_geo/{db_id}?ip={ip}

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
db_id	Yes	string	Container id
ip	No	string	Optional, IP to override query

Request Example:

GET http://192.168.30.2:18182/android_api/v1/ip_geo/EDGE0A1B2C3D4E5?ip=example_value

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "city": "Mountain View",
        "country": "US",
        "db_id": "EDGEF58PN1AB43UA",
        "host_ip": "192.168.11.235",
        "ip": "8.8.8.8",
        "lat": 37.4056,
        "lon": -122.0775,
        "name": "EDGEF58PN1AB43UA",
        "region": "California",
        "source": "ipinfo.io"
    },
    "msg": "success"
}

Failure:

json


{
    "code": 0,
    "data": {
        "db_id": "EDGEF58PN1AB43UA",
        "host_ip": "192.168.11.235",
        "ip": "172.17.0.2",
        "name": "EDGEF58PN1AB43UA"
    },
    "msg": "Private IP cannot be located, please configure proxy or provide public IP"
}

Batch Install APK

API Description: Batch installs to specified Android containers by uploading APK files. Files will first be uploaded to host /tmp directory, then batch copied to containers and executed with pm install -r.

Request URL: http://{ip}:{port}/android_api/v1/upload_file_android_batch

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
db_ids	Yes	string	Instance ID list, multiple separated by commas, e.g. EDGE123,EDGE456
file	Yes	file	APK file

Request Example:

POST http://192.168.30.2:18182/android_api/v1/upload_file_android_batch

Request Body: multipart/form-data

db_ids: Instance ID list, multiple separated by commas, e.g. EDGE123,EDGE456
file: (file)

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "host_ip": "192.168.11.235",
        "results": {
            "EDGE0A1B2C3D4E5": "Installation successful",
            "EDGE6F7...": "Installation failed: Failure [INSTALL_FAILED_ALREADY_EXISTS]"
        }
    },
    "msg": "Execution completed"
}

Failure:

json


{
    "code": 201,
    "data": {
        "host_ip": "192.168.11.235"
    },
    "msg": "Missing file parameter file"
}

Batch Upload Files

API Description: Batch copies to specified directory of instances by uploading local files. path parameter is optional, defaults to /storage/emulated/0/Download. If specified directory is provided, it must exist beforehand, otherwise error will be reported.

Request URL: http://{ip}:{port}/android_api/v1/upload_file_android_upload

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
db_ids	Yes	string	Instance ID list, multiple separated by commas, e.g. EDGE123,EDGE456
file	Yes	file	File to upload
path	No	string	Optional, target directory, default /storage/emulated/0/Download
Request Example:

POST http://192.168.30.2:18182/android_api/v1/upload_file_android_upload

Request Body: multipart/form-data

db_ids: Instance ID list, multiple separated by commas, e.g. EDGE123,EDGE456
file: (file)
path: Optional, target directory, default /storage/emulated/0/Download

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "host_ip": "192.168.11.235",
        "results": {
            "EDGE0A1B2C3D4E5": "Upload successful",
            "EDGE6F7...": "Directory does not exist: /data/custom/path"
        }
    },
    "msg": "Execution completed"
}

Failure:

json


{
    "code": 201,
    "data": {
        "host_ip": "192.168.11.235"
    },
    "msg": "Missing file parameter file"
}

Set Instance Latitude and Longitude

API Description: References CloudGameServer's gpsInjectInfo. Latitude and longitude are required. CBS forwards parameters to container http://{container_ip}:18183/api/gpsInjectInfo.

Request URL: http://{ip}:{port}/android_api/v1/gps_inject/{db_id}

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
db_id	Yes	string	Container id (path parameter)
longitude	Yes	float	Longitude
latitude	Yes	float	Latitude
altitude	No	float	Altitude
speed	No	float	Speed
bearing	No	float	Bearing
horizontalAccuracyMeters	No	float	Horizontal accuracy (meters)

Request Example:

POST http://192.168.30.2:18182/android_api/v1/gps_inject/EDGE0A1B2C3D4E5

Request Body:

json


{
    "longitude": 116.397455,
    "latitude": 39.909187,
    "altitude": 8,
    "speed": 8,
    "bearing": 0,
    "horizontalAccuracyMeters": 0.1
}

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "db_id": "EDGEF58PN1AB43UA",
        "host_ip": "192.168.11.235",
        "name": "EDGEF58PN1AB43UA"
    },
    "msg": "Success"
}

Failure:

json


{
    "code": 0,
    "data": {
        "db_id": "EDGEINVALID12345",
        "host_ip": "192.168.11.235"
    },
    "msg": "Instance does not exist: EDGEINVALID12345"
}

Set Video Injection

API Description: Forwards to container /api/injectVideo. Body: { 'url': 'https://xxx.mp4' }, CBS will construct injectSwitch=true, injectLoop=true, injectUrl=url and forward.

Request URL: http://{ip}:{port}/android_api/v1/video_inject/{db_id}

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
db_id	Yes	string	Container id (path parameter)
url	Yes	string	Video URL address, e.g. https://example.com/demo.mp4

Request Example:

POST http://192.168.30.2:18182/android_api/v1/video_inject/EDGE0A1B2C3D4E5

Request Body:

json


{
    "url": "https://example.com/demo.mp4"
}

Response Example:

Success:

json


{
    "code": 200,
    "cost": 1566,
    "data": "Video injection started",
    "message": "Success"
}

Failure:

json


{
    "code": 500,
    "cost": 1566,
    "message": "Video injection failed: Video download failed: response failed: 404 "
}

Stop Video Injection

API Description: Forwards to container /api/injectVideo, payload: { injectSwitch:false, injectLoop:false, injectUrl:'' }.

Request URL: http://{ip}:{port}/android_api/v1/video_inject_off/{db_id}

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
db_id	Yes	string	Container id

Request Example:

GET http://192.168.30.2:18182/android_api/v1/video_inject_off/EDGE0A1B2C3D4E5

Response Example:

Success:

json


{
    "code": 200,
    "cost": 1,
    "data": "Injection stopped successfully",
    "message": "Success"
}

Failure:

json


{
    "code": 0,
    "error": "Error reason"
}

Set Instance Timezone

API Description: Forwards to container /api/updateTimeZone. Body: { 'timeZone': 'Asia/Shanghai' }

Request URL: http://{ip}:{port}/android_api/v1/timezone_set/{db_id}

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
db_id	Yes	string	Container id
timeZone	Yes	string	Timezone, e.g. Asia/Shanghai

Request Example:

POST http://192.168.30.2:18182/android_api/v1/timezone_set/EDGE0A1B2C3D4E5

Request Body:

json


{
    "timeZone": "Asia/Shanghai"
}

Response Example:

Failure:

json


{
    "code": 0,
    "data": {
        "db_id": "EDGEINVALID12345",
        "host_ip": "192.168.11.235"
    },
    "msg": "Instance does not exist: EDGEINVALID12345"
}

Set Instance Language

API Description: Forwards to container /api/updateLanguage. Body: { 'country': 'CN', 'language': 'zh' }

Request URL: http://{ip}:{port}/android_api/v1/language_set/{db_id}

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
db_id	Yes	string	Container id (path parameter)
country	Yes	string	Country code, e.g. CN
language	Yes	string	Language code, e.g. zh

Request Example:

POST http://192.168.30.2:18182/android_api/v1/language_set/EDGE0A1B2C3D4E5

Request Body:

json


{
    "country": "CN",
    "language": "zh"
}

Response Example:

Failure:

json


{
    "code": 0,
    "data": {
        "db_id": "EDGEINVALID12345",
        "host_ip": "192.168.11.235"
    },
    "msg": "Instance does not exist: EDGEINVALID12345"
}

Query Instance Country, Language, Timezone

API Description: Gets persist.sys.timezone/persist.sys.locale/persist.sys.country from container via getprop, only supports instances in running state.

Request URL: http://{ip}:{port}/android_api/v1/get_timezone_locale/{db_id}

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
db_id	Yes	string	Instance unique identifier (EDGE + 12 random characters)

Request Example:

GET http://192.168.30.2:18182/android_api/v1/get_timezone_locale/EDGE0A1B2C3D4E5

Response Example:

Success:

json


{
    "code": 200,
    "data": {
        "country": "HK",
        "db_id": "EDGEF58PN1AB43UA",
        "host_ip": "192.168.11.235",
        "locale": "zh-CN",
        "timezone": "Asia/Shanghai",
        "user_name": "test-rename"
    },
    "msg": "Query successful"
}

Failure:

json


{
    "code": 0,
    "data": {
        "db_id": "EDGEINVALID12345",
        "host_ip": "192.168.11.235"
    },
    "msg": "Instance does not exist: EDGEINVALID12345"
}

Interface Logs

Interface execution records and statistics (latest 20 entries, export, success rate)

Query Recent Interface Logs

API Description: Returns the latest 20 interface execution records (/var/log/interface.log)

Request URL: http://{ip}:{port}/interface_logs/recent

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
-	-	-	None

Request Example:

GET http://192.168.30.2:18182/interface_logs/recent

Response Example:

Success:

json


{
    "code": 200,
    "msg": "success",
    "data": {
        "count": 20,
        "list": [
            {
                "time": "2025-11-30T21:29:46+08:00",
                "method": "Execute adb command",
                "status_code": 200,
                "success": true
            }
        ]
    }
}

Failure:

json


{
    "code": 0,
    "error": "Error reason"
}

Show Log Details

API Description: Shows log details

Request URL: http://{ip}:{port}/interface_logs/detail

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
-	-	-	None

Request Example:

GET http://192.168.30.2:18182/interface_logs/detail

Response Example:

Failure:

json


{
    "code": 0,
    "error": "Error reason"
}

Interface Success Rate Query

API Description: Statistics of interface execution count and success rate

Request URL: http://{ip}:{port}/interface_logs/stats

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
-	-	-	None

Request Example:

GET http://192.168.30.2:18182/interface_logs/stats

Response Example:

Success:

json


{
    "code": 200,
    "msg": "success",
    "data": {
        "count": 4,
        "list": [
            {
                "key": "Execute adb command",
                "total": 20,
                "success": 20,
                "success_rate": "100%"
            }
        ]
    }
}

Failure:

json


{
    "code": 2,
    "msg": "missing or unconfirmed"
}

SSD Management

Local storage (SSD) management

Storage Status

API Description: Returns storage status scanned at startup: trial (trial, no SSD), new_ssd (new SSD detected, action required), ssd (registered and mounted).

Request URL: http://{ip}:{port}/storage/status

Request Method: GET

Request Parameters:

Parameter Name	Required	Type	Description
-	-	-	None

Request Example:

GET http://192.168.30.2:18182/storage/status

Response Example:

Success:

json


{
    "mode": "ssd",
    "mounted": true,
    "root": "/container_nswc_lv",
    "device": {
        "path": "/dev/nvme0n1p1",
        "model": "SAMSUNG MZVL4256HBJD-00BH1",
        "serial": "S6B6NU0W808341",
        "size": "238.5G",
        "fstype": "ext4",
        "uuid": "60a716a0-7fe4-49fb-9637-b28b61879e08",
        "mounted": true
    },
    "action_required": false
}

Failure:

json


{
    "code": 2,
    "msg": "missing or unconfirmed"
}

Format as Data Disk and Mount

API Description: Formats specified device as ext4 and mounts to /container_nswc_lv, writes to fstab(UUID).

Request URL: http://{ip}:{port}/storage/format

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
device	Yes	string	Such as /dev/nvme0n1 or its partition
confirm	Yes	boolean	Confirm operation, must be true

Request Example:

POST http://192.168.30.2:18182/storage/format

Request Body:

json


{
    "device": "/dev/nvme0n1",
    "confirm": true
}

Response Example:

Success:

json


{
    "code": 200,
    "msg": "success"
}

Failure:

json


{
    "code": 2,
    "msg": "missing or unconfirmed"
}

Import Existing Data Disk and Mount

API Description: Without formatting, directly mounts specified device as /container_nswc_lv.

Request URL: http://{ip}:{port}/storage/import

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
device	Yes	string	Device path, e.g. /dev/nvme0n1
confirm	Yes	boolean	Confirm operation, must be true

Request Example:

POST http://192.168.30.2:18182/storage/import

Request Body:

json


{
    "device": "/dev/nvme0n1",
    "confirm": true
}

Response Example:

Success:

json


{
    "code": 200,
    "msg": "success"
}

Failure:

json


{
    "code": 2,
    "msg": "missing or unconfirmed"
}

Version Update

CBS version update

CBS Version Update

API Description: Uploads CBS executable file and updates service, please refresh this page after update.

Request URL: http://{ip}:{port}/v1/update_cbs

Request Method: POST

Request Parameters:

Parameter Name	Required	Type	Description
file	Yes	file	CBS executable file (filename must be in format cbs_go_edge_version; supports no extension or .cbs, does not support .exe)
Request Example:

POST http://192.168.30.2:18182/v1/update_cbs

Request Body: multipart/form-data

file: (file)

Response Example:

Success:

json


{
    "code": 200,
    "msg": "CBS update successful",
    "data": {
        "host_ip": "192.168.10.20",
        "current_version": "1.0.10.13.1"
    }
}

Failure:

json


{
    "code": 0,
    "data": {
        "current_version": "1.0.12.2.1",
        "host_ip": "192.168.11.235"
    },
    "msg": "File upload failed: request Content-Type isn't multipart/form-data"
}

General Notes

Response Code Description

Response Code	Description	Usage Scenario
200	Request successful	Interface call successful, operation completed normally
201	Special parameter error	File upload format error, Content-Type error and other special parameter validation failures
0	Operation failed	Most failure scenarios, such as instance does not exist, image does not exist, operation failed, etc.
1	Parameter error	Parameter format error, required parameter missing, invalid parameter value, etc.
2	Status error	Instance status does not meet operation requirements (e.g., requires running status but instance is stopped)
202	Resource does not exist	Container does not exist, resource not found, etc.
460	Operation conflict	Another task of the same type is in progress
500	Server error	Server internal error, such as video download failure, etc.
1001	Instance does not exist	Specified instance ID does not exist
1004	Mode mismatch	Instance is not in macvlan mode, cannot perform related operations

Notes

Basic Notes

Data Format: All interfaces return JSON format data
Address Replacement: {ip} and {port} in request parameters need to be replaced with actual CBS service address and port
Instance ID Format: {db_id} in path parameters is the instance unique identifier, format is EDGE + 12 random characters (e.g.: EDGEF58PN1AB43UA)
Batch Operations: Batch operation interfaces support operating multiple instances simultaneously, passed via db_ids array

Async Operation Notes

Some interfaces are async operations, the interface returns immediately after being called, actual operations execute in background. Async operation interfaces include:

Create Instance (/container_api/v1/create)
Batch Start Instances (/container_api/v1/run)
Batch Stop Instances (/container_api/v1/stop)
Batch Reboot Instances (/container_api/v1/reboot)
Batch Reset Instances (/container_api/v1/reset)
Batch Delete Instances (/container_api/v1/delete)
Upgrade Instance Image (/container_api/v1/upgrade_image)
Batch Device Refresh (/container_api/v1/replace_devinfo)
Clone Instance (/container_api/v1/clone)

After async operations return, you can check instance status changes through query interfaces (e.g., /container_api/v1/get_db).

Instance Status Description

Instances may be in the following states:

creating - Creating
starting - Starting
running - Running
stopping - Stopping
stopped - Stopped
rebooting - Rebooting
rebuilding - Resetting
renewing - Device refreshing
deleting - Deleting

Important: Some interfaces require instances to be in specific states to execute:

Interfaces requiring running state: GPS injection, video injection, execute ADB commands, query timezone language, etc.
Interfaces requiring stopped state: Clone instance (source instance must be stopped)

File Upload Notes

File upload interfaces need to use multipart/form-data format:

Import Image (/v1/import_image): Supports .tar.gz or .tar format
Batch Install APK (/android_api/v1/upload_file_android_batch): Supports .apk files
Batch Upload Files (/android_api/v1/upload_file_android_upload): Supports any file
CBS Version Update (/v1/update_cbs): Filename must be in format cbs_go_edge_version, supports no extension or .cbs, does not support .exe

Error Handling Recommendations

Check Response Code: First check the returned code field to determine if operation was successful
View Error Information: msg or error field contains specific error reason
Status Check: For async operations, need to poll query interfaces to confirm operation completion
Parameter Validation: Ensure all required parameters are provided and format is correct
Instance Status: Confirm instance is in the state required for the operation

Common Questions

Q: How to get instance list?
A: Use /container_api/v1/list_names to get basic information of all instances, or use /container_api/v1/get_db to get detailed information.

Q: How to determine if async operation is complete?
A: Query the instance's state field through /container_api/v1/get_db interface to confirm if status has changed to target state.

Q: How to connect after instance creation?
A: Use /container_api/v1/adb_start/{db_id} to get ADB connection command, then use adb connect command to connect.

Q: How to batch operate multiple instances?
A: Pass multiple instance IDs in the request's db_ids array, e.g.: {"db_ids": ["EDGE001", "EDGE002", "EDGE003"]}

Q: What to do if file upload fails?
A: Check if request's Content-Type is multipart/form-data, ensure file format is correct and file size is within allowed range.

Q: How to view interface call records?
A: Use /interface_logs/recent to view the latest 20 interface call records, use /interface_logs/stats to view interface success rate statistics.

API Documentation ​

Document Introduction ​

Quick Start ​

Basic Information ​

API Categories ​

Usage Instructions ​

Host APIs ​

Get Host Configuration Information ​

Get Host System Information ​

Get Host Network Configuration ​

Host Heartbeat Check ​

Get Host Image List ​

Prune Unused Images ​

Import Image ​

Set Swap Switch ​

Reboot Host ​

Reset Host ​

Discovery Service Status ​

Instance APIs ​

Rename Instance ​

Create Instance ​

Batch Start Instances (Async) ​

Batch Stop Instances (Async) ​

Batch Reboot Instances (Async) ​

Batch Reset Instances (Async) ​

Batch Delete Instances (Async) ​

Upgrade Instance Image ​

Batch Device Refresh (Async) ​

Modify Instance IP (macvlan only) ​

Get ADB Connection Command ​

Get Instance Details ​

Get Screenshot (jpg) ​

Query Instance Information ​

Query All Container IDs ​

Clone Instance Task Status ​

Clone Instance (Async) ​

Proxy Operations ​

Set Proxy ​

Stop Proxy ​

Query Proxy ​

Android Control APIs ​

Stop Current Foreground App ​

Execute ADB Command ​

Get Latitude and Longitude by IP ​

Batch Install APK ​

Batch Upload Files ​

Set Instance Latitude and Longitude ​

Set Video Injection ​

Stop Video Injection ​

Set Instance Timezone ​

Set Instance Language ​

Query Instance Country, Language, Timezone ​

Interface Logs ​

Query Recent Interface Logs ​

Show Log Details ​

Interface Success Rate Query ​

SSD Management ​

Storage Status ​

Format as Data Disk and Mount ​

Import Existing Data Disk and Mount ​

Version Update ​

CBS Version Update ​

General Notes ​

Response Code Description ​

Notes ​

Basic Notes ​

Async Operation Notes ​

Instance Status Description ​

File Upload Notes ​

Error Handling Recommendations ​

Common Questions ​

API Documentation

Document Introduction

Quick Start

Basic Information

API Categories

Usage Instructions

Host APIs

Get Host Configuration Information

Get Host System Information

Get Host Network Configuration

Host Heartbeat Check

Get Host Image List

Prune Unused Images

Import Image

Set Swap Switch

Reboot Host

Reset Host

Discovery Service Status

Instance APIs

Rename Instance

Create Instance

Batch Start Instances (Async)

Batch Stop Instances (Async)

Batch Reboot Instances (Async)

Batch Reset Instances (Async)

Batch Delete Instances (Async)

Upgrade Instance Image

Batch Device Refresh (Async)

Modify Instance IP (macvlan only)

Get ADB Connection Command

Get Instance Details

Get Screenshot (jpg)

Query Instance Information

Query All Container IDs

Clone Instance Task Status

Clone Instance (Async)

Proxy Operations

Set Proxy

Stop Proxy

Query Proxy

Android Control APIs

Stop Current Foreground App

Execute ADB Command

Get Latitude and Longitude by IP

Batch Install APK

Batch Upload Files

Set Instance Latitude and Longitude

Set Video Injection

Stop Video Injection

Set Instance Timezone

Set Instance Language

Query Instance Country, Language, Timezone

Interface Logs

Query Recent Interface Logs

Show Log Details

Interface Success Rate Query

SSD Management

Storage Status

Format as Data Disk and Mount

Import Existing Data Disk and Mount

Version Update

CBS Version Update

General Notes

Response Code Description

Notes

Basic Notes

Async Operation Notes

Instance Status Description

File Upload Notes

Error Handling Recommendations

Common Questions