VMOS Edge Documentation

English

简体中文

English

简体中文

Appearance

Android Control API Documentation ​

Updated: Jan 22, 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.

5. MCP Call (AI Agent Integration) ​

Requires API version 1.0.7 or above

Expose Android control capabilities directly to AI agents via MCP (Model Context Protocol).

Compatible clients: Claude Code, Cursor, Codex, Gemini, Tongyi Qianwen, Kimi, and any client that supports the MCP SSE protocol.

SSE Endpoints (choose one):

ModeEndpoint
LAN Mode (LAN IP enabled)http://{Device_IP}:18185/mcp/sse
Non-LAN Mode (LAN IP disabled)http://{Host_IP}:18182/android_api/v2/{Machine_ID}/mcp/sse

The examples below use LAN Mode. For Non-LAN Mode, replace the URL with the external HTTP call address.

bash
# Project-level (current project only, default)
claude mcp add --transport sse vmos-edge-control-api http://{Device_IP}:18185/mcp/sse
# Global (all projects)
claude mcp add -s user --transport sse vmos-edge-control-api http://{Device_IP}:18185/mcp/sse

# Remove
claude mcp remove vmos-edge-control-api
# Disable (keep config but don't load)
claude mcp disable vmos-edge-control-api
# Enable
claude mcp enable vmos-edge-control-api
# List
claude mcp list
yaml
# ~/.codex/config.yaml
mcp_servers:
  vmos-edge-control-api:
    type: sse
    url: "http://{Device_IP}:18185/mcp/sse"
json
// ~/.gemini/settings.json
{
  "mcpServers": {
    "vmos-edge-control-api": {
      "httpUrl": "http://{Device_IP}:18185/mcp/sse"
    }
  }
}
json
// .cursor/mcp.json in project root or ~/.cursor/mcp.json
{
  "mcpServers": {
    "vmos-edge-control-api": {
      "url": "http://{Device_IP}:18185/mcp/sse"
    }
  }
}
json
// Add in "MCP Services" settings
{
  "mcpServers": {
    "vmos-edge-control-api": {
      "type": "sse",
      "url": "http://{Device_IP}:18185/mcp/sse"
    }
  }
}

Once connected, AI can directly call tools like screenshot, click, text input, and UI hierarchy inspection without manually constructing HTTP requests.

Parameter Formats ​

All POST interfaces support application/json by default, and also accept application/yaml.

JSON (Default) ​

  • Content-Type: application/json

YAML ​

  • Content-Type: application/yaml or text/yaml
  • Example:
    yaml
    package_name: com.android.settings

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
}

Base Capabilities (Base) ​

Get API Version ​

Get current control service version information and all supported interface paths. Image version 20260113 or above is required.

  • URL: /base/version_info
  • Method: GET
  • Response Example:
    json
    {
  "code": 200,
  "data": {
    "version_name": "1.0.0",
    "version_code": 100,
    "supported_list": [
      "base/sleep",
      "workflow",
      "base/version_info",
      "..."
    ]
  },
  "msg": "OK",
  "request_id": "si123456"
}

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: /base/sleep
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    durationlongYesSleep 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:
    ParameterTypeRequiredDescription
    actionsarrayYesList 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": "base/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:
    ParameterTypeRequiredDescription
    package_namestringYesApplication 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:
    ParameterTypeRequiredDescription
    package_namestringNoPackage name (optional if action is specified)
    class_namestringNoActivity class name
    actionstringNoIntent action
    datastringNoIntent data
    extrasobjectNoIntent 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:
    ParameterTypeRequiredDescription
    package_namestringYesApplication 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:
    ParameterTypeRequiredDescription
    max_numintNoMaximum 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:
    ParameterTypeRequiredDescription
    task_idintYesTask ID
  • Request Example:
    json
    {
  "task_id": 123
}
  • 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, OBB and other split formats. Install via file upload (multipart).

  • URL: /package/install_sync
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    filefileYesAPK/XAPK file (multipart/form-data)
    installer_package_namestringNoSpecify the installer package name

File upload note: When uploading via file (multipart), text parameters such as installer_package_name must appear before the file field in the multipart body, or be passed as Query parameters (recommended). Example:

POST /package/install_sync?installer_package_name=com.android.vending
Content-Type: multipart/form-data

file=@app.xapk
  • Response Example:
    json
    {
  "code": 200,
  "cost": 2723,
  "data": {
    "android.content.pm.extra.STATUS": 0,
    "android.content.pm.extra.PACKAGE_NAME": "com.apkmirror.helper.prod",
    "android.content.pm.extra.PRE_APPROVAL": false,
    "android.content.pm.extra.SESSION_ID": 1513445030,
    "android.content.pm.extra.LEGACY_STATUS": 1,
    "android.content.pm.extra.STATUS_MESSAGE": "INSTALL_SUCCEEDED: Session installed"
  },
  "msg": "OK",
  "request_id": "84d5716b8d374006b4cba9caaef794b6"
}

Install Application via URI ​

Requires API version 1.0.7 or above

URI-only installation — does not support file upload. Ideal when you already have a download URL or local path for the APK. Waits synchronously for the installation to complete before returning. Supports standard APK as well as APKS, APKM, XAPK, OBB and other split formats.

  • URL: /package/install_uri_sync

  • Method: POST

  • Parameters:

    ParameterTypeRequiredDescription
    uristringYesAPK URI — supports http://, https:// (auto-download), file://, content://, or local path
    installer_package_namestringNoSpecify the installer package name

  • Request Example:

    json
    {
  "uri": "https://example.com/app.apk"
}

  • Response Example:

    json
    {
  "code": 200,
  "cost": 2723,
  "data": {
    "android.content.pm.extra.STATUS": 0,
    "android.content.pm.extra.PACKAGE_NAME": "com.example.app",
    "android.content.pm.extra.PRE_APPROVAL": false,
    "android.content.pm.extra.SESSION_ID": 1513445030,
    "android.content.pm.extra.LEGACY_STATUS": 1,
    "android.content.pm.extra.STATUS_MESSAGE": "INSTALL_SUCCEEDED: Session installed"
  },
  "msg": "OK",
  "request_id": "84d5716b8d374006b4cba9caaef794b6"
}

