Sign in

v1

latestOpenAPI 3.0.1Apache 2.02026-08-063494581.6 MB
device_Operations

Create a new Operation

Creates a new Dispatch operation to run a large fleet action, such as Converge, across a set of devices or groups in a single request.

Operations are built for scale — a single call can target device_ids directly or resolve a device_request query (for example matching on group_multi or state) into as many as tens of thousands of devices. The operation is queued immediately in the Created state and resolves asynchronously as Esper identifies the applicable devices and dispatches the command.

About Create Operation

Currently, operation_type supports CONVERGE and group-level app INSTALL and UNINSTALL, and INSTALL/UNINSTALL are immediate only. Unlike the Command Request API, which issues one command per device or group call, Operations are designed specifically for very large fleet actions and report a single aggregate status alongside individual per-device results. A created operation does not affect devices immediately; it queues the action, then resolves the target devices, then dispatches the command to each of them.

Key Fields / Request Body

operation_type — the action to run, currently CONVERGE, INSTALL, or UNINSTALL

schedule_type — IMMEDIATE to run right away or WINDOW to run within a scheduled window

operation_device_query — the device targeting payload; accepts a device_ids list or a device_request object with filters such as group_multi or state

arguments — operation-specific arguments, for example converge_with_provision for a Converge operation

Common Use Cases

Converging tens of thousands of devices onto an updated blueprint in a single request

Installing or uninstalling an app across every device in one or more groups

Re-driving a Converge operation for a targeted list of devices that failed a previous attempt

Best Practices

Batch very large device lists in operation_device_query rather than issuing many smaller operations, since Operations are built to scale to tens of thousands of devices per request

Capture the id returned in the response immediately, since it is required for every subsequent status check

Confirm devices are online and provisioned before including them in a Converge operation to avoid indefinite Dispatched or Processing states

Workflow

Determine the device_ids or device_request filters that define the target fleet

POST to this endpoint with the operation_type and operation_device_query

Capture the returned id as the Operation ID

Poll GET /v0/operations/{operationId}/ until the operation reaches Success or Failure

post/v0/operations/

Request body

operation_type'CONVERGE' | 'INSTALL' | 'UNINSTALL' | 'INSTALL_APP' | 'UNINSTALL_APP' | 'REBOOT' | 'LOCK' | 'SHUT_DOWN' | 'WIPE' | 'ADD_EMM_ACCOUNT' | 'ADD_OVERRIDE_APN' | 'ADD_WIFI_AP' | 'REMOVE_WIFI_AP' | 'UPDATE_WIFI_AP' | 'SET_ETHERNET_SETTINGS' | 'SET_STATIC_IP' | 'USE_ONLY_SAVED_WIFI_AP' | 'ADD_TO_WHITELIST' | 'REMOVE_FROM_WHITELIST' | 'ALLOW_BLUETOOTH' | 'ALLOW_CAMERA' | 'ALLOW_FACTORY_RESET' | 'ALLOW_UNENROLLMENT_FROM_DEVICE' | 'DEFER_OS_UPDATES' | 'PAUSE_OS_UPDATES' | 'SET_OS_UPDATE_POLICY' | 'APPLE_APP_UNINSTALL' | 'APPLY_APP_CONFIG' | 'CLEAR_APP_CACHE' | 'CLEAR_APP_DATA' | 'DIRECT_IOS_APP_INSTALL' | 'INSTALL_CERTIFICATE' | 'INSTALL_OTA' | 'NOTIFY_OTA' | 'REFRESH_APPLIST' | 'SET_APP_NOTIFICATIONS' | 'SET_APP_PERMISSION' | 'SET_APP_STATE' | 'SET_KIOSK_APP' | 'SET_MULTI_APP_MODE' | 'SET_NEW_POLICY' | 'SIMPLE_INSTALL' | 'SYNC_CONTENT' | 'UNINSTALL_CERTIFICATE' | 'VPP_APP_INSTALL' | 'INSTALL_PROFILE' | 'INSTALL_PROVISIONING_PROFILE' | 'INSTALL_WEBCLIP' | 'REMOVE_PROVISIONING_PROFILE' | 'UNINSTALL_WEBCLIP' | 'LIST_PROVISIONING_PROFILES' | 'BEEP_DEVICE' | 'CAPTURE_SCREENSHOT' | 'INITIATE_CONFERENCE_CALL' | 'INITIATE_OFFER' | 'NOTIFY_DEVICE' | 'NUDGE_DEVICE' | 'REQUEST_BUGREPORT' | 'REQUEST_DPCLOG' | 'DEPLOY_SYSTEM_OTA' | 'UPDATE_BLUEPRINT' | 'UPDATE_DEVICE_CONFIG' | 'UPDATE_OEM_CONFIG' | 'CLEAR_PASSCODE' | 'RESET_LOCKSCREEN_PASSWORD' | 'SET_ADB_STATE' | 'SET_DEVICE_LOCKDOWN_STATE' | 'DISABLE_LOST_MODE' | 'ENABLE_LOST_MODE' | 'LOST_MODE_DEVICE_LOCATION' | 'PLAY_LOST_MODE_SOUND' | 'SET_BLUETOOTH_STATE' | 'SET_BRIGHTNESS_SCALE' | 'SET_DEVICE_LANGUAGE' | 'SET_GEO_FENCE' | 'SET_GPS_STATE' | 'SET_LOCATION_SERVICE' | 'SET_ROTATION_STATE' | 'SET_SCREEN_OFF_TIMEOUT' | 'SET_STREAM_VOLUME' | 'SET_TIMEZONE' | 'SET_WALLPAPER' | 'SET_WIDGET' | 'SET_WIFI_STATE' | 'RUN_CSP_PAYLOAD' | 'SET_PFN' | 'COLLECT_LOGS' | 'REMOTE_CONNECTION' | 'REMOVE_AGENT' | 'REMOVE_DEVICE' | 'RUN_CUSTOM_ACTION' | 'RUN_SHELL_SCRIPT' | 'DECLARATIVE_MANAGEMENT' | 'APPLY_GEO_FENCE'
schedule_type'IMMEDIATE' | 'WINDOW'

Following Schedule types are supported

* IMMEDIATE: Schedule the command to execcute Immediately
* WINDOW: Schedule the command to execute within the given window
operation_device_queryobject

A flexible JSON object to define device properties and filters.

Response

Operation information for the Tenant