Android Control API Documentation

Updated: Jan 9, 2026

Version Support

Android Control API requires specific image version support. Please ensure your cloud machine image version is not lower than:

Android 10: vcloud_android10_edge_20260110 or above
Android 13: vcloud_android13_edge_20260110 or above
Android 15: vcloud_android15_edge_20260110 or above
CBS: 1.1.1.10 or above

Introduction

Android Control API provides a set of control and management capabilities for the Android system, covering application management, input control, system settings, file operations, and more.

Usage

1. HTTP Call from Outside

When calling from the host machine or other devices in the network, you need to forward through the container management API:

URL Format: http://{Host_IP}:18182/android_api/v2/{Machine_ID}/{Interface_Path}
Example: http://192.168.1.100:18182/android_api/v2/EDGE12345678/activity/processes

2. HTTP Call from Inside

Direct call inside the Android instance (e.g., via terminal or internal script):

URL Format: http://127.0.0.1:18185/api/{Interface_Path}
Example: http://127.0.0.1:18185/api/activity/processes

3. Socket Call

Not yet open, coming soon.

4. Command Line (CLI) Call

Not yet open, coming soon.

Common Response Structure

All interfaces return a standard JSON format with the following structure:

json

{
    "code": 200,            // Status code, 200 for success
    "data": { ... },        // Specific business data
    "msg": "OK",            // Status description
    "request_id": "..."     // Unique request identifier
}

Logic Process (Logic)

Sleep

Pause the interface response for a period of time. Commonly used for waiting during script execution. Image version 20260113 or above is required.

URL: /logic/sleep
Method: POST
Parameters:
Parameter Type Required Description
duration long Yes Sleep duration (ms)

Parameter	Type	Required	Description
duration	long	Yes	Sleep duration (ms)

Response Example:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "sl123456"
}

Workflow (Workflow)

Execute Workflow

Execute multiple interface actions sequentially in a single request. Image version 20260113 or above is required.

URL: /workflow
Method: POST
Parameters:
Parameter Type Required Description
actions array Yes List of actions. Each object contains path (interface path) and params (parameter object)

Parameter	Type	Required	Description
actions	array	Yes	List of actions. Each object contains `path` (interface path) and `params` (parameter object)

Request Example:

json

{
  "actions": [
    {
      "path": "activity/start",
      "params": { "package_name": "com.android.settings" }
    },
    {
      "path": "logic/sleep",
      "params": { "duration": 2000 }
    },
    {
      "path": "input/click",
      "params": { "x": 300, "y": 300 }
    }
  ]
}

Response Example:

json

{
  "code": 200,
  "data": [
    {
      "request_id": "8aca36b28c444ca09d07fb2690d03a3d",
      "response_data": {
        "package_name": "com.android.settings",
        "class_name": "com.android.settings.Settings"
      }
    },
    {
      "request_id": "9bca36b28c444ca09d07fb2690d03a3e",
      "response_data": true
    },
    {
      "request_id": "0cca36b28c444ca09d07fb2690d03a3f",
      "response_data": { "x": 300, "y": 300 }
    }
  ],
  "msg": "OK",
  "request_id": "wf123456"
}

Activity Management (Activity)

Start Application

URL: /activity/start
Method: POST
Parameters:
Parameter Type Required Description
package_name string Yes Application package name

Request Example:

json

{
  "package_name": "com.android.settings"
}

Response Example:

json

{
  "code": 200,
  "data": {
    "package_name": "com.android.settings",
    "class_name": "com.android.settings.Settings"
  },
  "msg": "OK",
  "request_id": "8aca36b28c444ca09d07fb2690d03a3d"
}

Start Specific Activity

URL: /activity/start_activity
Method: POST

Parameters:

Parameter	Type	Required	Description
package_name	string	No	Package name (optional if action is specified)
class_name	string	No	Activity class name
action	string	No	Intent action
data	string	No	Intent data
extras	object	No	Intent extras (Key-Value pairs)

Request Example:

json

{
  "package_name": "com.android.settings",
  "class_name": "com.android.settings.Settings",
  "extras": {
    "extra_key": "extra_value",
    "is_test": true
  }
}

Response Example:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "sa123456"
}

Stop Application

URL: /activity/stop
Method: POST
Parameters:
Parameter Type Required Description
package_name string Yes Application package name

Request Example:

json

{
  "package_name": "com.android.settings"
}

Response Example:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "a1b2c3d4e5f6g7h8i9j0"
}

Get Running Processes

URL: /activity/processes
Method: GET

Response Example:

json

{
  "code": 200,
  "data": [
    {
      "process_name": "com.android.settings",
      "pid": 1234,
      "uid": 1000,
      "package_names": ["com.android.settings"],
      "importance": 100
    }
  ],
  "msg": "OK",
  "request_id": "c3d4e5f6g7h8i9j0a1b2"
}

Get Top Activity Information

URL: /activity/top_activity
Method: GET

Response Example:

json

{
  "code": 200,
  "data": {
    "package_name": "com.android.settings",
    "class_name": "com.android.settings.Settings"
  },
  "msg": "OK",
  "request_id": "ta123456"
}

Get Recent Tasks