Uninstall Application ​

  • URL: /package/uninstall
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    package_namestringYesApplication package name
  • Response Example:
    json
    {
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "n4o5p6q7r8s9t0u1v2w3"
}

Set Package Enabled State ​

  • URL: /package/enabled
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    package_namestringYesApplication package name
    enabledbooleanYesWhether to enable
  • Response Example:
    json
    {
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "se123456"
}

Get Installed Packages ​

  • URL: /package/list
  • Method: GET
  • Parameters:
    ParameterTypeRequiredDescription
    typestringNoall=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:
    ParameterTypeRequiredDescription
    package_namestringYesApplication package name
  • Returns: APK or ZIP binary stream.

Clear Application Data ​

  • URL: /package/clear_data
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    package_namestringYesApplication 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:
    ParameterTypeRequiredDescription
    xintYesX coordinate
    yintYesY coordinate
  • Request Example:
    json
    {
  "x": 100,
  "y": 200
}
  • Response Example:
    json
    {
  "code": 200,
  "data": {
    "x": 100,
    "y": 200
  },
  "msg": "OK",
  "request_id": "d4e5f6g7h8i9j0a1b2c3"
}

Multi-Click ​

  • URL: /input/multi_click
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    xintYesX coordinate
    yintYesY coordinate
    timesintNoNumber of clicks, default 2
    intervallongNoClick 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:
    ParameterTypeRequiredDescription
    textstringYesText content to input
  • Request Example:
    json
    {
  "text": "Hello World"
}
  • Response Example:
    json
    {
  "code": 200,
  "data": {
    "text": "Hello World",
    "length": 11
  },
  "msg": "OK",
  "request_id": "e5f6g7h8i9j0a1b2c3d4"
}

Key Event ​

  • URL: /input/keyevent
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    key_codeintNoSingle KeyCode (e.g., 4=Back, 3=Home)
    key_codesarrayNoCombination key list (e.g., [113, 29] for CTRL + A)
  • Request Example (Single Key):
    json
    {
  "key_code": 4
}
  • Response Example:
    json
    {
  "code": 200,
  "data": [4],
  "msg": "OK",
  "request_id": "f6g7h8i9j0a1b2c3d4e5"
}

Swipe ​

  • URL: /input/swipe
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    start_xintYesStart X
    start_yintYesStart Y
    end_xintYesEnd X
    end_yintYesEnd Y
    durationintNoDuration (ms), default 300
    up_delaylongNoRelease 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:
    ParameterTypeRequiredDescription
    start_xintYesStart X
    start_yintYesStart Y
    end_xintYesEnd X
    end_yintYesEnd Y
    durationintNoDuration (ms), default 500
    up_delaylongNoRelease delay (ms), null for immediate, -1 for no release
    clear_flingstringNoFling 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:
    ParameterTypeRequiredDescription
    eventsarrayYesMotionEvent list, see description below
  • Event Object Description:
    ParameterTypeRequiredDescription
    actionintYesAction type: 0=DOWN, 1=UP, 2=MOVE, 3=CANCEL...
    xfloatYesX coordinate
    yfloatYesY coordinate
    delaylongNoDelay before sending this event (ms)
    pressurefloatNoPressure value (default 1.0)
    down_timelongNoPress 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:
    ParameterTypeRequiredDescription
    package_namestringYesApplication 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:
    ParameterTypeRequiredDescription
    package_namestringYesApplication package name
    grantbooleanYestrue=Grant, false=Revoke
    permissionsarrayNoPermission list (e.g., ["android.permission.CAMERA"])
    grant_allbooleanNoWhether to grant all requested permissions
    special_permissionbooleanNoWhether 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:
    ParameterTypeRequiredDescription
    dir_pathstringYesTarget directory (e.g., /sdcard/Download/)
    filefileYesFile field, supports multiple files
    scanbooleanNoWhether to scan media library, default true, only scans media files
  • Response Example:
    json
    {
  "code": 200,
  "data": {
    "files": [
      {
        "file_path": "/sdcard/Download/image.jpg",
        "file_size": 123456,
        "scanned": true,
        "mime_type": "image/jpeg"
      }
    ]
  },
  "msg": "OK",
  "request_id": "t0u1v2w3x4y5z6a7b8c9"
}

Export File ​

  • URL: /file/export
  • Method: GET
  • Parameters:
    ParameterTypeRequiredDescription
    pathstringYesFile path
  • Returns: File binary stream.

Scan Media Files ​

Scan specified media files into the system media library. Only images, videos, and audio files are scanned. Requires API version 1.0.4 or higher.

  • URL: /file/media_scan
  • Method: POST
  • Content-Type: application/json
  • Parameters:
    ParameterTypeRequiredDescription
    pathsarrayYesList of file paths
    mime_typesarrayYesList of MIME types, corresponding to paths one-to-one
  • Request Example:
    json
    {
  "paths": [
    "/sdcard/Download/image.jpg",
    "/sdcard/Download/video.mp4"
  ],
  "mime_types": [
    "image/jpeg",
    "video/mp4"
  ]
}
  • Response Example:
    json
    {
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "sm123456"
}
  • Notes:
    • paths and mime_types must correspond one-to-one and have the same length
    • Only media files (images, videos, audio) are scanned; other file types are automatically filtered
    • If a path does not exist or is not a file, it will be skipped
    • Returns true on success, false on failure

HTTP Download File ​

