Skip to content

Create a command request
Stable

Request

Issues a device or group-level command using the stable command API. This endpoint supports multi-OS environments and scheduling options, and should be used for all new command integrations. Common use cases: Installing or uninstalling apps, pushing certificates, modifying device settings, sending notifications, enforcing policies, and other device actions supported by Esper. Best Practices: Ensure the command is supported for the device’s OS before sending. Decide whether to target specific devices (DEVICE) or a device group (GROUP). Determine whether the command should run IMMEDIATE or use scheduling options (if supported by the command). Validate command_args carefully—payload structure differs by command. Understand the command lifecycle (queued → acknowledged → in progress → success/failure). Monitor execution and final state in the Event Feed after issuing the request. Important: Response bodies can vary depending on the command. For detailed examples and command-specific payload guidance, refer to the API Commands help documentation: https://help.esper.io/hc/en-us/articles/29710806069393-Creating-API-Commands

You can send the command immediately or schedule command for supported devices.

Scheduled commands are currently compatible with Android devices.

Security
commands_apiKey
Bodyapplication/jsonrequired
command_typestring

Identifies the type of command

* DEVICE: command request is meant for devices
* GROUP: command request is meant for groups
* DYNAMIC: command request is meant for dynamic set of devices
  i.e subset of devices from different groups or otherwise.
Enum:"DEVICE""GROUP""DYNAMIC"
aliasstring

Another name for the command, provided by the user or Console.

devicesArray of strings, (uuid), [ 0 .. 1000 ] items

List of devices to run commands. Required if command_type is 'DEVICE' or 'DYNAMIC'

groupsArray of strings, (uuid), [ 0 .. 500 ] items

List of groups to run commands. Required if command_type is 'GROUP' or 'DYNAMIC'

device_typestring

Filtering by device_type is currently not supported. Please specify 'all'.

Value:"all"
commandstring(commands_DeviceCommandEnum)

Following commands are supported

* ADD_TO_WHITELIST: Whitelist an installed sytem app. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper
* ADD_WIFI_AP : Add wifi access points for device. Requires `wifi_access_points` in command arguments where `wifi_access_points` is the data with access points
* APPLY_APP_CONFIG : Apply app configuration for an installed app.
* CLEAR_APP_DATA : Clear data for an installed app. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper
* CLEAR_APP_CACHE : Clear the cache of an installed app without removing its data. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper. Supported on Android 6.0+ devices with the supervisor installed.
* CONVERGE: Converge command for Blueprint
* INSTALL: Install an app on a device. Requires `app_version` in command arguments where `app_version` is the version id of app uploaded on Esper
* INSTALL_CERTIFICATE: Install a certificate chain in the system keystore of an android device. Requires `cert_file_type`, `cert_data_base64`, `cert_alias_name` and `cert_storage_type` in command arguments where `cert_file_type` must be set to "pkcs12", `cert_data_base64` contains the base64 encoded content of the pkcs12 file, `cert_alias_name` is the alias name with which the certificate chain is supposed to be installed and `cert_storage_type` must be set to "system". If the pkcs12 file is password protected, the password should be specified in the optional parameter `cert_password`.
* LOCK: Lock device screen, Supports Android, iOS and Windows devices.
* REBOOT: Reboot a device. Supports Android, iOS, and Windows devices.
* REMOVE_FROM_WHITELIST : Remove an installed system app from whitelist. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper
* REMOVE_WIFI_AP : Remove Wifi access points for device. Requires `wifi_access_points` in command arguments where `wifi_access_points` is the data with access points
* UPDATE_WIFI_AP : Update Wi-Fi access point configuration on device. Requires `wifi_ssid` and `wifi_security_type` in command arguments. Device must be connected to the target SSID. Supports EAP (enterprise) and personal (WPA2/WPA/WEP) networks. On failure, attempts to restore the previous configuration. Android only.
* SET_APP_PERMISSION : Set permission for an installed app. Requires `package_name`, `grant_state`, `permission` in command arguments where `package_name` is the app package uploaded on Esper, `grant_state` should be "PERMISSION_GRANT_STATE_DEFAULT", "PERMISSION_GRANT_STATE_DENIED", "PERMISSION_GRANT_STATE_GRANTED" and `permission` is a valid permission
* SET_APP_STATE : Set the state of an app - SHOW/HIDE/DISABLE/LAUNCHABLE_BUT_HIDDEN. Requries `app_state` and `package_name` in command arguments where `app_state` is the state of app and `package_name` is the app package uploaded on Esper For LAUNCHABLE_BUT_HIDDEN: Hide an app on the home screen but allow it to be launched from other apps. Requires Esper agent 8.5+ and `package_name`. 
* SET_BLUETOOTH_STATE : Set bluetooth state (ON/OFF) for device. Requires `bluetooth_state` in command arguments where `bluetooth_state` is a boolean.
* SET_BRIGHTNESS_SCALE : Set brightness for device. Requires `brightness_value` in command arguments where `brightness_value` is an integer (1-100).
* SET_DEVICE_LOCKDOWN_STATE : Set lockdown state for a device. Requires `state` and `message` in command arguments where `state` is LOCKED/UNLOCKED and `message` is the message to be added with command
* SET_GPS_STATE :Set the GPS state for a device. Requires `gps_state` in command arguments where `gps_state` should be either 0, 1, 2, 3 or 4 (LOCATION_MODE_HIGH_ACCURACY = 0, LOCATION_MODE_SENSORS_ONLY = 1, LOCATION_MODE_BATTERY_SAVING = 2, LOCATION_MODE_OFF = 3, LOCATION_MODE_ON = 4)
* SET_KIOSK_APP : Command to set the Kiosk app for a device. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper. For iOS devices, optionally accepts `disable_device_rotation` (boolean, default false) which disables device rotation sensing while in kiosk mode, and `disable_screen_timeout` (boolean, default true) which disables the screen auto-lock/timeout while in kiosk mode.