URL: /activity/recent_tasks
Method: GET
Parameters:
Parameter Type Required Description
max_num int No Maximum number, default is 20

Parameter	Type	Required	Description
max_num	int	No	Maximum number, default is 20

Response Example:

json

{
  "code": 200,
  "data": [
    {
      "task_id": 123,
      "base_package_name": "com.android.settings",
      "base_class_name": "com.android.settings.Settings",
      "top_package_name": "com.android.settings",
      "top_class_name": "com.android.settings.Settings",
      "num_activities": 1,
      "last_active_time": 1736412345000
    }
  ],
  "msg": "OK",
  "request_id": "rt123456"
}

Clear Task Stack

Removes all recent tasks (similar to clearing recent apps in the background).

URL: /activity/clear_tasks
Method: POST

Response Example:

json

{
  "code": 200,
  "data": [
    {
      "task_id": 123,
      "base_package_name": "com.android.settings",
      "base_class_name": "com.android.settings.Settings",
      "top_package_name": "com.android.settings",
      "top_class_name": "com.android.settings.Settings"
    }
  ],
  "msg": "OK",
  "request_id": "ct123456"
}

Move Task to Front

URL: /activity/move_to_front
Method: POST
Parameters:
Parameter Type Required Description
task_id int Yes Task ID
Request Example:
json
```
{
  "task_id": 123
}
```

Parameter	Type	Required	Description
task_id	int	Yes	Task ID

Response Example:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "mtf123456"
}

Package Management (Package)

Install Application

Supports standard APK as well as APKS, APKM, XAPK and other split formats. Async install returns a task ID immediately, sync install blocks until completion.

URL: /package/install (Async) / /package/install_sync (Sync)
Method: POST
Content-Type: multipart/form-data or application/json
Parameters:
Parameter Type Required Description
file file No APK/XAPK file (Multipart method)
file_path string No Path inside the instance (JSON method)
installer_package_name string No Specify the installer package name

Parameter	Type	Required	Description
file	file	No	APK/XAPK file (Multipart method)
file_path	string	No	Path inside the instance (JSON method)
installer_package_name	string	No	Specify the installer package name

Response Example (Async):

json

{
  "code": 200,
  "data": "m3n4o5p6q7r8s9t0u1v2",
  "msg": "OK",
  "request_id": "m3n4o5p6q7r8s9t0u1v2"
}

Response Example (Sync):

json

{
  "code": 200,
  "data": {
    "package_name": "com.example.app",
    "message": "Success"
  },
  "msg": "OK",
  "request_id": "ins_sync_123"
}

Uninstall Application

URL: /package/uninstall
Method: POST
Parameters:
Parameter Type Required Description
package_name string Yes Application package name

Response Example:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "n4o5p6q7r8s9t0u1v2w3"
}

Set Package Enabled State

URL: /package/enabled
Method: POST
Parameters:
Parameter Type Required Description
package_name string Yes Application package name
enabled boolean Yes Whether to enable

Response Example:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "se123456"
}

Get Installed Packages

URL: /package/list
Method: GET
Parameters:
Parameter Type Required Description
type string No all=All, system=System apps, user=User apps (Default is user)

Parameter	Type	Required	Description
type	string	No	`all`=All, `system`=System apps, `user`=User apps (Default is `user`)

Response Example:

json

{
  "code": 200,
  "data": {
    "type": "user",
    "count": 1,
    "packages": [
      {
        "package_name": "com.example.app",
        "app_name": "Example App",
        "version_name": "1.0.0",
        "version_code": 1,
        "is_system": false,
        "enabled": true,
        "uid": 10123,
        "source_dir": "/data/app/...",
        "data_dir": "/data/user/0/..."
      }
    ]
  },
  "msg": "OK",
  "request_id": "l2m3n4o5p6q7r8s9t0u1"
}

Export App APK

If the application is a single APK, returns the raw APK binary stream. If the application is split (Split APKs), automatically packages into a ZIP format and returns the binary stream.

URL: /package/export
Method: GET
Parameters:
Parameter Type Required Description
package_name string Yes Application package name
Returns: APK or ZIP binary stream.

Clear Application Data

URL: /package/clear_data
Method: POST
Parameters:
Parameter Type Required Description
package_name string Yes Application package name

Request Example:

json

{
  "package_name": "com.android.settings"
}

Response Example:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "b2c3d4e5f6g7h8i9j0a1"
}

Input Control (Input)

Click

URL: /input/click
Method: POST
Parameters:
Parameter Type Required Description
x int Yes X coordinate
y int Yes Y coordinate
Request Example:
json
```
{
  "x": 100,
  "y": 200
}
```

Parameter	Type	Required	Description
x	int	Yes	X coordinate
y	int	Yes	Y coordinate

Response Example:

json

{
  "code": 200,
  "data": {
    "x": 100,
    "y": 200
  },
  "msg": "OK",
  "request_id": "d4e5f6g7h8i9j0a1b2c3"
}

Multi-Click

URL: /input/multi_click
Method: POST
Parameters:
Parameter Type Required Description
x int Yes X coordinate
y int Yes Y coordinate
times int No Number of clicks, default 2
interval long No Click interval (ms), default 100