Requires API version 1.0.7 or above

  • URL: /file/download
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    urlstringYesDownload URL (http/https)
    pathstringYesSave path (e.g., /sdcard/Download/file.zip)
    overwritebooleanNoWhether to overwrite existing file, default true
  • Response Example:
    json
    {
  "code": 200,
  "data": {
    "path": "/sdcard/Download/file.zip",
    "size": 1048576
  },
  "msg": "OK",
  "request_id": "a1b2c3d4e5f6g7h8i9j0"
}

List Directory Content ​

  • URL: /file/list
  • Method: GET
  • Parameters:
    ParameterTypeRequiredDescription
    pathstringYesDirectory path
    show_hiddenbooleanNoWhether to show hidden files (default false)
  • Request Example:
    json
    {
  "path": "/sdcard"
}
  • 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:
    ParameterTypeRequiredDescription
    commandstringYesShell command to execute
    is_rootbooleanNoWhether 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:
    ParameterTypeRequiredDescription
    pathstringYesImage path (internal path or Assets path)
    typestringNofile (Default) or asset
  • Response Example:
    json
    {
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "wal1234567890"
}

Update System Settings ​

Update system timezone, language, and region. Requires image version 20260113 or higher.

  • URL: /system/update_settings
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    timezonestringNoTimezone ID (e.g., Asia/Shanghai)
    languagestringNoLanguage code (e.g., zh)
    regionstringNoCountry/Region code (e.g., CN)
  • Request Example:
    json
    {
  "timezone": "Asia/Shanghai",
  "language": "zh",
  "region": "CN"
}
  • Response Example:
    json
    {
  "code": 200,
  "data": {
    "timezone": "Asia/Shanghai",
    "language": "zh",
    "region": "CN"
  },
  "msg": "OK",
  "request_id": "us123456"
}

Set System Properties ​

Set Android system properties. Requires image version 20260113 or higher.

  • URL: /system/set_prop
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    propertiesobjectNoProperty Key-Value pairs, keys are used as-is
    persist_propertiesobjectNoProperty Key-Value pairs, keys are automatically prefixed with system prefix
  • Request Example:
    json
    {
  "properties": {
    "persist.sys.test": "value1",
    "debug.test": "value2"
  },
  "persist_properties": {
    "test": "value1",
    "key2": "value2"
  }
}
  • Description:
    • Keys in properties are used directly, e.g., persist.sys.test will be set as persist.sys.test
    • Keys in persist_properties are automatically prefixed with system prefix
    • At least one of properties or persist_properties must be provided
  • Response Example:
    json
    {
  "code": 200,
  "data": {
    "persist.sys.test": true,
    "debug.test": true,
    "test": true,
    "key2": true
  },
  "msg": "OK",
  "request_id": "sp123456"
}

Set System Setting ​

Requires API version 1.0.7 or above

  • URL: /system/settings_put
  • Method: POST
  • Description: Equivalent to settings put <namespace> <key> <value>. Supports three namespaces: secure, global, system.
  • Parameters:
    ParameterTypeRequiredDescription
    namespacestringYesNamespace, options: secure, global, system
    keystringYesSettings key, e.g. default_input_method
    valuestringYesValue to set
  • Request Example:
    json
    {
  "namespace": "secure",
  "key": "default_input_method",
  "value": "com.example.ime/.InputMethodService"
}
  • Response Example:
    json
    {
  "code": 200,
  "data": {
    "namespace": "secure",
    "key": "default_input_method",
    "value": "com.example.ime/.InputMethodService"
  },
  "msg": "OK",
  "request_id": "sp123456"
}

Get System Setting ​

Requires API version 1.0.7 or above

  • URL: /system/settings_get
  • Method: POST
  • Description: Equivalent to settings get <namespace> <key>. Supports three namespaces: secure, global, system.
  • Parameters:
    ParameterTypeRequiredDescription
    namespacestringYesNamespace, options: secure, global, system
    keystringYesSettings key, e.g. default_input_method
  • Request Example:
    json
    {
  "namespace": "secure",
  "key": "default_input_method"
}
  • Response Example:
    json
    {
  "code": 200,
  "data": {
    "namespace": "secure",
    "key": "default_input_method",
    "value": "com.example.ime/.InputMethodService"
  },
  "msg": "OK",
  "request_id": "sg123456"
}

Power Management (Power) ​

Screen On / Off ​

  • URL: /power/set_screen
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    onbooleanYestrue to turn on, false to turn off
  • Request Example:
    json
    {
  "on": true
}
  • Response Example:
    json
    {
  "code": 200,
  "data": {
    "on": true
  },
  "msg": "OK",
  "request_id": "ps123456"
}

Lock / Unlock Screen ​

  • URL: /power/locked
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    lockedbooleanYestrue to lock, false to unlock
  • Request Example:
    json
    {
  "locked": true
}
  • 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"
}

Battery Management (Battery) ​

Get Battery Info ​

