# List command requests

API to get and filter command requests

Endpoint: GET /commands/v0/commands/
Version: 1.0.0
Security: apiKey

## Query parameters:

  - `devices` (string)
    Filter by device IDs. Accepts comma separated values.

  - `groups` (string)
    Filter by group IDs. Accepts comma separated values.

  - `command` (string)
    Filter by command name

  - `schedule` (string)
    Filter by schedule type
    Enum: "IMMEDIATE", "WINDOW", "RECURRING"

  - `exclude_internal_commands` (boolean)
    Filter to exclude internal commands

  - `limit` (number)

  - `offset` (number)

## Response 200 fields (application/json):

  - `code` (integer)

  - `message` (string)

  - `content` (object)

  - `content.count` (integer)

  - `content.previous` (string)

  - `content.next` (string)

  - `content.results` (array)

  - `content.results.id` (string)
    Unique command request identifier

  - `content.results.command_type` (string)
    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"

  - `content.results.devices` (array)
    list of devices to run commands

  - `content.results.groups` (array)
    list of groups to run commands

  - `content.results.device_type` (string)
    Filtering by device_type is not supported currently and applies to 'all' devices. If 'active' or 'inactive' is specified, it will be ignored.
    Enum: "active", "inactive", "all"

  - `content.results.command` (string)
    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
* 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
* 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