Parameter	Type	Required	Description
x	int	Yes	X coordinate
y	int	Yes	Y coordinate
times	int	No	Number of clicks, default 2
interval	long	No	Click interval (ms), default 100

Request Example:

json

{
  "x": 100,
  "y": 200,
  "times": 3,
  "interval": 200
}

Response Example:

json

{
  "code": 200,
  "data": {
    "x": 100,
    "y": 200,
    "times": 3,
    "interval": 200
  },
  "msg": "OK",
  "request_id": "mc12345678"
}

Input Text

URL: /input/text
Method: POST
Parameters:
Parameter Type Required Description
text string Yes Text content to input
Request Example:
json
```
{
  "text": "Hello World"
}
```

Parameter	Type	Required	Description
text	string	Yes	Text content to input

Response Example:

json

{
  "code": 200,
  "data": {
    "text": "Hello World",
    "length": 11
  },
  "msg": "OK",
  "request_id": "e5f6g7h8i9j0a1b2c3d4"
}

Key Event

URL: /input/keyevent
Method: POST
Parameters:
Parameter Type Required Description
key_code int No Single KeyCode (e.g., 4=Back, 3=Home)
key_codes array No Combination key list (e.g., [113, 29] for CTRL + A)
Request Example (Single Key):
json
```
{
  "key_code": 4
}
```

Parameter	Type	Required	Description
key_code	int	No	Single KeyCode (e.g., 4=Back, 3=Home)
key_codes	array	No	Combination key list (e.g., [113, 29] for CTRL + A)

Response Example:

json

{
  "code": 200,
  "data": [4],
  "msg": "OK",
  "request_id": "f6g7h8i9j0a1b2c3d4e5"
}

Swipe

URL: /input/swipe
Method: POST

Parameters:

Parameter	Type	Required	Description
start_x	int	Yes	Start X
start_y	int	Yes	Start Y
end_x	int	Yes	End X
end_y	int	Yes	End Y
duration	int	No	Duration (ms), default 300
up_delay	long	No	Release delay (ms), null for immediate, -1 for no release

Request Example:

json

{
  "start_x": 100,
  "start_y": 800,
  "end_x": 100,
  "end_y": 200,
  "duration": 500
}

Response Example:

json

{
  "code": 200,
  "data": {
    "start_x": 100,
    "start_y": 800,
    "end_x": 100,
    "end_y": 200,
    "duration": 500,
    "up_delay": null
  },
  "msg": "OK",
  "request_id": "g7h8i9j0a1b2c3d4e5f6"
}

Bezier Scroll

URL: /input/scroll_bezier
Method: POST

Parameters:

Parameter	Type	Required	Description
start_x	int	Yes	Start X
start_y	int	Yes	Start Y
end_x	int	Yes	End X
end_y	int	Yes	End Y
duration	int	No	Duration (ms), default 500
up_delay	long	No	Release delay (ms), null for immediate, -1 for no release
clear_fling	string	No	Fling elimination strategy: "repeat_last"=repeat the last point

Request Example:

json

{
  "start_x": 200,
  "start_y": 1600,
  "end_x": 200,
  "end_y": 200,
  "duration": 500
}

Response Example:

json

{
  "code": 200,
  "data": {
    "start_x": 200,
    "start_y": 1600,
    "end_x": 200,
    "end_y": 200,
    "duration": 500
  },
  "msg": "OK",
  "request_id": "8aca36b28c444ca09d07fb2690d03a3d"
}

Send Raw MotionEvent

URL: /input/motion_event
Method: POST
Parameters:
Parameter Type Required Description
events array Yes MotionEvent list, see description below

Parameter	Type	Required	Description
events	array	Yes	MotionEvent list, see description below

Event Object Description:

Parameter	Type	Required	Description
action	int	Yes	Action type: 0=DOWN, 1=UP, 2=MOVE, 3=CANCEL...
x	float	Yes	X coordinate
y	float	Yes	Y coordinate
delay	long	No	Delay before sending this event (ms)
pressure	float	No	Pressure value (default 1.0)
down_time	long	No	Press time (default uses first event time)

Request Example:

json

{
  "events": [
    { "action": 0, "x": 100, "y": 200, "delay": 0 },
    { "action": 2, "x": 150, "y": 250, "delay": 50 },
    { "action": 1, "x": 200, "y": 300, "delay": 50 }
  ]
}

Response Example:

json

{
  "code": 200,
  "data": {
    "sent_count": 3,
    "events": [ ... ]
  },
  "msg": "OK",
  "request_id": "mot1234567890"
}

Permission Management (Permission)

Get Application Permissions

URL: /permission/get
Method: GET
Parameters:
Parameter Type Required Description
package_name string Yes Application package name

Response Example:

json

{
  "code": 200,
  "data": {
    "package_name": "com.example.app",
    "count": 2,
    "permissions": [
      { "permission": "android.permission.CAMERA", "granted": true },
      { "permission": "android.permission.RECORD_AUDIO", "granted": false }
    ]
  },
  "msg": "OK",
  "request_id": "per1234567890"
}

Set Application Permissions

