HeadSpin Documentation
Documentation

iOS Device API

Overview

HeadSpin provides a convenient REST API interface for idevice, a tool to natively communicate with iOS devices. HeadSpin allows you to run idevice commands through an API interface so you can easily target and perform actions on your iOS devices.

The prerequisite to using the HeadSpin API is an API token. You can create an API token from your user settings.

Base URL

All URLs referenced in the API documentation have the following base URL structure:


https://api-dev.headspin.io/v0/idevice/

Available parameters:

  • timeout: wait for devices until they come back online or timeout is reached (unit: second / default: 0.0)

Example:


curl https://<your_api_token>@api-dev.headspin.io/v0/idevice/{ios-device-id}/screenshot?timeout=60 -o ./my-screenshot.png

Your API token is passed in the request header as the Authorization Bearer. Here's an example of this expressed in Python, which you can use as a reference to adapt to your language of choice:


import requests

api_token = "<your_api_token>" # We pre-filled your API Token here
device_serial = "{ios-device-id}" # Replace this with the UDID for your target device 


def get_ios_device_app_list(api_token, udid):
    headers = {
        "Authorization": "Bearer {}".format(api_token)
    }

    request_url = "https://api-dev.headspin.io/v0/idevice/{}/installer/list?json".format(udid)
    r = requests.get(request_url, headers=headers)
    data = r.json()

    return data

To ensure data privacy, our REST API are served over HTTPS. For on-premise deployments your Base URL may vary based on your environment. Please reach out to your HeadSpin contact or support@headspin.io for your exact Base URL details.

Note: The examples in this guide will be expressed as cURL commands to make it easy to follow cross-platform and independent of programming language. For cURL commands we can use a convenient base URL syntax, where your API token is placed in the Base URL as such:


https://{your-api-token}@api-dev.headspin.io/v0/idevice/id

API Guide

This section will introduce how to use the HeadSpin iOS Device API through several examples:

  • Take a screenshot
  • Retrieve the iOS syslog
  • Install a provisioning profile
  • Install or uninstall an iOS app
  • Get a list of installed apps on a device

The examples cover popular use cases and explain how to use the API. The subsequent section will be a full reference of available iOS API.

Take a screenshot

API

You can take a screenshot of an iOS device by sending a GET request to the iOS Screenshot API. You can also specify an output path where the image can be stored on your client machine.


curl https://<your_api_token>@api-dev.headspin.io/v0/idevice/{device-udid}/screenshot

For example:


curl https://<your_api_token>@api-dev.headspin.io/v0/idevice/{ios-device-id}/screenshot -o ./my-screenshot.png

Retrieve the iOS syslog

API

Syslog is the iOS system logger that contains all of the log file data from an iOS device. Since there can be numerous syslog events on a given device, HeadSpin provides a convenient query string parameter to retrieve a certain number of lines.


curl https://<your_api_token>@api-dev.headspin.io/v0/idevice/{device-udid}/syslog?n={number-of-lines}

For example:


curl https://<your_api_token>@api-dev.headspin.io/v0/idevice/{ios-device-id}/syslog?n=50

Install a provisioning profile

API

Development builds of iOS apps have to be signed by Apple first before they can be installed on a given device. The first step is to install your provisioning profile on the device. A provisioning profile acts as a link between the device and the developer account. In your Apple Developer Account, you can select which devices can run your app with your provisioning profile. A provisioning profile must be installed on each device on which you wish to run your application code. HeadSpin provides API for installing your provisioning profile. As a prerequiste to using this API, download your iOS provisioning profile from your Apple Developer Account.


curl -X POST https://<your_api_token>@api-dev.headspin.io/v0/idevice/{device-udid}/provision/install --data-binary "@{your-provisioning-profile}"

For example:


curl -X POST https://<your_api_token>@api-dev.headspin.io/v0/idevice/{ios-device-id}/provision/install --data-binary "@/Users/example/myexample.mobileprovision"

Install or uninstall an iOS app

