---
title: "Create a command request"
method: POST
path: "/v0/enterprise/{enterprise_id}/command/"
tags: ["esper_cloud_api_Commands V2"]
---

# Create a command request

`POST /v0/enterprise/{enterprise_id}/command/`

⚠️ Android only. This endpoint issues commands to Android-managed devices.

Alternative Available

A newer, multi-OS commands API is available and recommended for most use cases
https://api.esper.io/openapi/command-request/createcommandrequest

Creates a command request targeting one or more devices or groups, dispatching a managed operation such as an install, reboot, lock, or configuration change. Accepts a V0CommandRequest body specifying the target scope (DEVICE, GROUP, or DYNAMIC), the command type, any required arguments, and an optional schedule. Returns the created command request including its id (request_id), which is used to poll for per-device execution status. Alternative endpoint- https://{foo}-api.esper.cloud/api/commands/v0/commands/

About Create Command Request

Esper's command system dispatches operations to enrolled Android devices asynchronously. A command request defines what to do (command), who to do it to (devices or groups), any parameters the command requires (command_args), and when to do it (schedule and schedule_args). The command_type field determines targeting scope: DEVICE targets up to 1,000 specific devices, GROUP targets up to 500 groups, and DYNAMIC targets a custom cross-group subset. After creation, use the request_id to query per-device execution status at the status endpoint.

Key Fields

command_type — targeting scope: DEVICE, GROUP, or DYNAMIC

devices — list of device UUIDs to target (up to 1,000); used with command_type: DEVICE

groups — list of group UUIDs to target (up to 500); used with command_type: GROUP

command — the operation to perform (e.g. INSTALL, REBOOT, LOCK; see V0DeviceCommandEnum for the full list)


command_args — command-specific parameters (e.g. app_version UUID for INSTALL, package_name for CLEAR_APP_DATA)

schedule — scheduling mode (immediate or deferred)

schedule_args — scheduling parameters when using deferred execution

See https://help.esper.io/hc/en-us/articles/29710806069393-Creating-API-Commands for command examples.

## Path parameters

- `enterprise_id` string, uuid, required

## Response `201`

command request successfully created