URL: /permission/set
Method: POST

Parameters:

Parameter	Type	Required	Description
package_name	string	Yes	Application package name
grant	boolean	Yes	true=Grant, false=Revoke
permissions	array	No	Permission list (e.g., ["android.permission.CAMERA"])
grant_all	boolean	No	Whether to grant all requested permissions
special_permission	boolean	No	Whether to grant special system permissions (including float window, file management, screen recording, etc.)

Special Permission Description: When special_permission is true, the following special permissions will be automatically granted:
- Float Window: Allows the application to display on top of other applications.
- File Management: Allows the application to access all external storage files (Android 11+).
- Screen Recording: Automatically allows screen recording requests, skipping system security confirmation.

Response Example:

json

{
  "code": 200,
  "data": {
    "package_name": "com.example.app",
    "grant": true,
    "success_count": 1
  },
  "msg": "OK",
  "request_id": "per0987654321"
}

File Management (File)

Import File

URL: /file/import
Method: POST
Content-Type: multipart/form-data
Parameters:
Parameter Type Required Description
dir_path string Yes Target directory (e.g., /sdcard/Download/)
file file Yes File field, supports multiple files

Parameter	Type	Required	Description
dir_path	string	Yes	Target directory (e.g., `/sdcard/Download/`)
file	file	Yes	File field, supports multiple files

Response Example:

json

{
  "code": 200,
  "data": {
    "files": [
      {
        "file_path": "/sdcard/Download/test.apk",
        "file_size": 123456
      }
    ]
  },
  "msg": "OK",
  "request_id": "t0u1v2w3x4y5z6a7b8c9"
}

Export File

URL: /file/export
Method: GET
Parameters:
Parameter Type Required Description
path string Yes File path
Returns: File binary stream.

Parameter	Type	Required	Description
path	string	Yes	File path

List Directory Content

URL: /file/list
Method: GET
Parameters:
Parameter Type Required Description
path string Yes Directory path
show_hidden boolean No Whether to show hidden files (default false)
Request Example:
json
```
{
  "path": "/sdcard"
}
```

Parameter	Type	Required	Description
path	string	Yes	Directory path
show_hidden	boolean	No	Whether to show hidden files (default false)

Response Example:

json

{
  "code": 200,
  "data": {
    "path": "/sdcard",
    "count": 2,
    "files": [
      {
        "name": "Download",
        "absolute_path": "/sdcard/Download",
        "is_directory": true,
        "is_file": false,
        "size": 4096,
        "last_modified": 1736412345000,
        "can_read": true,
        "can_write": true,
        "can_execute": true
      }
    ]
  },
  "msg": "OK",
  "request_id": "u1v2w3x4y5z6a7b8c9d0"
}

System Settings (System)

Execute Shell Command

URL: /system/shell
Method: POST
Parameters:
Parameter Type Required Description
command string Yes Shell command to execute
is_root boolean No Whether to execute as root (default true)

Parameter	Type	Required	Description
command	string	Yes	Shell command to execute
is_root	boolean	No	Whether to execute as root (default true)

Request Example:

json

{
  "command": "ls -l /sdcard",
  "is_root": true
}

Response Example:

json

{
  "code": 200,
  "data": {
    "command": "ls -l /sdcard",
    "is_root": true,
    "exit_code": 0,
    "output": "total 0\ndrwxrwx--- 2 root ...",
    "error": ""
  },
  "msg": "OK",
  "request_id": "q7r8s9t0u1v2w3x4y5z6"
}

Set Wallpaper

URL: /system/wallpaper
Method: POST
Parameters:
Parameter Type Required Description
path string Yes Image path (internal path or Assets path)
type string No file (Default) or asset

Parameter	Type	Required	Description
path	string	Yes	Image path (internal path or Assets path)
type	string	No	`file` (Default) or `asset`

Response Example:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "wal1234567890"
}

Power Management (Power)

Screen On / Off

URL: /power/set_screen
Method: POST
Parameters:
Parameter Type Required Description
on boolean Yes true to turn on, false to turn off
Request Example:
json
```
{
  "on": true
}
```

Parameter	Type	Required	Description
on	boolean	Yes	`true` to turn on, `false` to turn off

Response Example:

json

{
  "code": 200,
  "data": {
    "on": true
  },
  "msg": "OK",
  "request_id": "ps123456"
}

Lock / Unlock Screen

URL: /power/locked
Method: POST
Parameters:
Parameter Type Required Description
locked boolean Yes true to lock, false to unlock
Request Example:
json
```
{
  "locked": true
}
```

Parameter	Type	Required	Description
locked	boolean	Yes	`true` to lock, `false` to unlock

Response Example:

json

{
  "code": 200,
  "data": {
    "locked": true
  },
  "msg": "OK",
  "request_id": "pl123456"
}

Get Screen and Lock Status

URL: /power/status
Method: GET

Response Example:

json

{
  "code": 200,
  "data": {
    "is_screen_on": true,
    "is_locked": false
  },
  "msg": "OK",
  "request_id": "pst123456"
}

Localization (Locale)

Get Localization Info

Get a list of all supported languages, countries/regions, and time zones.