Get current device battery status information. Returns raw extras data from Android BatteryManager Intent.

  • URL: /battery/get
  • Method: GET
  • Response Example:
    json
    {
  "code": 200,
  "data": {
    "technology": "Li-ion",
    "icon-small": 17303583,
    "max_charging_voltage": 4400000,
    "health": 2,
    "max_charging_current": 3250000,
    "status": 3,
    "plugged": 0,
    "present": true,
    "seq": 1941,
    "charge_counter": 5000,
    "level": 47,
    "scale": 100,
    "temperature": 338,
    "voltage": 3036,
    "invalid_charger": 0,
    "battery_low": false
  },
  "msg": "OK",
  "request_id": "bg123456"
}
  • Response Fields:
    FieldTypeDescription
    levelintCurrent battery level (0-scale), -1 means unknown
    scaleintMaximum battery level, usually 100
    statusintBattery status, see table below
    pluggedintCharger connection type, see table below
    healthintBattery health, see table below
    voltageintBattery voltage (mV), -1 means unknown
    temperatureintBattery temperature (0.1°C, divide by 10 to get Celsius), -1 means unknown
    technologystringBattery technology type (e.g., Li-ion), may be null
    presentbooleanWhether battery is present
    icon-smallintBattery icon resource ID
    max_charging_voltageintMaximum charging voltage (microvolts, divide by 1000000 to get volts)
    max_charging_currentintMaximum charging current (microamps, divide by 1000000 to get amps)
    seqintBattery status sequence number
    charge_counterintBattery charge counter
    invalid_chargerintInvalid charger flag: 0=Valid, 1=Invalid
    battery_lowbooleanWhether battery is low
  • status (Battery Status):
    ValueConstantDescription
    1BATTERY_STATUS_UNKNOWNUnknown
    2BATTERY_STATUS_CHARGINGCharging
    3BATTERY_STATUS_DISCHARGINGDischarging
    4BATTERY_STATUS_NOT_CHARGINGNot Charging
    5BATTERY_STATUS_FULLFull
  • health (Battery Health):
    ValueConstantDescription
    1BATTERY_HEALTH_UNKNOWNUnknown
    2BATTERY_HEALTH_GOODGood
    3BATTERY_HEALTH_OVERHEATOverheat
    4BATTERY_HEALTH_DEADDead
    5BATTERY_HEALTH_OVER_VOLTAGEOver Voltage
    6BATTERY_HEALTH_UNSPECIFIED_FAILUREUnspecified Failure
    7BATTERY_HEALTH_COLDCold
  • plugged (Charging Type):
    ValueConstantDescription
    0-Not Connected
    1BATTERY_PLUGGED_ACAC Charging
    2BATTERY_PLUGGED_USBUSB Charging
    4BATTERY_PLUGGED_WIRELESSWireless Charging

Set Battery Information ​

Set device battery information, supporting parameters such as level, status, health, etc. Requires API version 1.0.4 or higher.

  • URL: /battery/set
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    levelintNoBattery level (0-100)
    statusintNoBattery status, see /battery/get
    healthintNoBattery health, see /battery/get
    pluggedintNoCharging type, see /battery/get
  • Request Example:
    json
    {
  "level": 85,
  "status": 2,
  "health": 2,
  "plugged": 2
}
  • Response Example:
    json
    {
  "code": 200,
  "data": {
    "technology": "Li-ion",
    "icon-small": 17303583,
    "max_charging_voltage": 4400000,
    "health": 2,
    "max_charging_current": 3250000,
    "status": 2,
    "plugged": 2,
    "present": true,
    "seq": 1941,
    "charge_counter": 5000,
    "level": 85,
    "scale": 100,
    "temperature": 300,
    "voltage": 4200,
    "invalid_charger": 0,
    "battery_low": false
  },
  "msg": "OK",
  "request_id": "bs123456"
}
  • Note:
    • Returns the latest battery information after setting, with the same format as the /battery/get endpoint
    • At least one parameter must be provided, otherwise an error will be returned
    • The level parameter must be in the range 0-100, otherwise the setting will fail
    • For field descriptions, please refer to the /battery/get endpoint

Localization (Locale) ​

Get Localization Info ​

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

  • URL: /locale/list
  • Method: GET
  • Parameters:
    ParameterTypeRequiredDescription
    display_languagesarrayNoList 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:
    ParameterTypeRequiredDescription
    textstringYesText content
  • Request Example:
    json
    {
  "text": "Hello World"
}
  • 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:
    ParameterTypeRequiredDescription
    rotationintYesRotation angle: 0=0°, 1=90°, 2=180°, 3=270°
  • Request Example:
    json
    {
  "rotation": 1
}
  • 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:
    ParameterTypeRequiredDescription
    formatstringNowebp, png, jpeg (Default is jpg)
    qualityintNoQuality (1-100), default 100
  • Returns: Raw image binary stream (Content-Type: image/jpeg, etc.).

Get Screenshot (Raw) ​

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

Call Log Management (CallLog) ​

Add Call Log ​

Requires API version 1.0.4 or higher.

  • URL: /calllog/add
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    numberstringYesPhone number
    typeintNoType: 1=Incoming, 2=Outgoing, 3=Missed (Default 1)
    datelongNoTimestamp, default current time
    durationlongNoDuration (seconds), default 0
  • Request Example:
    json
    {
  "number": "13800001234",
  "type": 1,
  "duration": 60
}
  • Response Example:
    json
    {
  "code": 200,
  "data": [
    {
      "_id": 1,
      "number": "13800001234",
      "type": 1,
      "type_name": "INCOMING_TYPE",
      "date": 1678888888000,
      "duration": 60,
      "new": 0,
      "cached_name": null,
      "contact": {
        "_id": 3,
        "display_name": "John"
      }
    }
  ],
  "msg": "OK",
  "request_id": "cla123456"
}

Batch Add Call Logs ​

Requires API version 1.0.4 or higher.

  • URL: /calllog/add_list
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    calllog_listarrayYesCall log list, each item contains number, type, date, duration
  • Request Example:
    json
    {
  "list": [
    { "number": "13800001234", "type": 1, "duration": 60 },
    { "number": "13900005678", "type": 2, "duration": 120 }
  ]
}
  • Response Example:
    json
    {
  "code": 200,
  "data": [
    {
      "_id": 1,
      "number": "13800001234",
      "type": 1,
      "type_name": "INCOMING_TYPE",
      "date": 1678888888000,
      "duration": 60,
      "new": 0,
      "cached_name": null,
      "contact": {
        "_id": 3,
        "display_name": "John"
      }
    },
    {
      "_id": 2,
      "number": "13900005678",
      "type": 2,
      "type_name": "OUTGOING_TYPE",
      "date": 1678888889000,
      "duration": 120,
      "new": 0,
      "cached_name": null
    }
  ],
  "msg": "OK",
  "request_id": "clal123456"
}

Delete Call Log ​

Requires API version 1.0.4 or higher.

  • URL: /calllog/delete
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    idlongYesCall log ID
  • Response Example:
    json
    {
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "cld123456"
}

Batch Delete Call Logs ​