* SET_MULTI_APP_MODE : Command to set the device back to multi app mode.
* SET_NEW_POLICY : Apply policy on device. Requires `policy_url` in command arguments where `policy_url` is the URL to the policy
* SET_ROTATION_STATE : Set screen orientation. Requires `rotate_state` in command arguments where `rotate_state` should be either 0, 1 or 2 (0 = AUTO, 1 = PORTRAIT_ONLY, 2 = LANDSCAPE_ONLY)
* SET_SCREEN_OFF_TIMEOUT: Set screen off timeout for a device. Requires `screen_off_timeout` in command arguments where `screen_off_timeout` should be either -1 or between 5000 and 1800000
* SET_STREAM_VOLUME : Set strema volume for a device. Requires `stream` and `volume_level` in command arguments where `stream` should be either 0(Ring), 1(Notification), 2(Alarm) or 3(Music) and `volume_level` should be a value from 0 to 100
* SET_TIMEZONE : Set the timezone for a device. Requires `timezone_string` in command arguments where `timezone_string` is a valid string representing the timezone
* SET_WIFI_STATE : Set the wifi state (ON/OFF) for a device. Requires `wifi_state` in command arguments where `wifi_state` is a boolean.
* UNINSTALL: Uninstall an app from device. Requires `package_name` in command arguments where `package_name` is the app package uploaded on Esper
* UNINSTALL_CERTIFICATE: Uninstall a certificate from an android device's system keystore using the installed certificate's alias name. Requires `cert_alias_name` and `cert_storage_type` in command arguments where `cert_alias_name` is the alias name of the certificate to be uninstalled and `cert_storage_type` must be set to "system"
* UPDATE_DEVICE_CONFIG: Push additional configurations to the Device
* UPDATE_HEARTBEAT: Ping a device
* UPDATE_LATEST_DPC : Prompt device to update the DPC app to the latest versions.
* WIPE : Wipes the device.
* RESET_LOCKSCREEN_PASSWORD: Change the lockscreen password of the device. Requires `new_lockscreen_password` in command arguments where `new_lockscreen_password` is a valid string.
* UPDATE_BLUEPRINT: Pushes or reapplies the most current Blueprint version to the device or group.
* NOTIFY_DEVICE: Allows you to  broadcast message to the device.
* SET_DEVICE_LANGUAGE: Set language for a device. Requires locale value in xx[_Zzzz]_yy where xx is language code, Zzzz is script (optional) and yy is country code.
* SET_ETHERNET_SETTINGS: Set ethernet settings on supported Device
* SET_STATIC_IP: Set static ip on the deivce. Requires interface, dhcp_dnabled, static_ip, primary_dns, subnet_mask, gateway, secondary_dns (optional)
* BEEP_DEVICE: Allows you to make the device beep for a specified duration
* SET_APP_NOTIFICATIONS: Enable/disable app notifications. Requries `app_notifications_state` and `package_name` in command arguments where `app_notifications_state` is a string that has the value `ENABLED` or `DISABLED` and `package_name` is the app package uploaded on Esper.
* USE_ONLY_SAVED_WIFI_AP: Allow/disallow device to connect to unregistered WiFi APs. Requires boolean `use_only_saved_ap`..
* DEVICE_INFORMATION: Prompt device to update the device information
* VPP_APP_INSTALL: Install a vpp app on an iOS device. Requires `app_id` and `bundle_identifier` in command arguments that corresponds to the associate vpp app
* APPLE_APP_UNINSTALL: Uninstall an app on an iOS device. Requires `app_id` and `bundle_identifier` in command arguments that corresponds to the associated app
* CLEAR_PASSCODE: Clear the passcode in a device
* LIST_INSTALLED_PROFILES: Returns a list of all installed profiles on an iOS device.
* INSTALL_PROFILE: Install a profile on an iOS device.
* REMOVE_PROFILE: Remove a profile from an iOS device.
* RUN_SHELL_SCRIPT: Run a shell script on a Linux or Windows device. Requires `script` and `interpreter` in command arguments.
* RUN_CUSTOM_ACTION: Run a custom action (script) on a Linux device. Requires custom action parameters in command arguments.
* COLLECT_LOGS: Collect and upload Esper agent logs from a Linux device.
* SCHEDULE_OS_UPDATE: Schedule an OS update on an Apple device. Requires `product_version` (string) and `install_action` (string, one of "Default", "DownloadOnly", "InstallASAP") in command_args.
* OS_UPDATE_STATUS: Query the status of pending or in-progress OS updates on an Apple device.
* SCAN_OS_UPDATES: Query available OS updates on an Apple device.
* ENFORCE_OS_UPDATE_SETTINGS: Configure software update settings on an Apple device via DDM (Declarative Device Management). Maps to Apple's `com.apple.configuration.softwareupdate.settings` declaration. Supports `allow_standard_user_os_updates` (boolean), `automatic_actions` (object with `download`, `install_os_updates`, `install_security_update` — each "allowed", "always_on", or "always_off"), `deferrals` (object — must specify EITHER `combined_period_in_days` alone OR all three of `major_period_in_days`, `minor_period_in_days`, `system_period_in_days`; each value 1-90 days; mixing combined with any individual field is rejected), `notifications` (boolean), `rapid_security_response` (object with `enable`, `enable_rollback` — both boolean), and `recommended_cadence` ("all", "oldest", or "newest"). Requires iOS/iPadOS 18.0+ or tvOS 18.4+.
* ENFORCE_SOFTWARE_UPDATE: Enforce software update on an Apple device. Requires `target_os_version` and `target_local_date_time` in command arguments where `target_os_version` is the OS version to update to and `target_local_date_time` is local date time value that specifies when to force install the software update. Use the format yyyy-mm-ddThh:mm:ss, which is derived from RFC3339 but doesn’t include a time zone offset. If the user doesn’t trigger the software update before this time, the device force installs it. Applicable for iOS/iPadOS 17+ and tvOS 18.4+ after enabling Declarative Device Management (DDM) on the device.
* SET_OS_UPDATE_POLICY: Allow, disable or schedule automatic updates on a Windows device. Requires `auto_update_type` in command arguments. `auto_update_type` supports "NOTIFY_DOWNLOAD", "AUTO_INSTALL_AND_NOTIFY_RESTART", "DEFAULT", "SCHEDULED_INSTALL_AND_RESTART", "AUTO_INSTALL_AND_RESTART_FORCED" or "OFF".
Enum:"ADD_TO_WHITELIST""ADD_WIFI_AP""APPLY_APP_CONFIG""CLEAR_APP_CACHE""CLEAR_APP_DATA""CONVERGE""INSTALL""INSTALL_CERTIFICATE""LIST_INSTALLED_PROFILES""LOCK"
command_argsobject(Command args)
schedulestring(commands_CommandScheduleEnum)