URL: /locale/list
Method: GET
Parameters:
Parameter Type Required Description
display_languages array No List of language codes for display names, default ["zh", "en"]

Parameter	Type	Required	Description
display_languages	array	No	List of language codes for display names, default `["zh", "en"]`

Response Example:

json

{
  "code": 200,
  "data": {
    "languages": [
      { 
        "code": "zh", 
        "names": { "zh": "中文", "en": "Chinese" } 
      },
      { 
        "code": "en", 
        "names": { "zh": "英语", "en": "English" } 
      }
    ],
    "regions": [
      { 
        "code": "CN", 
        "names": { "zh": "中国", "en": "China" } 
      },
      { 
        "code": "US", 
        "names": { "zh": "美国", "en": "United States" } 
      }
    ],
    "time_zones": [
      {
        "id": "Asia/Shanghai",
        "names": { "zh": "中国标准时间 (上海)", "en": "China Standard Time (Shanghai)" },
        "offset": 28800000,
        "raw_offset": 28800000
      }
    ]
  },
  "msg": "OK",
  "request_id": "li123456"
}

Clipboard (Clipboard)

Set Clipboard

URL: /clipboard/set
Method: POST
Parameters:
Parameter Type Required Description
text string Yes Text content
Request Example:
json
```
{
  "text": "Hello World"
}
```

Parameter	Type	Required	Description
text	string	Yes	Text content

Response Example:

json

{
  "code": 200,
  "data": {
    "text": "Hello World",
    "length": 11
  },
  "msg": "OK",
  "request_id": "h8i9j0a1b2c3d4e5f6g7"
}

Get Current Clipboard

URL: /clipboard/get
Method: GET

Response Example:

json

{
  "code": 200,
  "data": {
    "text": "Hello World",
    "length": 11
  },
  "msg": "OK",
  "request_id": "i9j0a1b2c3d4e5f6g7h8"
}

Get Clipboard History

URL: /clipboard/list
Method: GET

Response Example:

json

{
  "code": 200,
  "data": {
    "count": 2,
    "mime_type": "text/plain",
    "items": ["Hello", "World"]
  },
  "msg": "OK",
  "request_id": "j0a1b2c3d4e5f6g7h8i9"
}

Clear Clipboard

URL: /clipboard/clear
Method: POST

Response Example:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "k1l2m3n4o5p6q7r8s9t0"
}

Display (Display)

Get Screen Information

URL: /display/info
Method: GET

Response Example:

json

{
  "code": 200,
  "data": {
    "width": 1080,
    "height": 1920,
    "rotation": 0,
    "orientation": 1
  },
  "msg": "OK",
  "request_id": "o5p6q7r8s9t0u1v2w3x4"
}

Screen Rotation

URL: /display/rotate
Method: POST
Parameters:
Parameter Type Required Description
rotation int Yes Rotation angle: 0=0°, 1=90°, 2=180°, 3=270°
Request Example:
json
```
{
  "rotation": 1
}
```

Parameter	Type	Required	Description
rotation	int	Yes	Rotation angle: 0=0°, 1=90°, 2=180°, 3=270°

Response Example:

json

{
  "code": 200,
  "data": {
    "width": 1920,
    "height": 1080,
    "rotation": 1,
    "orientation": 0
  },
  "msg": "OK",
  "request_id": "p6q7r8s9t0u1v2w3x4y5"
}

Screen Screenshot (Compressed)

URL: /screenshot/format
Method: GET
Parameters:
Parameter Type Required Description
format string No webp, png, jpeg (Default is jpg)
quality int No Quality (1-100), default 100
Returns: Raw image binary stream (Content-Type: image/jpeg, etc.).

Parameter	Type	Required	Description
format	string	No	`webp`, `png`, `jpeg` (Default is `jpg`)
quality	int	No	Quality (1-100), default 100

Get Screenshot (Raw)

URL: /screenshot/raw
Method: GET
Returns: Raw RGBA pixel data stream (ARGB_8888). Each pixel occupies 4 bytes.

Contact Management (Contact)

Add Contact

URL: /contact/add
Method: POST
Parameters:
Parameter Type Required Description
name string Yes Name
phone string Yes Phone number
email string No Email
organization string No Company/Organization
note string No Remark

Parameter	Type	Required	Description
name	string	Yes	Name
phone	string	Yes	Phone number
email	string	No	Email
organization	string	No	Company/Organization
note	string	No	Remark

Request Example:

json

{
  "name": "Zhang San",
  "phone": "13800138000"
}

Response Example:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "con1234567890"
}

Delete Contact

URL: /contact/delete
Method: POST
Parameters:
Parameter Type Required Description
id long Yes Contact ID
Request Example:
json
```
{
  "id": 1
}
```

Parameter	Type	Required	Description
id	long	Yes	Contact ID

Response Example:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "cd123456"
}

Get Contact List

URL: /contact/list
Method: GET
Parameters:
Parameter Type Required Description
offset int No Offset, default 0
limit int No Limit count, default 100

Parameter	Type	Required	Description
offset	int	No	Offset, default 0
limit	int	No	Limit count, default 100

Response Example:

json

