Bulk device mode switch and app cache clear — Blueprints and API

Android

When you need to move a large fleet from Kiosk Mode to Multi-App Mode, or clear app cache across many devices at once, doing this device-by-device in the Esper Console is not practical. Blueprints handle bulk device mode changes through convergence, and the Esper REST API handles bulk cache clearing programmatically.

Why this happens

The Esper Console is designed for single-device or small-group actions. At scale, Blueprints act as the authoritative configuration source for all assigned devices — publishing a change to a blueprint and converging it pushes that change to every assigned device simultaneously. Cache clearing has no bulk UI control, so the REST API is the only supported path for fleet-wide execution.

What you need before starting

Access to the Esper Console with permission to edit Blueprints
Your enterprise ID — found in Company Settings
An API token — generated in API Key Management
The package name of the app whose cache you want to clear (for example, com.example.yourapp)

Part 1: Bulk switch device mode using Blueprints

Open the Esper Console and navigate to Blueprints.
Identify the blueprint assigned to your target devices. If only a subset of devices should change mode, move those devices to a dedicated blueprint first — every device assigned to the blueprint will receive this change.
Click Edit Blueprint on the target blueprint.
Locate the Device Mode section and change the setting from Kiosk Mode to Multi-App Mode.
Click Save, then click Publish to activate the updated blueprint.
Click Converge to push the configuration to all assigned devices. This triggers the Esper Agent on each device to apply the new mode immediately if the device is online. Offline devices will apply the change on their next check-in.
Navigate to Devices & Groups and confirm that the Device Mode column shows Multi-App Mode for your target devices.

Verify: Each affected device should display Multi-App Mode in Devices & Groups within a few minutes of convergence for online devices. Devices that were offline will update within a few minutes of reconnecting.

Part 2: Bulk clear app cache using the API

Collect your API credentials. In the Esper Console, go to Company Settings and copy your enterprise ID. Then go to API Key Management and copy your API token.
Retrieve your target device IDs. Send a GET request to list devices in your enterprise. Replace <tenant> and <enterprise_id> with your actual values.
```
GET https://<tenant>-api.esper.cloud/api/v0/enterprise/<enterprise_id>/devices/?limit=100
```
The response returns a list of device objects, each containing a id field — this is the device ID you will use in the next step. Use the limit and offset parameters to page through larger fleets.
Send the clear cache command to each device. For every target device ID, send the following POST request using curl, Postman, or a script:
```
POST https://<tenant>-api.esper.cloud/api/v0/enterprise/<enterprise_id>/devices/<device_id>/command/

Headers:
  Authorization: Bearer <your_api_token>
  Content-Type: application/json

Body:
{
  "command": "CLEAR_APP_DATA",
  "command_args": {
    "package_name": "com.example.yourapp"
  },
  "command_type": "DEVICE"
}
```
Replace <device_id> with each target device's ID and com.example.yourapp with the actual package name. To run this at scale, loop through your list of device IDs in a script and send one POST per device.
Review command results. In the Esper Console, go to Devices & Groups → [Device Name] → Activity Feed for any device to confirm the command status. A Success status confirms the cache was cleared. A Failed status will include an error detail — check this before retrying.

Verify: Each device targeted by the API command should show a Success status in the Activity Feed within a few minutes. If a device was offline when the command was sent, the command will execute once the device comes back online.

Important: CLEAR_APP_DATA clears data, not just cache

The CLEAR_APP_DATA command removes both the app cache and all app data, including stored user settings, login sessions, and local databases. Run this command against a non-production device first to confirm the impact on your specific app before deploying fleet-wide. Some OEM Android builds may also restrict this command — if you see consistent failures on a specific device model, review the error details in the Activity Feed for that device.

If this doesn't resolve it

If devices are not converging after a Blueprint publish, or if API commands are returning errors, collect the following before contacting support:

The blueprint name and the device IDs that are not responding
The exact error message or status shown in the Activity Feed
The full API response body for any failed command requests
The Android version and OEM model for affected devices

Contact Esper Support with these details for further assistance.

Still need help?

If you're unable to switch device modes or clear app cache using Blueprints or the API, submit a support ticket with details about which method you're using (Blueprints or API), the specific error messages you're encountering, and the device models affected.