Requires API version 1.0.4 or higher.

  • URL: /calllog/delete_list
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    idsarrayYesArray of call log IDs
  • Request Example:
    json
    {
  "ids": [1, 2, 3]
}
  • Response Example:
    json
    {
  "code": 200,
  "data": 3,
  "msg": "OK",
  "request_id": "cldl123456"
}
  • Note: Returns the number of records successfully deleted.

Clear Call Log ​

Requires API version 1.0.4 or higher.

  • URL: /calllog/clear
  • Method: POST
  • Response Example:
    json
    {
  "code": 200,
  "data": 15,
  "msg": "OK",
  "request_id": "clc123456"
}
  • Note: Returns the number of deleted records.

Get Call Log List ​

Requires API version 1.0.4 or higher.

  • URL: /calllog/list
  • Method: GET
  • Parameters:
    ParameterTypeRequiredDescription
    limitintNoLimit count, default 100
    offsetintNoOffset, default 0
  • Response Example:
    json
    {
  "code": 200,
  "data": {
    "offset": 0,
    "limit": 100,
    "count": 1,
    "list": [
      {
        "_id": 1,
        "number": "13800001234",
        "type": 1,
        "type_name": "INCOMING_TYPE",
        "date": 1678888888000,
        "duration": 60,
        "new": 0,
        "cached_name": "John",
        "contact": {
          "_id": 3,
          "display_name": "John"
        }
      }
    ]
  },
  "msg": "OK",
  "request_id": "cll123456"
}
  • Response Fields:
    FieldTypeDescription
    _idlongUnique call log ID
    numberstringPhone number
    typeintCall type: 1=Incoming, 2=Outgoing, 3=Missed, 4=Voicemail, 5=Rejected, 6=Blocked
    type_namestringCall type constant name (e.g., INCOMING_TYPE)
    datelongCall timestamp (ms)
    durationlongCall duration (seconds)
    newintWhether it's a new record: 1=Yes, 0=No
    cached_namestringCached contact name (may be null)
    contactobjectContact info (returned when number matches, contains _id and display_name)

Contact Management (Contact) ​

Add Contact ​

Requires API version 1.0.4 or higher.

  • URL: /contact/add
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    namestringYesName
    phonestringYesPhone number
    emailstringNoEmail
    organizationstringNoCompany/Organization
    titlestringNoJob title
    notestringNoRemark
  • Request Example:
    json
    {
  "name": "Zhang San",
  "phone": "13800138000"
}
  • Response Example:
    json
    {
  "code": 200,
  "data": [
    {
      "_id": 1,
      "display_name": "Zhang San",
      "has_phone_number": 1,
      "phones": ["13800138000"]
    }
  ],
  "msg": "OK",
  "request_id": "con1234567890"
}

Batch Add Contacts ​

Requires API version 1.0.4 or higher.

  • URL: /contact/add_list
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    contact_listarrayYesContact list, each item contains name, phone, email, organization, title, note
  • Request Example:
    json
    {
  "contact_list": [
    { "name": "Zhang San", "phone": "13800138000" },
    { "name": "Li Si", "phone": "13900139000", "email": "lisi@example.com" }
  ]
}
  • Response Example:
    json
    {
  "code": 200,
  "data": [
    {
      "_id": 1,
      "display_name": "Zhang San",
      "has_phone_number": 1,
      "phones": ["13800138000"]
    },
    {
      "_id": 2,
      "display_name": "Li Si",
      "has_phone_number": 1,
      "phones": ["13900139000"]
    }
  ],
  "msg": "OK",
  "request_id": "cal123456"
}

Delete Contact ​

Requires API version 1.0.4 or higher.

  • URL: /contact/delete
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    idlongYesContact ID
  • Request Example:
    json
    {
  "id": 1
}
  • Response Example:
    json
    {
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "cd123456"
}

Batch Delete Contacts ​

Requires API version 1.0.4 or higher.

  • URL: /contact/delete_list
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    idsarrayYesArray of contact IDs
  • Request Example:
    json
    {
  "ids": [1, 2, 3]
}
  • Response Example:
    json
    {
  "code": 200,
  "data": 3,
  "msg": "OK",
  "request_id": "cdl123456"
}
  • Note: Returns the number of records successfully deleted.

Get Contact List ​

  • URL: /contact/list
  • Method: GET
  • Parameters:
    ParameterTypeRequiredDescription
    offsetintNoOffset, default 0
    limitintNoLimit count, default 100
  • Response Example:
    json
    {
  "code": 200,
  "data": {
    "offset": 0,
    "limit": 100,
    "count": 1,
    "list": [
      {
        "_id": 1,
        "display_name": "Zhang San",
        "has_phone_number": 1,
        "phones": ["13800138000"]
      }
    ]
  },
  "msg": "OK",
  "request_id": "cl123456"
}
  • Response Fields:
    FieldTypeDescription
    _idlongUnique contact ID
    display_namestringContact display name
    has_phone_numberintHas phone number: 1=Yes, 0=No
    phonesarrayList of phone numbers

Query Contacts ​

Requires API version 1.0.4 or higher.

  • URL: /contact/query
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    idlongNoContact ID
    namestringNoContact name (fuzzy match)
    phonestringNoPhone number
    offsetintNoOffset, default 0
    limitintNoLimit count, default 100
  • Request Example:
    json
    {
  "name": "John"
}
  • Response Example:
    json
    {
  "code": 200,
  "data": {
    "offset": 0,
    "limit": 100,
    "count": 1,
    "list": [
      {
        "_id": 1,
        "display_name": "John Doe",
        "has_phone_number": 1,
        "phones": ["13800001234"]
      }
    ]
  },
  "msg": "OK",
  "request_id": "cq123456"
}
  • Note: Supports querying contacts by ID, name (fuzzy match), or phone number. Parameters can be combined. If no parameters are provided, returns all contacts.

Clear Contacts ​