{
  "code": 200,
  "data": {
    "offset": 0,
    "limit": 100,
    "count": 1,
    "contacts": [
      { "id": 1, "name": "Zhang San", "phones": ["13800138000"] }
    ]
  },
  "msg": "OK",
  "request_id": "cl123456"
}

SMS Management (SMS)

Get SMS List

URL: /sms/list
Method: GET
Parameters:
Parameter Type Required Description
offset int No Offset, default 0
limit int No Limit count, default 100

Parameter	Type	Required	Description
offset	int	No	Offset, default 0
limit	int	No	Limit count, default 100

Response Example:

json

{
  "code": 200,
  "data": {
    "offset": 0,
    "limit": 100,
    "count": 1,
    "sms_list": [
      { "id": 1, "address": "10086", "body": "Low balance", "date": 1736412345000, "type": 1, "read": 1 }
    ]
  },
  "msg": "OK",
  "request_id": "sl123456"
}

Add SMS

URL: /sms/add
Method: POST
Parameters:
Parameter Type Required Description
address string Yes Recipient/Sender number
body string Yes SMS content
type int No Type: 1=Received, 2=Sent (Default 1)
date long No Timestamp, default current time

Parameter	Type	Required	Description
address	string	Yes	Recipient/Sender number
body	string	Yes	SMS content
type	int	No	Type: 1=Received, 2=Sent (Default 1)
date	long	No	Timestamp, default current time

Request Example:

json

{
  "address": "10086",
  "body": "Your balance is low, please recharge.",
  "type": 1
}

Response Example:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "sa123456"
}

Delete SMS

URL: /sms/delete
Method: POST
Parameters:
Parameter Type Required Description
id long Yes SMS ID

Parameter	Type	Required	Description
id	long	Yes	SMS ID

Response Example:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "sd123456"
}

Account Management (Account)

Add Account

URL: /account/add
Method: POST
Parameters:
Parameter Type Required Description
name string Yes Account name (e.g., example@gmail.com)
type string Yes Account type (e.g., com.google)
password string No Password
user_data object No Custom user data (Key-Value)

Parameter	Type	Required	Description
name	string	Yes	Account name (e.g., `example@gmail.com`)
type	string	Yes	Account type (e.g., `com.google`)
password	string	No	Password
user_data	object	No	Custom user data (Key-Value)

Request Example:

json

{
  "name": "test_user",
  "type": "com.example.account",
  "password": "password123",
  "user_data": {
    "key1": "value1"
  }
}

Response Example:

json

{
  "code": 200,
  "data": {
    "name": "test_user",
    "type": "com.example.account"
  },
  "msg": "OK",
  "request_id": "aa123456"
}

Get Account List

URL: /account/list
Method: GET
Parameters:
Parameter Type Required Description
type string No Filter by account type

Parameter	Type	Required	Description
type	string	No	Filter by account type

Response Example:

json

{
  "code": 200,
  "data": {
    "count": 1,
    "accounts": [
      { "name": "test_user", "type": "com.example.account" }
    ]
  },
  "msg": "OK",
  "request_id": "al123456"
}

Delete Account

URL: /account/delete
Method: POST
Parameters:
Parameter Type Required Description
name string Yes Account name
type string Yes Account type

Parameter	Type	Required	Description
name	string	Yes	Account name
type	string	Yes	Account type

Response Example:

json

{
  "code": 200,
  "data": {
    "name": "test_user",
    "type": "com.example.account"
  },
  "msg": "OK",
  "request_id": "ad123456"
}

Media & Audio (Media)

Set Volume

URL: /media/set_volume
Method: POST

Parameters:

Parameter	Type	Required	Description
stream_type	string	Yes	Volume type: `music`, `voice_call`, `ring`, `alarm`, `notification`
volume	int	Yes	Volume value (0 to Max)
show_ui	boolean	No	Whether to show system volume UI (Default `true`)

Request Example:

json

{
  "stream_type": "music",
  "volume": 8
}

Response Example:

json

{
  "code": 200,
  "data": {
    "stream_type": "music",
    "volume": 8
  },
  "msg": "OK",
  "request_id": "sv123456"
}

Mute / Unmute

URL: /media/mute
Method: POST
Parameters:
Parameter Type Required Description
mute boolean Yes true to mute, false to unmute

Parameter	Type	Required	Description
mute	boolean	Yes	`true` to mute, `false` to unmute

Response Example:

json

{
  "code": 200,
  "data": {
    "mute": true
  },
  "msg": "OK",
  "request_id": "mu123456"
}

Get Volume Info

URL: /media/get_volume
Method: GET

Response Example:

json

{
  "code": 200,
  "data": {
    "music": { "current": 8, "max": 15 },
    "voice_call": { "current": 5, "max": 10 },
    "ring": { "current": 10, "max": 15 },
    "is_mute": false
  },
  "msg": "OK",
  "request_id": "vi123456"
}

Accessibility (Accessibility)

Export UI Hierarchy

URL: /accessibility/dump
Method: GET

Response Example:

json

{
  "code": 200,
  "data": "<?xml version='1.0' encoding='UTF-8' standalone='yes' ?><hierarchy ...",
  "msg": "OK",
  "request_id": "r8s9t0u1v2w3x4y5z6a7"
}