Following Schedule types are supported

* IMMEDIATE: Schedule the command to execcute Immediately
* WINDOW: Schedule the command to execute within the given window
* RECURRING: Schedule the command to execute during the scheduled time until it succeeds or expires. After executing successfully, it will not fire again.
Enum:"IMMEDIATE""WINDOW""RECURRING"
schedule_argsobject(Command Schedule Arguments)
cURL
curl -i -X POST \
  https://api.esper.io/_mock/openapi/commands/v0/commands/ \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "command_type": "DEVICE",
    "alias": "string",
    "devices": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "groups": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "device_type": "all",
    "command": "ADD_TO_WHITELIST",
    "command_args": {
      "device_alias_name": "string",
      "custom_settings_config": {},
      "app_version": "string",
      "package_name": "string",
      "policy_url": "string",
      "wifi_access_points": {},
      "wifi_ssid": "string",
      "wifi_security_type": "NONE",
      "wifi_password": "string",
      "wifi_eap_method": "PEAP",
      "wifi_phase2_auth": "string",
      "certificate_file_path": "string",
      "certificate_file_password": "string",
      "identity": "string",
      "anonymous_identity": "string",
      "domain": "string",
      "hidden": true,
      "state": "string",
      "message": "string",
      "title": "string",
      "url": "string",
      "app_state": "string",
      "bluetooth_state": true,
      "brightness_value": 0,
      "gps_state": 0,
      "rotate_state": 0,
      "screen_off_timeout": 0,
      "stream": 0,
      "volume_level": 0,
      "timezone_string": 0,
      "wifi_state": true,
      "wifi_revert_timeout": 0,
      "locale": "string",
      "ethernet_auth_mode": "NONE",
      "ethernet_ca_cert_alias": "string",
      "ethernet_client_cert_alias": "string",
      "ethernet_eap_identity": "string",
      "interface": "string",
      "dhcp_enabled": "string",
      "static_ip": "string",
      "primary_dns": "string",
      "subnet_mask": "string",
      "secondary_dns": "string",
      "gateway": "string",
      "duration": "string",
      "video_quality": "HIGH",
      "enable_debug_mode": false,
      "app_id": "string",
      "bundle_identifier": "string",
      "managed_only": true,
      "profile_identifier": "string",
      "profile": "string",
      "is_converge": true,
      "disable_device_rotation": false,
      "disable_screen_timeout": true,
      "script": "string",
      "interpreter": "string",
      "execute_as": "string",
      "arguments": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "cert_file_type": "string",
      "cert_data_base64": "string",
      "cert_alias_name": "string",
      "cert_storage_type": "string",
      "cert_password": "string",
      "is_factory_reset": true,
      "product_version": "string",
      "install_action": "Default",
      "allow_standard_user_os_updates": true,
      "automatic_actions": {
        "download": "allowed",
        "install_os_updates": "allowed",
        "install_security_update": "allowed"
      },
      "deferrals": {
        "combined_period_in_days": 1,
        "major_period_in_days": 1,
        "minor_period_in_days": 1,
        "system_period_in_days": 1
      },
      "notifications": true,
      "rapid_security_response": {
        "enable": true,
        "enable_rollback": true
      },
      "recommended_cadence": "all",
      "target_os_version": "string",
      "target_local_date_time": "string",
      "auto_update_type": "NOTIFY_DOWNLOAD"
    },
    "schedule": "IMMEDIATE",
    "schedule_args": {
      "name": "string",
      "start_datetime": "2019-08-24T14:15:22Z",
      "end_datetime": "2019-08-24T14:15:22Z",
      "time_type": "console",
      "window_start_time": "string",
      "window_end_time": "string",
      "days": [
        "string"
      ]
    }
  }'

Responses

Command request successfully created.

Bodyapplication/json
codeinteger
messagestring
contentobject(commands_CommandRequest)
Response
{ "code": 0, "message": "string", "content": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "command_type": "DEVICE", "devices": [], "groups": [], "device_type": "active", "command": "ADD_TO_WHITELIST", "command_args": {}, "schedule": "IMMEDIATE", "schedule_args": {}, "reason": "string", "created_by": "string", "created_at": "2019-08-24T14:15:22Z" } }