HeadSpin Documentation

Device Cleaning API

Device Cleaning API cleans devices back to the default state by deleting user-installed third-party apps and shows the current state of device cleaning.

For android devices, the API also deletes user data saved in the Chrome browser. For desktop browsers the API does nothing since each browser is a new independent instance with no data saved from previous usage.

There are four device cleaning states:

  • <code class="dcode">dirty</code>: Device cleaning is requested and queued
  • <code class="dcode">in_progress</code>: Device cleaning is in progress
  • <code class="dcode">clean</code>: The device is cleaned
  • <code class="dcode">failed</code>: Failed to clean the device

API Reference

List device cleaning states

Clean devices

List device cleaning states

Route Method
/v0/device-cleaning GET


curl https://<your_api_token>@api-dev.headspin.io/v0/device-cleaning

Optional Parameters

  • <code class="dcode">/v0/device-cleaning?states=<device cleaning state>,...</code>: List devices in the given cleaning states.


A JSON object in the form of <code class="dcode">{"<device cleaning state>": [<device address>, ...], ...}</code> that has a list of device addresses.

An example:

  "dirty": [
  "in_progress": [...],
  "clean": [...],
  "failed": [...],

Clean Devices

Clean devices matching the given selector by deleting user-installed third-party apps and their user data.

Route Method
/v0/device-cleaning/{selector}/clean POST

Request Body

The request body must be an empty or contain a JSON object such as:

    "mobile_safari": true

Clean device options:

Key Name Description
mobile_safari If the request cleans mobile Safari data for iPhone and iPad. It is equivalent to cleaning Safari data via Clear History and Website Data. It may take 10 - 20 seconds to complete because it requires UI interactions. The cleanup may fail when the screen has system popup. Default false.


To clean all devices:

curl -X POST https://<your_api_token>@api-dev.headspin.io/v0/device-cleaning/*/clean

To clean a single device:

curl -X POST https://<your_api_token>@api-dev.headspin.io/v0/device-cleaning/device_id:2124d0e6+hostname:proxy-us-mv-1.headspin.io/clean


A JSON object:

<code class="dcode">{"failed": ["<device_address>"...], "success": [...]}</code>

  • If any devices are failed, status code 400 will be returned.


  • <code class="dcode">{"status": "Could not find any devices for the selector: '<selector>'", "status_code": 400}</code> if matching devices are not found.