Find UI Node

Find UI nodes on the current screen based on specified criteria. Image version 20260113 or above is required.

URL: /accessibility/find_node
Method: POST

Parameters:

Parameter	Type	Required	Description
xpath	string	No	XPath expression, highest priority
text	string	No	Node text. Supports regex (e.g., `.Settings.`)
content_desc	string	No	Node content description. Supports regex
name	string	No	Node text or content description. Supports regex
class	string	No	Node class name (class)
resource_id	string	No	Node resource ID (resource-id)
package	string	No	Application package name
index	int	No	Index of the node within its parent
clickable	boolean	No	Whether clickable
enabled	boolean	No	Whether enabled
scrollable	boolean	No	Whether scrollable
focusable	boolean	No	Whether focusable
focused	boolean	No	Whether focused
selected	boolean	No	Whether selected
checkable	boolean	No	Whether checkable
checked	boolean	No	Whether checked
center_x	int	No	Node center X coordinate
center_y	int	No	Node center Y coordinate

Request Example (Combined + Regex):

json

{
  "text": ".*Settings.*",
  "class": "android.widget.TextView",
  "clickable": true
}

Request Example (Exact Match):

json

{
  "text": "Settings",
  "class": "android.widget.TextView",
  "resource_id": "com.android.settings:id/title"
}

Request Example (XPath):

json

{
  "xpath": "//node[@text='Settings' and @clickable='true']"
}

Response Example:

json

{
  "code": 200,
  "data": {
    "count": 1,
    "nodes": [
      {
        "text": "Settings",
        "class": "android.widget.TextView",
        "package": "com.android.settings",
        "content_desc": "Settings button",
        "resource_id": "com.android.settings:id/title",
        "bounds": { "left": 100, "top": 200, "right": 300, "bottom": 400 },
        "center_x": 200,
        "center_y": 300,
        "clickable": true,
        "enabled": true,
        "focusable": true,
        "focused": false,
        "scrollable": false,
        "long_clickable": false,
        "password": false,
        "selected": false
      }
    ]
  },
  "msg": "OK",
  "request_id": "fn123456"
}

Perform Node Action

URL: /accessibility/perform_action
Method: POST
Parameters:
Parameter Type Required Description
text string No Node text
view_id string No Node Resource ID
action int Yes Action code (16=Click, 32=Long Click, etc.)

Parameter	Type	Required	Description
text	string	No	Node text
view_id	string	No	Node Resource ID
action	int	Yes	Action code (16=Click, 32=Long Click, etc.)

Response Example:

json

{
  "code": 200,
  "data": {
    "performed_count": 1
  },
  "msg": "OK",
  "request_id": "pa123456"
}

Set Accessibility Service Hidden State

Set whether a specified application is hidden from the accessibility service list. Image version 20260113 or above is required.

URL: /accessibility/set_hidden
Method: POST
Parameters:
Parameter Type Required Description
package_names array Yes List of accessibility service package names
hidden boolean No Whether to hide, default true

Parameter	Type	Required	Description
package_names	array	Yes	List of accessibility service package names
hidden	boolean	No	Whether to hide, default `true`

Response Example:

json

{
  "code": 200,
  "data": ["com.example.service1", "com.example.service2"],
  "msg": "OK",
  "request_id": "sh123456"
}

Get Accessibility Service Hidden State

Get the list of accessibility service package names that are currently hidden. Image version 20260113 or above is required.

URL: /accessibility/get_hidden
Method: GET

Response Example:

json

{
  "code": 200,
  "data": ["com.example.service1", "com.example.service2"],
  "msg": "OK",
  "request_id": "gh123456"
}

Notification Management (Notification)

Get Active Notifications

URL: /notification/list
Method: GET
Parameters:
Parameter Type Required Description
package_name string No Filter notifications by application package name

Parameter	Type	Required	Description
package_name	string	No	Filter notifications by application package name

Response Example:

json

{
  "code": 200,
  "data": {
    "count": 1,
    "notifications": [
      {
        "package_name": "com.android.settings",
        "id": 1,
        "key": "0|com.android.settings|1|null|1000",
        "title": "Notification Title",
        "text": "Notification Content",
        "post_time": 1736412345000,
        "is_ongoing": false,
        "is_clearable": true,
        "priority": 0
      }
    ]
  },
  "msg": "OK",
  "request_id": "v2w3x4y5z6a7b8c9d0e1"
}

Get Application Notification Channels

URL: /notification/channels
Method: GET
Parameters:
Parameter Type Required Description
package_name string Yes Application package name

Response Example:

json

{
  "code": 200,
  "data": {
    "package_name": "com.example.app",
    "count": 1,
    "channels": [
      {
        "id": "channel_id",
        "name": "Channel Name",
        "importance": 3,
        "description": "Channel description"
      }
    ]
  },
  "msg": "OK",
  "request_id": "nc123456"
}

Device Information (Device)

Random Model Info

Randomly generate and set the model info of the cloud machine. Note: This interface is only supported for virtual machine type cloud machines.