Install

API

To install a previously uploaded iOS app on a device, make a POST request with the app id.


curl -X POST https://<your_api_token>@api-dev.headspin.io/v1/app/{app_id}/install/{ios-device-id}

Uninstall

API

To uninstall a previously uploaded iOS app on a device, make a POST request with the app id.


curl -X POST https://<your_api_token>@api-dev.headspin.io/v1/app/{app_id}/uninstall/{ios-device-id}

Get a list of installed apps on a device

You can retrieve a list of installed apps on a given device using the following endpoint. Furthermore, there is a query string parameter to specify if you would like the response in JSON or in the native plist XML format.


curl https://<your_api_token>@api-dev.headspin.io/v0/idevice/{ios-device-id}/installer/list?{json-or-xml}

For example:


curl https://<your_api_token>@api-dev.headspin.io/v0/idevice/{ios-device-id}/installer/list?json

API Reference

List all iOS devices

Get a device's information

Install a provisioning profile

List all apps on a device

Install an app on a device by app ID

Uninstall an app from a device by app ID

Installing dSYMs with App Management

View a device's syslog

Get a screenshot from a device

Save a screenshot to the cloud

Restart a device

Lock a device

Unlock a device

Dismiss popups on a device

Using Pintap to solve PIN entry screen

List all iOS devices

Route Method
/v0/idevice/id GET

Example


curl https://<your_api_token>@api-dev.headspin.io/v0/idevice/id

Response