Requires API version 1.0.4 or higher.

  • URL: /contact/clear
  • Method: POST
  • Response Example:
    json
    {
  "code": 200,
  "data": 5,
  "msg": "OK",
  "request_id": "cc123456"
}
  • Note: Returns the number of deleted records.

SMS Management (SMS) ​

Get SMS List ​

  • URL: /sms/list
  • Method: GET
  • Parameters:
    ParameterTypeRequiredDescription
    typeintNoSMS type (0: All, 1: Inbox, 2: Sent, 3: Draft, 4: Outbox, 5: Failed, 6: Queued), default 0
    offsetintNoOffset, default 0
    limitintNoLimit count, default 100
  • Response Example:
    json
    {
  "code": 200,
  "data": {
    "type": 0,
    "offset": 0,
    "limit": 100,
    "count": 1,
    "list": [
      {
        "_id": 1,
        "address": "13800001234",
        "body": "Hello, this is a test message.",
        "date": 1736412345000,
        "type": 1,
        "type_name": "MESSAGE_TYPE_INBOX",
        "read": 1,
        "seen": 1,
        "creator": "com.android.messaging",
        "contact": {
          "_id": 3,
          "display_name": "John"
        }
      }
    ]
  },
  "msg": "OK",
  "request_id": "sl123456"
}
  • Response Fields:
    FieldTypeDescription
    _idlongUnique SMS ID
    addressstringRecipient/Sender number
    bodystringSMS content
    datelongTimestamp (ms)
    typeintSMS type: 1=Inbox, 2=Sent, 3=Draft, 4=Outbox, 5=Failed, 6=Queued
    type_namestringSMS type constant name (e.g., MESSAGE_TYPE_INBOX)
    readintWhether read: 1=Yes, 0=No
    seenintWhether displayed: 1=Yes, 0=No
    creatorstringCreator package name
    contactobjectContact info (returned when number matches, contains _id and display_name)

Add SMS ​

Requires API version 1.0.4 or higher.

  • URL: /sms/add
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    addressstringYesRecipient/Sender number
    bodystringYesSMS content
    typeintNoSMS type (1: Inbox, 2: Sent, 3: Draft, 4: Outbox, 5: Failed, 6: Queued), default 1
    datelongNoTimestamp, default current time
    readbooleanNoWhether read, default true
    seenbooleanNoWhether displayed, default true
  • Request Example:
    json
    {
  "address": "13800001234",
  "body": "Hello, this is a test message.",
  "type": 1,
  "read": true,
  "seen": true
}
  • Response Example:
    json
    {
  "code": 200,
  "data": [
    {
      "_id": 1,
      "address": "13800001234",
      "body": "Hello, this is a test message.",
      "date": 1736412345000,
      "type": 1,
      "type_name": "MESSAGE_TYPE_INBOX",
      "read": 1,
      "seen": 1,
      "creator": "com.android.messaging",
      "contact": {
        "_id": 3,
        "display_name": "John"
      }
    }
  ],
  "msg": "OK",
  "request_id": "sa123456"
}

Batch Add SMS ​

Requires API version 1.0.4 or higher.

  • URL: /sms/add_list
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    sms_listarrayYesSMS list, each item contains address, body, type, date, read, seen
  • Request Example:
    json
    {
  "list": [
    { "address": "13800001234", "body": "test msg1", "type": 1 },
    { "address": "13900005678", "body": "test msg2", "type": 1 }
  ]
}
  • Response Example:
    json
    {
  "code": 200,
  "data": [
    {
      "_id": 1,
      "address": "13800001234",
      "body": "test msg1",
      "date": 1736412345000,
      "type": 1,
      "type_name": "MESSAGE_TYPE_INBOX",
      "read": 1,
      "seen": 1,
      "creator": "com.android.messaging",
      "contact": {
        "_id": 3,
        "display_name": "John"
      }
    },
    {
      "_id": 2,
      "address": "13900005678",
      "body": "test msg2",
      "date": 1736412346000,
      "type": 1,
      "type_name": "MESSAGE_TYPE_INBOX",
      "read": 1,
      "seen": 1,
      "creator": "com.android.messaging"
    }
  ],
  "msg": "OK",
  "request_id": "sal123456"
}

Receive SMS (Simulate Incoming SMS) ​

Simulate receiving an SMS, which triggers the complete SMS reception flow. Requires API version 1.0.4 or higher, currently supports Android 13 / 14.

  • URL: /sms/receive
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    senderstringYesSender number
    bodystringYesSMS content
  • Request Example:
    json
    {
  "sender": "13800001234",
  "body": "Your verification code is 123456."
}
  • Response Example:
    json
    {
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "sr123456"
}
  • Note: The difference from /sms/add is that this endpoint triggers the complete SMS reception flow including system notifications and broadcasts, while /sms/add only adds a record to the database.

Delete SMS ​

  • URL: /sms/delete
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    idlongYesSMS ID
  • Response Example:
    json
    {
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "sd123456"
}

Batch Delete SMS ​

Requires API version 1.0.4 or higher.

  • URL: /sms/delete_list
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    idsarrayYesArray of SMS IDs
  • Request Example:
    json
    {
  "ids": [1, 2, 3]
}
  • Response Example:
    json
    {
  "code": 200,
  "data": 3,
  "msg": "OK",
  "request_id": "sdl123456"
}
  • Note: Returns the number of records successfully deleted.

Clear SMS ​

Requires API version 1.0.4 or higher.

  • URL: /sms/clear
  • Method: POST
  • Response Example:
    json
    {
  "code": 200,
  "data": 20,
  "msg": "OK",
  "request_id": "sc123456"
}
  • Note: Returns the number of deleted records.

Location Management (Location) ​

Get Location Info ​