* 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.
    Enum: "ADD_TO_WHITELIST", "ADD_WIFI_AP", "APPLY_APP_CONFIG", "CLEAR_APP_DATA", "CONVERGE", "INSTALL", "INSTALL_CERTIFICATE", "LIST_INSTALLED_PROFILES", "LOCK", "REBOOT", "REMOVE_FROM_WHITELIST", "REMOVE_PROFILE", "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_MULTI_APP_MODE", "SET_NEW_POLICY", "SET_ROTATION_STATE", "SET_SCREEN_OFF_TIMEOUT", "SET_STREAM_VOLUME", "SET_TIMEZONE", "SET_WIFI_STATE", "UNINSTALL", "UNINSTALL_CERTIFICATE", "UPDATE_DEVICE_CONFIG", "UPDATE_HEARTBEAT", "UPDATE_LATEST_DPC", "WIPE", "RESET_LOCKSCREEN_PASSWORD", "UPDATE_BLUEPRINT", "NOTIFY_DEVICE", "SET_DEVICE_LANGUAGE", "SET_ETHERNET_SETTINGS", "SET_STATIC_IP", "BEEP_DEVICE", "SET_APP_NOTIFICATIONS", "USE_ONLY_SAVED_WIFI_AP", "DEVICE_INFORMATION", "VPP_APP_INSTALL", "APPLE_APP_UNINSTALL", "CLEAR_PASSCODE", "INSTALL_PROFILE", "RUN_SHELL_SCRIPT", "RUN_CUSTOM_ACTION", "COLLECT_LOGS"

  - `content.results.command_args` (object)

  - `content.results.command_args.device_alias_name` (string)
    Alternate human-readable name for your Device

  - `content.results.command_args.custom_settings_config` (object)
    Managed configurations for your device (passed as JSON object)

  - `content.results.command_args.app_version` (string)
    The version id of app uploaded on Esper

  - `content.results.command_args.package_name` (string)
    The app package name uploaded on Esper

  - `content.results.command_args.policy_url` (string)
    The URL to the policy

  - `content.results.command_args.wifi_access_points` (object)
    Wifi access points for the device (passed as JSON object)

  - `content.results.command_args.state` (string)
    LOCKED/UNLOCKED

  - `content.results.command_args.message` (string)
    Message to be added with command to notify device.

  - `content.results.command_args.title` (string)
    Message title  to be added with command to notify device.

  - `content.results.command_args.url` (string)
    (Optional) Link to notify device.

  - `content.results.command_args.app_state` (string)
    The state of app - SHOW/HIDE/DISABLE/LAUNCHABLE_BUT_HIDDEN

  - `content.results.command_args.bluetooth_state` (boolean)
    The state of bluetooth - ON/OFF

  - `content.results.command_args.brightness_value` (integer)
    The brightness value of a device(1-100)

  - `content.results.command_args.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)

  - `content.results.command_args.rotate_state` (integer)
    The screen orientation of a device. Should be either 0, 1 or 2 (0 = AUTO, 1 = PORTRAIT_ONLY, 2 = LANDSCAPE_ONLY)

  - `content.results.command_args.screen_off_timeout` (integer)
    The value for screen timeout of a device. Should be either -1 or between 5000 and 1800000

  - `content.results.command_args.stream` (integer)
    The value of the volume stream. Should be either 0(Ring), 1(Notification), 2(Alarm) or 3(Music)

  - `content.results.command_args.volume_level` (integer)
    The level of volume. Should be a value from 0 to 100

  - `content.results.command_args.timezone_string` (integer)
    The timezone of a device. Should be a valid timezone string

  - `content.results.command_args.wifi_state` (boolean)
    The state of WIFI - ON/OFF

  - `content.results.command_args.wifi_revert_timeout` (integer)
    The WIFI revert timeout. Should be greater than or equal to 1

  - `content.results.command_args.locale` (string)
    Language and country code in xx[_Zzzz]_yy where xx is language code, Zzzz is script (optional) and yy is country code.

  - `content.results.command_args.ethernet_auth_mode` (string)
    Chosen mode of authentication
    Enum: "NONE", "EAP_TLS"

  - `content.results.command_args.ethernet_ca_cert_alias` (string)
    CA certificate alias. It is mandatory with Auth Mode EAP_TLS

  - `content.results.command_args.ethernet_client_cert_alias` (string)
    Client certificate alias. It is mandatory with Auth Mode EAP_TLS

  - `content.results.command_args.ethernet_eap_identity` (string)
    EAP identity

  - `content.results.command_args.interface` (string)
    The network interface of the device - wlan/eth

  - `content.results.command_args.dhcp_enabled` (string)
    The dhcp state on the device - true/false

  - `content.results.command_args.static_ip` (string)
    The static ip to set on the device. Should be a valid ipv4

  - `content.results.command_args.primary_dns` (string)
    The primary dns to set on the device. Should be a valid ipv4

  - `content.results.command_args.subnet_mask` (string)
    The subnet mask set on the device. Should between 1-32 both inclusive

  - `content.results.command_args.secondary_dns` (string)
    The secondary dns to set on the device. Should be a valid ipv4

  - `content.results.command_args.gateway` (string)
    The gateway to set on the device. Should be a valid ipv4

  - `content.results.command_args.duration` (string)
    The beep duration specified in seconds. Value must be between 10 and 300, both inclusive.

  - `content.results.command_args.video_quality` (string)
    The video quality of the respective Remote Viewer session. Options are "LOW", "MEDIUM" and "HIGH".

  - `content.results.command_args.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.

  - `content.results.command_args.app_id` (string)
    The unique identifier for VPP application in Apple’s ecosystem

  - `content.results.command_args.bundle_identifier` (string)
    The unique identifier for an application in Apple’s ecosystem

  - `content.results.command_args.managed_only` (boolean)
    If true, list outs only the profiles that was installed via MDM.

  - `content.results.command_args.profile_identifier` (string)
    The identifier of the profile to remove.

  - `content.results.command_args.profile` (string)
    Base 64 encoded profile plist to be installed on the device.

  - `content.results.command_args.is_converge` (boolean)
    This value indicates that the command belongs to a converge action.

  - `content.results.command_args.script` (string)
    A complete shell script to execute on Linux or Windows devices.

  - `content.results.command_args.interpreter` (string)
    Type of interpreter to use for executing the script. e.g. For Linux use bash, zsh, or sh. For Windows use powershell. This field is mandatory.

  - `content.results.command_args.execute_as` (string)
    User to execute the script as root or Esper (default user) - Optional, default is Esper if not specified. Supports Linux devices.

  - `content.results.command_args.cert_file_type` (string)
    Certificate file type. Currently file type of "pkcs12" is supported

  - `content.results.command_args.cert_data_base64` (string)
    Base64 encoded content of the certificate file

  - `content.results.command_args.cert_alias_name` (string)
    Alias name of the certificate to be used during installation or uninstallation

  - `content.results.command_args.cert_storage_type` (string)
    Refers to the keystore type to be used for certificate installation or uninstallation. Currently storage type of "system" is supported

  - `content.results.command_args.cert_password` (string)
    Provides the password if the pkcs12 file is password protected - Optional

  - `content.results.command_args.is_factory_reset` (boolean)
    If true, performs factory reset and unenrolls the device. If false, only unenrolls the device without wiping data. Required for WIPE command on Windows devices.

  - `content.results.schedule` (string)
    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"

  - `content.results.schedule_args` (object)

  - `content.results.schedule_args.name` (string)

  - `content.results.schedule_args.start_datetime` (string)

  - `content.results.schedule_args.end_datetime` (string)

  - `content.results.schedule_args.time_type` (string)
    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.
    Enum: "console", "device"

  - `content.results.schedule_args.window_start_time` (string)

  - `content.results.schedule_args.window_end_time` (string)

  - `content.results.schedule_args.days` (array)

  - `content.results.reason` (string)
    details briefing the reason for current command request processing stage

  - `content.results.created_by` (string)
    user id of the user

  - `content.results.created_at` (string)
    Timestamp of command request

## Response 401 fields (application/json):

  - `code` (integer, required)

  - `message` (string, required)

  - `content` (object)

## Response 500 fields (application/json):

  - `code` (integer, required)

  - `message` (string, required)

  - `content` (object)