JSON object, each key is the address of a device. The address is in the form of <code class="dcode">{the iOS device's UDID (Unique Device Identifier)}@{host}</code>.


{
  "d138cc4ef3109179902444f33e5229ad68883db9@staging-us-mv-0-proxy-2.headspin.io": {
    "status": "device",
    "serial": "DNPQ2JDTG5MP",
    "os": "ios",
    "host": "staging-us-mv-0-proxy-2.headspin.io",
    "device_id": "d138cc4ef3109179902444f33e5229ad68883db9"
  },
  "ef472902906914b6edccff300852b92175c13622@staging-us-mv-0-proxy-3.headspin.io": {
    "status": "device",
    "serial": "F2LWK0B7JCLF",
    "os": "ios",
    "host": "staging-us-mv-0-proxy-3.headspin.io",
    "device_id": "ef472902906914b6edccff300852b92175c13622"
  }
}

Get a device's information

Route Method
/v0/idevice/{device_id}/info GET

Optional parameters

  • <code class="dcode">/{device_id}/info?json</code>: get the results in JSON
  • <code class="dcode">/{device_id}/info?flags=--xml</code>: get the results in XML

Example


curl https://<your_api_token>@api-dev.headspin.io/v0/idevice/{ios-device-id}/info

Response

By default, the response is in plaintext.

If the optional <code class="dcode">?json</code> parameter is used, the response is a JSON object that looks like the following:


{
  "BasebandVersion": "6.30.04",
  "EthernetAddress": "d0:25:98:31:1a:87",
  "UniqueDeviceID": "{ios-device-id}",
  "CPUArchitecture": "arm64",
  "PkHash": "5OQIGNymupBn16zMKPujMp3562XDnNFkULy+gshbERM=",
  "ChipID": 28672,
  "BasebandMasterKeyHash": "8CB15EE4C8002199070D9500BB8FB183B02713A5CA2A6B92DB5E75CE15536182",
  "SoftwareBehavior": "AQAAAAAAAAAAAAAAAAAAAA==",
  "ProximitySensorCalibration": "T00EAA0LODgQA7wCsATMALwC/AACAMoQ9gMCALqr+gLuAl8AKQKnASvI/xoAAAAA4QCVAAQCAADrAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
  "SIMStatus": "kCTSIMSupportSIMStatusNotInserted",
  "ModelNumber": "MG4H2",
  "DeviceColor": "#e1e4e3",
  "ProductType": "iPhone7,2",
  "TimeZone": "Asia/Jakarta",
  "BasebandKeyHashInformation": {
    "SKeyHash": "u+/tcCwvaQ+1Y9t40I4yegCEmB28mALlaROhaIVGBWo=",
    "SKeyStatus": 0,
    "AKeyStatus": 2
  },
  "FirstFreePairExpired": true,
  "BluetoothAddress": "d0:25:98:31:1a:86",
  "BrickState": false,
  "DeviceName": "Proxy Box’s iPhone",
  "kCTPostponementStatus": "kCTPostponementStatusActivated",
  "TrustedHostAttached": true,
  "HasSiDP": true,
  "TimeZoneOffsetFromUTC": 25200,
  "UseRaptorCerts": true,
  "CarrierBundleInfoArray": [],
  "MobileSubscriberNetworkCode": "",
  "HardwarePlatform": "t7000",
  "RegionInfo": "PA/A",
  "SBLockdownEverRegisteredKey": true,
  "BasebandChipID": 8343777,
  "kCTPostponementInfoServiceProvisioningState": false,
  "MLBSerialNumber": "C07519507F3FQJYF",
  "HardwareModel": "N61AP",
  "BasebandRegionSKU": "BQAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
  "BasebandActivationTicketVersion": "V2",
  "FirmwareVersion": "iBoot-4076.30.43",
  "DeviceClass": "iPhone",
  "kCTPostponementInfoPRLName": 0,
  "PasswordProtected": false,
  "SerialNumber": "C39PP04BG5MT",
  "UniqueChipID": 599087876023334,
  "TelephonyCapability": true,
  "BoardId": 6,
  "ProtocolVersion": "2",
  "FusingStatus": 3,
  "BasebandCertId": 3840149528,
  "ActivationState": "Activated",
  "WiFiAddress": "d0:25:98:31:1a:85",
  "ChipSerialNo": "FC4T9A==",
  "ProductVersion": "11.2",
  "BasebandStatus": "BBInfoAvailable",
  "kCTPostponementInfoPRIVersion": "0.0.0",
  "ProductionSOC": true,
  "ActivationStateAcknowledged": true,
  "MobileEquipmentIdentifier": "35928606708121",
  "BasebandSerialNumber": "FC4T9A==",
  "HostAttached": true,
  "CertID": 3840149528,
  "SoftwareBundleVersion": "",
  "TimeIntervalSince1970": 1553106896.753065,
  "SIMTrayStatus": "kCTSIMSupportSIMTrayInsertedNoSIM",
  "ProductName": "iPhone OS",
  "BuildVersion": "15C114",
  "SupportedDeviceFamilies": [
    1
  ],
  "InternationalMobileEquipmentIdentity": "359286067081218",
  "WirelessBoardSerialNumber": "F417CE336DC",
  "Uses24HourClock": false,
  "DieID": 599087876023334,
  "MobileSubscriberCountryCode": "",
  "PartitionType": "GUID_partition_scheme",
  "NonVolatileRAM": {
    "com.apple.System.tz0-size": "MHhDMDAwMDA=",
    "auto-boot": "dHJ1ZQ==",
    "backlight-level": "MTU0MA==",
    "boot-args": ""
  }
}

If the optional <code class="dcode">?flags=--xml</code> parameter is used, the response is instead an XML object that looks like the following:


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>ActivationState</key>
    <string>Activated</string>
    <key>ActivationStateAcknowledged</key>
    <true/>
    <key>BasebandActivationTicketVersion</key>
    <string>V2</string>
    <key>BasebandCertId</key>
    <integer>3840149528</integer>
    <key>BasebandChipID</key>
    <integer>8343777</integer>
    <key>BasebandKeyHashInformation</key>
    <dict>
        <key>AKeyStatus</key>
        <integer>2</integer>
        <key>SKeyHash</key>
        <data>
        u+/tcCwvaQ+1Y9t40I4yegCEmB28mALlaROhaIVGBWo=
        </data>
        <key>SKeyStatus</key>
        <integer>0</integer>
    </dict>
    <key>BasebandMasterKeyHash</key>
    <string>8CB15EE4C8002199070D9500BB8FB183B02713A5CA2A6B92DB5E75CE15536182</string>
    <key>BasebandRegionSKU</key>
    <data>
    BQAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
    AAAAAAAAAAAAAAAAAA==
    </data>
    <key>BasebandSerialNumber</key>
    <data>
    FC4T9A==
    </data>
    <key>BasebandStatus</key>
    <string>BBInfoAvailable</string>
    <key>BasebandVersion</key>
    <string>6.30.04</string>
    <key>BluetoothAddress</key>
    <string>d0:25:98:31:1a:86</string>
    <key>BoardId</key>
    <integer>6</integer>
    <key>BrickState</key>
    <false/>
    <key>BuildVersion</key>
    <string>15C114</string>
    <key>CPUArchitecture</key>
    <string>arm64</string>
    <key>CarrierBundleInfoArray</key>
    <array>
    </array>
    <key>CertID</key>
    <integer>3840149528</integer>
    <key>ChipID</key>
    <integer>28672</integer>
    <key>ChipSerialNo</key>
    <data>
    FC4T9A==
    </data>
    <key>DeviceClass</key>
    <string>iPhone</string>
    <key>DeviceColor</key>
    <string>#e1e4e3</string>
    <key>DeviceName</key>
    <string>Proxy Box’s iPhone</string>
    <key>DieID</key>
    <integer>599087876023334</integer>
    <key>EthernetAddress</key>
    <string>d0:25:98:31:1a:87</string>
    <key>FirmwareVersion</key>
    <string>iBoot-4076.30.43</string>
    <key>FirstFreePairExpired</key>
    <true/>
    <key>FusingStatus</key>
    <integer>3</integer>
    <key>HardwareModel</key>
    <string>N61AP</string>
    <key>HardwarePlatform</key>
    <string>t7000</string>
    <key>HasSiDP</key>
    <true/>
    <key>HostAttached</key>
    <true/>
    <key>InternationalMobileEquipmentIdentity</key>
    <string>359286067081218</string>
    <key>MLBSerialNumber</key>
    <string>C07519507F3FQJYF</string>
    <key>MobileEquipmentIdentifier</key>
    <string>35928606708121</string>
    <key>MobileSubscriberCountryCode</key>
    <string></string>
    <key>MobileSubscriberNetworkCode</key>
    <string></string>
    <key>ModelNumber</key>
    <string>MG4H2</string>
    <key>NonVolatileRAM</key>
    <dict>
        <key>auto-boot</key>
        <data>
        dHJ1ZQ==
        </data>
        <key>backlight-level</key>
        <data>
        MTU0MA==
        </data>
        <key>boot-args</key>
        <string></string>
        <key>com.apple.System.tz0-size</key>
        <data>
        MHhDMDAwMDA=
        </data>
    </dict>
    <key>PartitionType</key>
    <string>GUID_partition_scheme</string>
    <key>PasswordProtected</key>
    <false/>
    <key>PkHash</key>
    <data>
    5OQIGNymupBn16zMKPujMp3562XDnNFkULy+gshbERM=
    </data>
    <key>ProductName</key>
    <string>iPhone OS</string>
    <key>ProductType</key>
    <string>iPhone7,2</string>
    <key>ProductVersion</key>
    <string>11.2</string>
    <key>ProductionSOC</key>
    <true/>
    <key>ProtocolVersion</key>
    <string>2</string>
    <key>ProximitySensorCalibration</key>
    <data>
    T00EAA0LODgQA7wCsATMALwC/AACAMoQ9gMCALqr+gLuAl8AKQKnASvI/xoAAAAA4QCV
    AAQCAADrAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
    AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
    </data>
    <key>RegionInfo</key>
    <string>PA/A</string>
    <key>SBLockdownEverRegisteredKey</key>
    <true/>
    <key>SIMStatus</key>
    <string>kCTSIMSupportSIMStatusNotInserted</string>
    <key>SIMTrayStatus</key>
    <string>kCTSIMSupportSIMTrayInsertedNoSIM</string>
    <key>SerialNumber</key>
    <string>C39PP04BG5MT</string>
    <key>SoftwareBehavior</key>
    <data>
    AQAAAAAAAAAAAAAAAAAAAA==
    </data>
    <key>SoftwareBundleVersion</key>
    <string></string>
    <key>SupportedDeviceFamilies</key>
    <array>
        <integer>1</integer>
    </array>
    <key>TelephonyCapability</key>
    <true/>
    <key>TimeIntervalSince1970</key>
    <real>1553107066.929317</real>
    <key>TimeZone</key>
    <string>Asia/Jakarta</string>
    <key>TimeZoneOffsetFromUTC</key>
    <real>25200.000000</real>
    <key>TrustedHostAttached</key>
    <true/>
    <key>UniqueChipID</key>
    <integer>599087876023334</integer>
    <key>UniqueDeviceID</key>
    <string>{ios-device-id}</string>
    <key>UseRaptorCerts</key>
    <true/>
    <key>Uses24HourClock</key>
    <false/>
    <key>WiFiAddress</key>
    <string>d0:25:98:31:1a:85</string>
    <key>WirelessBoardSerialNumber</key>
    <string>F417CE336DC</string>
    <key>kCTPostponementInfoPRIVersion</key>
    <string>0.0.0</string>
    <key>kCTPostponementInfoPRLName</key>
    <integer>0</integer>
    <key>kCTPostponementInfoServiceProvisioningState</key>
    <false/>
    <key>kCTPostponementStatus</key>
    <string>kCTPostponementStatusActivated</string>
</dict>
</plist>

Install a provisioning profile

A provisioning profile ties your developer team to the devices your team uses for development and testing. If your app is not signed and distributed, you sometimes have to install your provisioning profile on a device before you can install your app on that device to test.

Route Method
/v0/idevice/{device_id}/provision/install POST

Request Body

The request's body should include the content of your <code class="dcode">.mobileprovision</code> file. To include the binary in your <code class="dcode">curl</code> request, use the <code class="dcode">--data-binary <file_name></code> flag.

See Apple's guide for more information on your provisioning profile.

Example


curl -X POST https://<your_api_token>@api-dev.headspin.io/v0/idevice/{ios-device-id}/provision/install -H "Content-type: text/plain" --data-binary provisioning_profile

Response

  • <code class="dcode">HTTP response: 400, missing mobile provision data</code> if the provisioning data is not included in the body.

List all apps on a device

Route Method
/v0/idevice/{device_id}/installer/list GET

Optional Parameters

  • <code class="dcode">{device_id}/installer/list?json</code>: get the results in JSON
  • <code class="dcode">/{device_id}/installer/list?flags=--xml</code>: get the results in XML

Example


curl https://<your_api_token>@api-dev.headspin.io/v0/idevice/{ios-device-id}/installer/list

Response

The response is a plaintext document in CSV format that looks like the following:


CFBundleIdentifier, CFBundleVersion, CFBundleDisplayName
com.apple.itunesu, "2488", "iTunes U"
com.apple.Pages, "6091", "Pages"
com.apple.Numbers, "6091", "Numbers"
com.apple.Keynote, "6091", "Keynote"
io.headspin.masterhand.app, "15", "masterhand"
com.apple.iMovie, "4147.7.82", "iMovie"
com.apple.test.WebDriverAgentRunner-Runner, "1", "WebDriverAgentRunner-Runner"
com.apple.mobilegarageband, "4878.17", "GarageBand"

If the optional <code class="dcode">?json</code> parameter is used, the response is a JSON object that looks like the following:


{
  "data": [
    {
      "DTPlatformVersion": "12.1",
      "UIRequiresFullScreen": true,
      "CFBundleNumericVersion": 0,
      "Container": "/private/var/mobile/Containers/Data/Application/42A0FFC4-973F-4692-902B-D42C23CF9B2B",
      "ParallelPlaceholderPath": true,
      "CFBundleIcons": {
        "CFBundlePrimaryIcon": {
          "CFBundleIconName": "AppIcon",
          "CFBundleIconFiles": [
            "AppIcon29x29",
            "AppIcon40x40",
            "AppIcon60x60"
          ]
        }
      },
      "ApplicationDSID": 8434493456,
      "CFBundleInfoDictionaryVersion": "6.0",
      "UIBackgroundStyle": "UIBackgroundStyleTransparent",
      "DTXcodeBuild": "10B61",
      "EnvironmentVariables": {
        "HOME": "/private/var/mobile/Containers/Data/Application/42A0FFC4-973F-4692-902B-D42C23CF9B2B",
        "CFFIXED_USER_HOME": "/private/var/mobile/Containers/Data/Application/42A0FFC4-973F-4692-902B-D42C23CF9B2B",
        "TMPDIR": "/private/var/mobile/Containers/Data/Application/42A0FFC4-973F-4692-902B-D42C23CF9B2B/tmp"
      },
      "CFBundleSupportedPlatforms": [
        "iPhoneOS"
      ],
      "CFBundleIdentifier": "com.apple.itunesu",
      "CFBundleDocumentTypes": [
        {
          "CFBundleTypeIconFiles": [
            "mat-thumb_ipad_pdf"
          ],
          "CFBundleTypeName": "PDF",
          "LSItemContentTypes": [
            "com.adobe.pdf"
          ],
          "LSHandlerRank": "Alternate"
        },
        {
          "CFBundleTypeName": "Keynote",
          "LSItemContentTypes": [
            "com.apple.keynote.key",
            "com.apple.iwork.keynote.key"
          ],
          "LSHandlerRank": "Alternate"
        },
        {
          "CFBundleTypeName": "Pages",
          "LSItemContentTypes": [
            "com.apple.pages.pages",
            "com.apple.iwork.pages.pages"
          ],
          "LSHandlerRank": "Alternate"
        },
       ....
       ....
       ....
  ]
}

If the optional <code class="dcode">?flags=--xml</code> parameter is used, the response is an XML object with the same content.

Install an app on a device by app ID

Route Method
/v1/app/{app_id}/install/{device_id} POST

Note

This command is a part of our App Management API. For more information and additional API command sets, please navigate to the link above. App Management API is consistent across all platforms, so this command will work for XAPK as well as APK and IPA files.

Automated Signing

Your IPA will be signed by us to ensure that it can install on the target device. If you would like to manage signing yourself, register the device UDID in your Apple Developer Account and add the device to a provisioning profile. An IPA provisioned for the target device will disable automated signing but you can explicitly disable it with the optional ?sign=false parameter. Automated signing does not support app capabilities.

Apps provisioned with an Enterprise profile are not subject to deployment restrictions and therefore HeadSpin disables Automated Signing for these apps. If an app requires features that are only available with non-Enterprise profiles, please select an alternative distribution method in Xcode when exporting the IPA, such as Ad Hoc or Development. This will allow Automated Signing to manage signing as expected.

Optional Parameters

  • <code class="dcode">/v1/app/{app_id}/install/{device_id}?sign=false</code>: disable Automated Signing. iOS only, see above for signing documentation.

Example

Install a previously uploaded app:


curl -X POST https://<your_api_token>@api-dev.headspin.io/v1/app/{app_id}/install/{ios-device-id}

Uninstall an app from a device by app ID

Route Method
/v1/app/{app_id}/uninstall/{device_id} POST

Note

This command is a part of our App Management API. For more information and additional API command sets, please navigate to the link above. App Management API is consistent across all platforms, so this command will work for XAPK as well as APK and IPA files.

Example


curl -X POST https://<your_api_token>@api-dev.headspin.io/v1/app/{app_id}/uninstall/{ios-device-id}

Installing dSYMs with App Management

In order to upload dSYMs, use the 'upload additional app file' method available in App Management.

Package your dSYMs

When you archive your app in Xcode to export an IPA, Xcode will generate Debug Symbol files (dSYMs) for that build. You should be able to find your archive in Xcode's Organizer (right-click it and select Show in Finder, then right-click the .xcarchive itself to Show Package Contents.) Right-click the dSYMs directory and select Compress "dSYMs" or do so via the command line with zip -r dSYMs.zip dSYMs. A debuggable IPA and matching debug symbols are required to generate a Function Call Timeline for a given app. If not using the Automated Signing feature, you must sign the app with an iOS App Development profile.

View a device's syslog

Streams the content of the connected device's syslog.

Route Method
/v0/idevice/{device_id}/syslog GET

Optional Parameters

  • <code class="dcode">{device_id}/syslog?n={lines back}</code>: Instead of streaming, retrieve only the last 'n' lines from the device's syslog. For example, <code class="dcode">/syslog?n=30</code> retrieves the last 30 lines.

Example


curl https://<your_api_token>@api-dev.headspin.io/v0/idevice/{ios-device-id}/syslog

Response

The device's syslog is sent to the requesting user in <code class="dcode">text/plain</code>. The content is streamed and sent in chunks.

Get a screenshot from a device

Capture a screenshot of the device's current screen in PNG format.

Route Method
/v0/idevice/{device_id}/screenshot GET

Optional Parameters

  • To save the captured screenshot as an image, append <code class="dcode">> {local path}/{filename}.png</code> to the end of the command.

Example


curl https://<your_api_token>@api-dev.headspin.io/v0/idevice/{ios-device-id}/screenshot > test.png

Response

An <code class="dcode">image/png</code> object.

Save a screenshot to the cloud

Similar to the <code class="dcode">.../screenshot</code> route explained above, the <code class="dcode">.../screenshot_url</code> route will take a screenshot in PNG format, but additionally the screenshot will be uploaded to the HeadSpin services. The result of the <code class="dcode">.../screenshot_url</code> route is another URL that can be used to retrieve the uploaded screenshot. Note that the URL returned from this API is only valid for 24 hours.

Route Method
/v0/idevice/{device_id}/screenshot_url GET

Example


curl https://<your_api_token>@api-dev.headspin.io/v0/idevice/{ios-device-id}/screenshot_url
  https://another-url...

curl https://another-url... -o ./my-screenshot.png

Response

A URL.

Restart a device

Route Method
/v0/idevice/{device_id}/diagnostics/restart POST

Example


curl -X POST https://<your_api_token>@api-dev.headspin.io/v0/idevice/{ios-device-id}/diagnostics/restart

Response

A JSON object.

  • <code class="dcode">{"status": 0, "returncode": 0, "stdout": "Restarting device.\n", "summary": "ok"}</code> if the device is restarted successfully.

Lock a device

Route Method
/v0/idevice/{device_id}/lock POST

Example


curl -X POST https://<your_api_token>@api-dev.headspin.io/v0/idevice/{ios-device-id}/lock

Optional Parameters

  • <code class="dcode">{device_id}/lock/?timeout={timeout seconds}</code>: If the locking attempt fails, the server will keep retrying until the <code class="dcode">timeout seconds</code> have elapsed. If there's no <code class="dcode">?timeout</code> parameter, or <code class="dcode">timeout seconds</code> is <code class="dcode">0</code>, then this returns immediately after the first attempt to lock.
  • <code class="dcode">{device_id}/lock/?idleTimeout={timeout seconds}</code>: Unlock automatically if the device is inactive for <code class="dcode">timeout seconds</code>.

Response

JSON object:

  • <code class="dcode">{"status": 0, "message": "<device_address> locked."}</code> if the lock attempt was successful.
  • <code class="dcode">{"status": 1, "message": "Did not lock."}</code> if the lock attempt was unsuccessful. The device might be locked by another user.

Notes

  • This route is incompatible with the reservation system. If your company is using the reservation system, use the <code class="dcode">/v0/devices/</code> route instead.

Unlock a device

Unlocks a targeted device in the platform, if the lock is owned by the requesting user.

Route Method
/v0/idevice/{device_id}/unlock POST

Example


curl -X POST https://<your_api_token>@api-dev.headspin.io/v0/idevice/{ios-device-id}/unlock

Response

JSON object:

  • <code class="dcode">{"status": 0, "message": "<device_address> unlocked."}</code> if the unlock attempt was successful.
  • <code class="dcode">{"status": 1, "message": "Did not unlock."}</code> if the unlock attempt was unsuccessful. The device might not be locked by the requesting user.

Dismiss pop-ups on a device

Dismiss pop-ups on the device. If there are no pop-ups, it does nothing.

If the device isn't already locked by the requesting user, calling this API route will lock the device. If the device is locked by someone else, this route will not work.

Note that some pop-ups prevent XCTest from starting on the device, resulting in xcodebuild waiting for the pop-up to be dismissed. Call this before running XCTest to ensure reliable startup.

Route Method
/v0/idevice/{device_id}/poptap POST

Example


curl -X POST https://<your_api_token>@api-dev.headspin.io/v0/idevice/{ios-device-id}/poptap

Response

  • <code class="dcode">{"status": 0, "message": "Poptap success", "value": {"success": true}}</code> if existing pop-ups was dismissed successfully.

Using Pintap to solve PIN entry screen

Uses Pintap to enter a code to solve the PIN entry screen. This performs the same actions as Pintap in Remote Control UI.

Route Method
/v0/idevice/{device_id}@{host}/pintap POST

Optional Parameters

The PIN code can be specified by including a JSON object as the request body.

Key Name Description
pin The PIN code to use with Pintap (optional).

Example


curl https://<your_api_token>@api-dev.headspin.io/v0/idevice/{ios-device-id}@{host}/pintap

curl https://<your_api_token>@api-dev.headspin.io/v0/idevice/{ios-device-id}@{host}/pintap -d '{"pin":"1234"}'

Response

The server will reply after Pintap has finished execution, which may take several seconds, or when there is an issue.

  • <code class="dcode">HTTP 200</code> when Pintap finishes execution.
  • <code class="dcode">HTTP 400</code> if there was a problem with the request.
  • <code class="dcode">HTTP 404</code> if no eligible device matches the requested device address.
  • <code class="dcode">HTTP 500</code> if Pintap encounters an error.

Multiple Device Access

A limited set of commands are available to run across multiple devices in parallel. The commands accept an address pattern called a selector, that follows the standard selector syntax used throughout the platform. The selector syntax runs on each device object and matches the fields in the device object.

Read more about selectors in the selectors doc.

The emtpy selector matches all devices.

API Reference

Get all devices matching a selector

Route Method
/v0/idevicem/{selector}/id GET

Example


curl https://<your_api_token>@api-dev.headspin.io/v0/idevicem/os:ios/id

Response

A JSON object, with each key being a device address matching the selector.


{
  "049456f85e142e8dfd7ada8aebc068480dcc47ac@proxy-us-nyc-6.headspin.io": {
    "status": "device",
    "host": "proxy-us-nyc-6.headspin.io",
    "serial": "F2LW41BTHFM2",
    "os": "ios",
    "present": "True",
    "device_id": "049456f85e142e8dfd7ada8aebc068480dcc47ac"
  },
  "d9e562b48b9388b4eb24d56ab88a8ab68c3202b9@proxy-gb-lhr-0.headspin.io": {
    "status": "device",
    "host": "proxy-gb-lhr-0.headspin.io",
    "serial": "C39S20DVH2XK",
    "os": "ios",
    "present": "True",
    "device_id": "d9e562b48b9388b4eb24d56ab88a8ab68c3202b9"
  }
}