API to get and filter command requests
ESPER API REFERENCE (1.0.0)
Welcome to Esper’s API documentation. The Esper API allows users to accomplish operations outside of the console. Some common uses for our APIs include observing device information and console activity, installing and updating apps, uploading files, and sending files to devices. Our users have also used the API to automate app updates, perform bulk actions, and more.
Esper API endpoints use REST-based architecture and return JSON responses.
See our documentation for:
You need to create an API Key to interact with our APIs. Learn more about generating an API Key. You can also learn more about Esper and sign up for an account at esper.io/signup.
Some endpoints also require an Enterprise ID. This ID can be found in the API Management section of the Esper console.
Responses may be paginated. Use the following parameters to query the data. A full list of parameters can be found on the endpoint’s documentation page.
| Parameter | Data Type | Explanation |
|---|---|---|
| limit | integer | Limit the data returned. Default = 20. |
| offset | integer | Offset to the first item returned. Default = 0. |
| ordering | string | Order the results set by the field name. Varies by endpoint. |
| next | string | Paginate to the next response set. |
| previous | string | Paginate to the last set response. |
We use standard HTTP status codes for success or failure. A typical error response may look something like this:
{
"errors": [],
"message": "error message",
"status": 400
}errors- List of error detailsmessage- Error descriptionstatus- HTTP status code
Some common status codes and messages are:
| Number | Message | Explanation |
|---|---|---|
| 200 | OK | The request succeeded. |
| 201 | Resource creation | A resource was created. |
| 401 | Unauthorized | The API key is invalid. |
| 404 | Not found | The resource was not found. |
| 429 | Rate limit exceeded | Too many requests. Wait a moment and try again. |
| 500 | Server error | Internal error. Wait a moment and try again. If the issue persists, contact Esper. |
See how our systems are doing by checking our status page.
To ensure quality of service for all customers, we enforce rate limits for API requests. Most customers won’t hit this limit with normal use. In case you experience 429 or rate limit exceeded errors, we recommend the following:
- Try sending requests in batches.
- Begin with about 20 requests at a time and building up from there.
- Ensure your scripts are efficient and don’t contain redundant calls.
- Reach out to your account manager to discuss your options.
Download OpenAPI description
Overview
Languages
Servers
Mock server
https://api.esper.io/_mock/openapi
https://{foo}-api.esper.cloud/api
- Mock serverhttps://api.esper.io/_mock/openapi/v0/enterprise/{enterprise_id}/command/
- https://develop-api.esper.cloud/api/v0/enterprise/{enterprise_id}/command/
curl -i -X GET \
'https://api.esper.io/_mock/openapi/v0/enterprise/{enterprise_id}/command/?command_type=string&devices=string&device_type=string&command=string&issued_by=string' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'Response
application/json
{ "count": 0, "next": "string", "previous": "string", "results": [ { … } ] }
Body*/*required
The request body to create a command for set of devices or groups
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"
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
* 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
* 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. ``` Enum"ADD_TO_WHITELIST""ADD_WIFI_AP""CLEAR_APP_DATA""INSTALL""LOCK""REBOOT""REMOVE_FROM_WHITELIST""REMOVE_WIFI_AP""SET_APP_PERMISSION""SET_APP_STATE"
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"
- Mock serverhttps://api.esper.io/_mock/openapi/v0/enterprise/{enterprise_id}/command/
- https://develop-api.esper.cloud/api/v0/enterprise/{enterprise_id}/command/
curl -i -X POST \
'https://api.esper.io/_mock/openapi/v0/enterprise/{enterprise_id}/command/' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: */*' \
-d '[object Object]'command request successfully created
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"
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
* 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
* 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. ``` Enum"ADD_TO_WHITELIST""ADD_WIFI_AP""CLEAR_APP_DATA""INSTALL""LOCK""REBOOT""REMOVE_FROM_WHITELIST""REMOVE_WIFI_AP""SET_APP_PERMISSION""SET_APP_STATE"
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"
Response
application/json
{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "enterprise": "796caaf9-a7de-4817-9ffa-39d04bf83de9", "command_type": "DEVICE", "devices": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "groups": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "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": {}, "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", "tag": "string", "video_quality": "string", "enable_debug_mode": false, "converge_with_provision_option": false, "auto_update_mode": "autoUpdateDefault", "content_id": "string" }, "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": [ … ] }, "issued_by": "string", "created_on": "2019-08-24T14:15:22Z", "status": [ { … } ] }
- Mock serverhttps://api.esper.io/_mock/openapi/v0/enterprise/{enterprise_id}/command/{request_id}/status/
- https://develop-api.esper.cloud/api/v0/enterprise/{enterprise_id}/command/{request_id}/status/
curl -i -X GET \
'https://api.esper.io/_mock/openapi/v0/enterprise/{enterprise_id}/command/{request_id}/status/?device=string&state=string' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'Response
application/json
{ "count": 0, "next": "string", "previous": "string", "results": [ { … } ] }