URL: /device/random_model
Method: POST
Parameters:
Parameter Type Required Description
is_china boolean No Whether to only randomize Chinese models, default false

Response Example:

json

{
  "code": 200,
  "data": {
    "manufacturer": "Xiaomi",
    "model": "MI 11",
    "brand": "Xiaomi",
    "device": "cetus",
    "product": "cetus",
    "hardware": "qcom"
  },
  "msg": "OK",
  "request_id": "s9t0u1v2w3x4y5z6a7b8"
}

Google Services (Google)

Enable/Disable Google Suite

Enable or disable the complete Google service suite (including GMS Core, Play Store, Service Framework, etc.).

URL: /google/set_enabled
Method: POST
Parameters:
Parameter Type Required Description
enabled boolean Yes true to enable, false to disable

Response Example:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "gs123456"
}

Reset GAID

Reset Google Advertising ID (GAID).

URL: /google/reset_gaid
Method: POST
Parameters:
Parameter Type Required Description
gaid string No Specify GAID, if not passed, a random one will be generated

Response Example:

json

{
  "code": 200,
  "data": "550e8400-e29b-41d4-a716-446655440000",
  "msg": "OK",
  "request_id": "gr123456"
}

Get Google Suite Enablement State

Get the current enablement state of the Google service suite. Returns true only if all components in the suite are enabled.

URL: /google/get_enabled
Method: GET

Response Example:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "gst123456"
}

Android Control API Documentation ​

Introduction ​

Usage ​

1. HTTP Call from Outside ​

2. HTTP Call from Inside ​

3. Socket Call ​

4. Command Line (CLI) Call ​

Common Response Structure ​

Logic Process (Logic) ​

Sleep ​

Workflow (Workflow) ​

Execute Workflow ​

Activity Management (Activity) ​

Start Application ​

Start Specific Activity ​

Stop Application ​

Get Running Processes ​

Get Top Activity Information ​

Get Recent Tasks ​

Clear Task Stack ​

Move Task to Front ​

Package Management (Package) ​

Install Application ​

Uninstall Application ​

Set Package Enabled State ​

Get Installed Packages ​

Export App APK ​

Clear Application Data ​

Input Control (Input) ​

Click ​

Multi-Click ​

Input Text ​

Key Event ​

Swipe ​

Bezier Scroll ​

Send Raw MotionEvent ​

Permission Management (Permission) ​

Get Application Permissions ​

Set Application Permissions ​

File Management (File) ​

Import File ​

Export File ​

List Directory Content ​

System Settings (System) ​

Execute Shell Command ​

Set Wallpaper ​

Power Management (Power) ​

Screen On / Off ​

Lock / Unlock Screen ​

Get Screen and Lock Status ​

Localization (Locale) ​

Get Localization Info ​

Clipboard (Clipboard) ​

Set Clipboard ​

Get Current Clipboard ​

Get Clipboard History ​

Clear Clipboard ​

Display (Display) ​

Get Screen Information ​

Screen Rotation ​

Screen Screenshot (Compressed) ​

Get Screenshot (Raw) ​

Contact Management (Contact) ​

Add Contact ​

Delete Contact ​

Get Contact List ​

SMS Management (SMS) ​

Get SMS List ​

Add SMS ​

Delete SMS ​

Account Management (Account) ​

Add Account ​

Get Account List ​

Delete Account ​

Media & Audio (Media) ​

Set Volume ​

Mute / Unmute ​

Get Volume Info ​

Accessibility (Accessibility) ​

Export UI Hierarchy ​

Android Control API Documentation

Introduction

Usage

1. HTTP Call from Outside

2. HTTP Call from Inside

3. Socket Call

4. Command Line (CLI) Call

Common Response Structure

Logic Process (Logic)

Sleep

Workflow (Workflow)

Execute Workflow

Activity Management (Activity)

Start Application

Start Specific Activity

Stop Application

Get Running Processes

Get Top Activity Information

Get Recent Tasks

Clear Task Stack

Move Task to Front

Package Management (Package)

Install Application

Uninstall Application

Set Package Enabled State

Get Installed Packages

Export App APK

Clear Application Data

Input Control (Input)

Click

Multi-Click

Input Text

Key Event

Swipe

Bezier Scroll

Send Raw MotionEvent

Permission Management (Permission)

Get Application Permissions

Set Application Permissions

File Management (File)

Import File

Export File

List Directory Content

System Settings (System)

Execute Shell Command

Set Wallpaper

Power Management (Power)

Screen On / Off

Lock / Unlock Screen

Get Screen and Lock Status

Localization (Locale)

Get Localization Info

Clipboard (Clipboard)

Set Clipboard

Get Current Clipboard

Get Clipboard History

Clear Clipboard

Display (Display)

Get Screen Information

Screen Rotation

Screen Screenshot (Compressed)

Get Screenshot (Raw)

Contact Management (Contact)

Add Contact

Delete Contact

Get Contact List

SMS Management (SMS)

Get SMS List

Add SMS

Delete SMS

Account Management (Account)

Add Account

Get Account List

Delete Account

Media & Audio (Media)

Set Volume

Mute / Unmute

Get Volume Info

Accessibility (Accessibility)

Export UI Hierarchy