- EsperCloudApiV0CommandRequest
  - `id` string, uuid — Unique command request identifier
  - `enterprise` string, uuid — Esper account identifier
  - `command_type` 'DEVICE' | 'GROUP' | 'DYNAMIC' — 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. ```
  - `devices` string[] — list of devices to run commands
  - `groups` string[] — list of groups to run commands
  - `command` 'ADD_TO_WHITELIST' | 'ADD_WIFI_AP' | 'CLEAR_APP_DATA' | 'CLEAR_APP_CACHE' | 'INSTALL' | 'LOCK' | 'REBOOT' | 'REMOVE_FROM_WHITELIST' | 'REMOVE_WIFI_AP' | 'SET_APP_PERMISSION' | 'SET_APP_STATE' | 'SET_BLUETOOTH_STATE' | 'SET_BRIGHTNESS_SCALE' | 'SET_DEVICE_LOCKDOWN_STATE' | 'SET_GPS_STATE' | 'SET_KIOSK_APP' | 'SET_NEW_POLICY' | 'SET_ROTATION_STATE' | 'SET_SCREEN_OFF_TIMEOUT' | 'SET_STREAM_VOLUME' | 'SET_TIMEZONE' | 'SET_WIFI_STATE' | 'UNINSTALL' | 'UPDATE_DEVICE_CONFIG' | 'UPDATE_HEARTBEAT' | 'UPDATE_LATEST_DPC' | 'UPDATE_WIFI_AP' | 'WIPE' | 'RESET_LOCKSCREEN_PASSWORD' | 'UPDATE_BLUEPRINT' | 'CAPTURE_SCREENSHOT' | 'NOTIFY_DEVICE' | 'SET_DEVICE_LANGUAGE' | 'SET_ETHERNET_SETTINGS' | 'SET_STATIC_IP' | 'BEEP_DEVICE' | 'SET_APP_NOTIFICATIONS' | 'USE_ONLY_SAVED_WIFI_AP' | 'CONVERGE' | 'SYNC_CONTENT' — 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 * 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. * 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 * LOCK: Lock device screen * REBOOT: Reboot a device * 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 * 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 * 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 stream 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 * 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. * CAPTURE_SCREENSHOT: Allows you to take a screenshot of the device's current screen. The "tag" is an optional param that can be set to corresponding screenshot. * 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. Requires 'title', 'message' and 'url' (optional) as string in command arguments. For scheduled message command requires 'name', 'time_type' as string and 'start_datetime' and 'end_datetime' as date-time. * 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`. * CONVERGE: Allows you to converge the device to the latest version of its assigned blueprint. * SYNC_CONTENT: Allows you to sync content to the device. Requires `content_id` in command arguments where `content_id` is the id of the content to be synced. ```
  - `command_args` EsperCloudApiV0CommandArgs
    - `device_alias_name` string — Alternate human-readable name for your Device
    - `custom_settings_config` object — Managed configurations for your device (passed as JSON object)
    - `app_version` string — The version id of app uploaded on Esper
    - `package_name` string — The app package name uploaded on Esper
    - `policy_url` string — The URL to the policy
    - `wifi_access_points` object — Wifi access points for the device (passed as JSON object)
    - `state` string — LOCKED/UNLOCKED
    - `message` string — Message to be added with command to notify device.
    - `title` string — Message title to be added with command to notify device.
    - `url` string — (Optional) Link to notify device.
    - `app_state` string — The state of app - SHOW/HIDE/DISABLE/LAUNCHABLE_BUT_HIDDEN
    - `bluetooth_state` boolean — The state of bluetooth - ON/OFF
    - `brightness_value` integer — The brightness value of a device(1-100)
    - `gps_state` integer — The GPS state of a device. 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)
    - `rotate_state` integer — The screen orientation of a device. Should be either 0, 1 or 2 (0 = AUTO, 1 = PORTRAIT_ONLY, 2 = LANDSCAPE_ONLY)
    - `screen_off_timeout` integer — The value for screen timeout of a device. Should be either -1 or between 5000 and 1800000
    - `stream` integer — The value of the volume stream. Should be either 0(Ring), 1(Notification), 2(Alarm) or 3(Music)
    - `volume_level` integer — The level of volume. Should be a value from 0 to 100
    - `timezone_string` integer — The timezone of a device. Should be a valid timezone string
    - `wifi_state` boolean — The state of WIFI - ON/OFF
    - `wifi_revert_timeout` integer — The WIFI revert timeout. Should be greater than or equal to 1
    - `locale` string — Language and country code in xx[_Zzzz]_yy where xx is language code, Zzzz is script (optional) and yy is country code.
    - `ethernet_auth_mode` 'NONE' | 'EAP_TLS' — Chosen mode of authentication
    - `ethernet_ca_cert_alias` string — CA certificate alias. It is mandatory with Auth Mode EAP_TLS
    - `ethernet_client_cert_alias` string — Client certificate alias. It is mandatory with Auth Mode EAP_TLS
    - `ethernet_eap_identity` string — EAP identity
    - `interface` string — The network interface of the device - wlan/eth
    - `dhcp_enabled` string — The dhcp state on the device - true/false
    - `static_ip` string — The static ip to set on the device. Should be a valid ipv4
    - `primary_dns` string — The primary dns to set on the device. Should be a valid ipv4
    - `subnet_mask` string — The subnet mask set on the device. Should between 1-32 both inclusive
    - `secondary_dns` string — The secondary dns to set on the device. Should be a valid ipv4
    - `gateway` string — The gateway to set on the device. Should be a valid ipv4
    - `duration` string — The beep duration specified in seconds. Value must be between 10 and 300, both inclusive.
    - `tag` string — The tag is an optional param that can be set to corresponding screenshot. Options are "tag".
    - `video_quality` string — The video quality of the respective Remote Viewer session. Options are "STANDARD" and "DATA_SAVER".
    - `enable_debug_mode` boolean — The flag to determine whether device must go into Debug Mode, in order to retreive bug report when the device is already in Kiosk Mode.
    - `converge_with_provision_option` boolean — The flag to determine whether device should be converged with provision only or not.
    - `auto_update_mode` 'autoUpdateDefault' | 'autoUpdateHighPriority' | 'autoUpdatePostponed' — (Optional) Auto update mode for google play application
    - `content_id` string — The id of the content to be synced.
  - `schedule` 'IMMEDIATE' | 'WINDOW' | 'RECURRING' — 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. ```
  - `schedule_args` EsperCloudApiV0CommandScheduleArgs
    - `name` string
    - `start_datetime` string, date-time
    - `end_datetime` string, date-time
    - `time_type` 'console' | 'device' — The Time-Type argument, in Schedule args, is to indicate which timezone the Command Framework should utilize when scheduling the command. Following Schedule Args for Time-Type are supported: ``` * CONSOLE: Use the local timezone of the user creating the schedule. * DEVICE: Use the local timezone of the device, to which the command is issued, wherever it may be. ```
    - `window_start_time` string — It is automatically populated by the time field from the request's start_datetime and cannot be injected via the API request body.
    - `window_end_time` string — It is automatically populated by the time field from the request's end_datetime and cannot be injected via the API request body.
    - `days` string[]
  - `issued_by` string, url — command is issued by this user
  - `created_on` string, date-time — Timestamp of command request
  - `status` EsperCloudApiV0CommandRequestStatus[] — Show current status of commands issued during this request
    - `state` string, uuid — Current State of command
    - `total` integer — No of commands currently in this state

## Other responses

- `400` — Bad request
- `401` — Authorization information is missing or invalid.
- `403` — Forbidden, no permission to perform this action.
- `500` — Internal server error

---

[API](https://skmtc.net/esper/apis/esper-api-reference.md) · [All operations](https://skmtc.net/esper/apis/esper-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/esper/esper-api-reference/revisions/e1f64cbb488e/schema)