Get current device GPS location information using standard Android API. Requires API version 1.0.4 or higher.

  • URL: /location/get_data
  • Method: GET
  • Response Example:
    json
    {
  "code": 200,
  "data": {
    "latitude": 39.9042,
    "longitude": 116.4074,
    "altitude": 0.0,
    "speed": 0.0,
    "bearing": 0.0,
    "accuracy": 50.0,
    "vertical_accuracy_meters": 50.0,
    "speed_accuracy_meters_per_second": 1.0,
    "bearing_accuracy_degrees": 30.0,
    "enabled": true,
    "time": 1673641234567,
    "provider": "gps"
  },
  "msg": "OK",
  "request_id": "lg123456"
}
  • Response Fields:
    FieldTypeDescription
    latitudedoubleLatitude
    longitudedoubleLongitude
    altitudedoubleAltitude (meters)
    speeddoubleSpeed (m/s)
    bearingdoubleBearing (degrees)
    accuracyfloatHorizontal accuracy (meters)
    vertical_accuracy_metersfloatVertical accuracy (meters)
    speed_accuracy_meters_per_secondfloatSpeed accuracy (m/s)
    bearing_accuracy_degreesfloatBearing accuracy (degrees)
    enabledbooleanWhether mock location is enabled
    timelongTimestamp of location fix (ms)
    providerstringLocation provider (e.g., gps, network, properties)

Set Location Information ​

Simulate device GPS location information. Requires API version 1.0.4 or higher.

  • URL: /location/set_data
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    enabledbooleanNoWhether to enable mock location
    persistbooleanNoWhether to persist (effective after reboot), default false
    latitudedoubleNoLatitude
    longitudedoubleNoLongitude
    altitudedoubleNoAltitude (meters), default 0.0
    speeddoubleNoSpeed (m/s), default 0.0
    bearingdoubleNoBearing (degrees), default 0.0
    accuracydoubleNoHorizontal accuracy (meters), default 50.0
    vertical_accuracy_metersdoubleNoVertical accuracy (meters), default 50.0
    speed_accuracy_meters_per_seconddoubleNoSpeed accuracy (m/s), default 1.0
    bearing_accuracy_degreesdoubleNoBearing accuracy (degrees), default 30.0
  • Request Example:
    json
    {
  "latitude": 39.9042,
  "longitude": 116.4074,
  "vertical_accuracy_meters": 50.0,
  "enabled": true,
  "persist": true
}
  • Response Example:
    json
    {
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "ls123456"
}

Sensor Management (Sensor) ​

Get Sensor List ​

Get information about all sensors supported by the system. Requires API version 1.0.4 or higher.

  • URL: /sensor/list
  • Method: GET
  • Parameters:
    ParameterTypeRequiredDescription
    typeintNoSensor type ID, returns all if not passed
  • Response Example:
    json
    {
  "code": 200,
  "data": [
    {
      "name": "Goldfish 3-axis Accelerometer",
      "type": 1,
      "type_name": "TYPE_ACCELEROMETER",
      "vendor": "The Android Open Source Project",
      "version": 1,
      "resolution": 0.0,
      "power": 0.0,
      "min_delay": 0,
      "string_type": "android.sensor.accelerometer"
    }
  ],
  "msg": "OK",
  "request_id": "sl123456"
}
  • Response Fields:
    FieldTypeDescription
    namestringSensor name
    typeintSensor type ID
    type_namestringSensor type constant name
    vendorstringSensor vendor
    versionintSensor version
    resolutionfloatSensor resolution
    powerfloatPower consumption (mA)
    min_delayintMinimum sampling interval (microseconds)
    string_typestringSensor type string

Get Sensor Data ​

Get real-time data of the current sensor. Requires API version 1.0.4 or higher.

  • URL: /sensor/get_data
  • Method: GET
  • Parameters:
    ParameterTypeRequiredDescription
    typeintNoSensor type ID (e.g., 1 for accelerometer), returns all sensor data if not passed
    timeoutlongNoTimeout for getting data (ms), default 500
  • Response Example (Single Sensor):
    json
    {
  "code": 200,
  "data": {
    "type": 1,
    "type_name": "TYPE_ACCELEROMETER",
    "name": "Goldfish 3-axis Accelerometer",
    "values": [0.0, 9.8, 0.0],
    "timestamp": 1673641234567
  },
  "msg": "OK",
  "request_id": "sg123456"
}
  • Response Example (All Sensors):
    json
    {
  "code": 200,
  "data": {
    "sensors": [
      {
        "type": 1,
        "type_name": "TYPE_ACCELEROMETER",
        "name": "Goldfish 3-axis Accelerometer",
        "values": [0.0, 9.8, 0.0]
      }
    ],
    "timestamp": 1673641234567
  },
  "msg": "OK",
  "request_id": "sg123456"
}

Set Sensor Data ​

Set simulation data for virtual sensors. Requires API version 1.0.4 or higher.

  • URL: /sensor/set_data
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    sensorsarrayYesList of sensor data entries
  • Sensor Object Description:
    ParameterTypeRequiredDescription
    typeintYesSensor type, see table below
    valuedoubleNoValue for single-axis sensors (e.g., light, pressure, proximity, humidity, temperature, step count)
    xdoubleNoX-axis value for three-axis sensors (e.g., accelerometer, magnetic field, gyroscope)
    ydoubleNoY-axis value
    zdoubleNoZ-axis value
  • Sensor Types:
    typeConstantDescription
    1TYPE_ACCELEROMETERAccelerometer Sensor
    2TYPE_MAGNETIC_FIELDMagnetic Field Sensor
    3TYPE_ORIENTATIONOrientation Sensor
    4TYPE_GYROSCOPEGyroscope Sensor
    5TYPE_LIGHTLight Sensor
    6TYPE_PRESSUREPressure Sensor
    8TYPE_PROXIMITYProximity Sensor
    9TYPE_GRAVITYGravity Sensor
    10TYPE_LINEAR_ACCELERATIONLinear Acceleration Sensor
    11TYPE_ROTATION_VECTORRotation Vector Sensor
    12TYPE_RELATIVE_HUMIDITYHumidity Sensor
    13TYPE_AMBIENT_TEMPERATURETemperature Sensor
    14TYPE_MAGNETIC_FIELD_UNCALIBRATEDUncalibrated Magnetic Field Sensor
    15TYPE_GAME_ROTATION_VECTORGame Rotation Vector Sensor
    16TYPE_GYROSCOPE_UNCALIBRATEDUncalibrated Gyroscope Sensor
    17TYPE_SIGNIFICANT_MOTIONSignificant Motion Sensor
    18TYPE_STEP_DETECTORStep Detector Sensor
    19TYPE_STEP_COUNTERStep Counter Sensor
    20TYPE_GEOMAGNETIC_ROTATION_VECTORGeomagnetic Rotation Vector Sensor
    21TYPE_HEART_RATEHeart Rate Sensor
    22TYPE_TILT_DETECTORTilt Detector Sensor
    25TYPE_PICK_UP_GESTUREPick Up Gesture Sensor
    26TYPE_WRIST_TILT_GESTUREWrist Tilt Sensor
    27TYPE_DEVICE_ORIENTATIONDevice Orientation Sensor
    30TYPE_MOTION_DETECTMotion Detect Sensor
    35TYPE_ACCELEROMETER_UNCALIBRATEDUncalibrated Accelerometer Sensor
    36TYPE_HINGE_ANGLEHinge Angle Sensor
  • Request Example:
    json
    {
  "sensors": [
    {
      "type": 5,
      "value": 100.0
    },
    {
      "type": 2,
      "x": 1.0,
      "y": 2.0,
      "z": 3.0
    }
  ]
}
  • Response Example:
    json
    {
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "ss123456"
}

Account Management (Account) ​

Add Account ​

  • URL: /account/add
  • Method: POST
  • Parameters:
    ParameterTypeRequiredDescription
    namestringYesAccount name (e.g., example@gmail.com)
    typestringYesAccount type (e.g., com.google)
    passwordstringNoPassword
    user_dataobjectNoCustom 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:
    ParameterTypeRequiredDescription
    typestringNoFilter 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:
    ParameterTypeRequiredDescription
    namestringYesAccount name
    typestringYesAccount 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:
    ParameterTypeRequiredDescription
    stream_typestringYesVolume type: music, voice_call, ring, alarm, notification
    volumeintYesVolume value (0 to Max)
    show_uibooleanNoWhether 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:
    ParameterTypeRequiredDescription
    mutebooleanYestrue 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"
}

UI Node Operations ​

Unified interface for node finding and operations, supporting finding, waiting, and performing actions. Requires image version 20260201 or above.

  • URL: /accessibility/node

  • Method: POST

  • Parameters:

    ParameterTypeRequiredDescription
    selectorobjectYesNode selector containing search criteria
    wait_timeoutlongNoWait timeout (ms), default 0 means no wait
    wait_intervallongNoWait interval (ms), default 500
    actionstringNoAction name to execute (e.g., click, set_text)
    action_paramsobjectNoAction parameters (e.g., text)
    action_indexintNoIndex of the node to act on, default 0

  • Selector Parameters:

    ParameterTypeRequiredDescription
    xpathstringNoXPath expression, highest priority
    textstringNoNode text. Supports regex (e.g., .*Settings.*)
    content_descstringNoNode content description. Supports regex
    namestringNoNode text or content description. Supports regex
    classstringNoNode class name (class)
    resource_idstringNoNode resource ID (resource-id)
    packagestringNoApplication package name
    indexintNoIndex of the node within its parent
    clickablebooleanNoWhether clickable
    enabledbooleanNoWhether enabled
    scrollablebooleanNoWhether scrollable
    focusablebooleanNoWhether focusable
    focusedbooleanNoWhether focused
    selectedbooleanNoWhether selected
    checkablebooleanNoWhether checkable
    checkedbooleanNoWhether checked
    center_xintNoNode center X coordinate
    center_yintNoNode center Y coordinate

  • Supported Actions:

    • click: Click
    • long_click: Long click
    • set_text: Set text (requires parameter text)
    • clear_text: Clear text
    • scroll_forward / scroll_backward: Scroll forward/backward
    • scroll_up / scroll_down / scroll_left / scroll_right: Directional scroll
    • focus / clear_focus: Get/Clear focus
    • select / clear_selection: Select/Deselect
    • copy / paste / cut: Clipboard operations
    • expand / collapse: Expand/Collapse
    • ime_enter: IME Enter

  • Request Example (Exact Match):

    json
    {
  "selector": {
    "text": "Settings"
  },
  "action": "click"
}

  • Request Example (XPath Match):

    json
    {
  "selector": {
    "xpath": "//node[@text='Settings' and @clickable='true']"
  },
  "action": "click"
}

  • Request Example (Wait and Set Text):

    json
    {
  "selector": {
    "resource_id": "com.example:id/input"
  },
  "wait_timeout": 5000,
  "action": "set_text",
  "action_params": {
    "text": "Hello"
  }
}

  • Response Example:

    json
    {
  "code": 200,
  "data": {
    "count": 1,
    "nodes": [ ... ],
    "action": "click",
    "action_index": 0,
    "action_node": { ... }
  },
  "msg": "OK",
  "request_id": "an123456"
}

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:
    ParameterTypeRequiredDescription
    package_namesarrayYesList of accessibility service package names
    hiddenbooleanNoWhether 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:
    ParameterTypeRequiredDescription
    package_namestringNoFilter 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:
    ParameterTypeRequiredDescription
    package_namestringYesApplication 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:
    ParameterTypeRequiredDescription
    is_chinabooleanNoWhether 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:
    ParameterTypeRequiredDescription
    enabledbooleanYestrue 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:
    ParameterTypeRequiredDescription
    gaidstringNoSpecify 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"
}

Powered by VMOS Edge Team

© 2026 VMOS Edge