HeadSpin Documentation
Documentation

App Management

Overview

App Management is a set of features to store, inspect, and install apps on HeadSpin's cloud. This allows teams to collaborate and access a common set of apps, whether they're uploaded by a continuous integration server or by an individual developer. The goal is to centralize an organization's apps and unify interaction with those apps across all device platforms supported on HeadSpin. App interaction is primarily powered by the new Metadata Selector syntax which allows users to query for apps based on a set of defined metadata fields either derived from the apps themselves or defined by the user.

Table of Contents

1. Metadata Selectors

2. API Reference

Metadata Selectors

App Management maintains a set of metadata fields that are common to each supported device platform. This includes the app identifier, version number, and display name, which are defined by the app build, as well as user-provided metadata fields such as the release type, version control commit hash, and other information which contextualizes each build.

When an app is uploaded to HeadSpin, the system derives the build-defined information and combines it with information provided by the user in the form of a metadata JSON object, creating the complete metadata description of the build. The user is able to not only retrieve this metadata about a build but query and filter builds using the Metadata Selector syntax. Metadata Selectors either retrieve a list of app builds or the latest app build matching the provided metadata fields and perform actions such as metadata evaluation or app installation.

Selector keys

Selectors work by finding app builds matching any number of key : value pairs, such as <code class="dcode">os_type:ios</code> or <code class="dcode">app_identifier:io.headspin.ios.</code> The list of all metadata selector keys is available through the App Management API:


curl https://<your_api_token>@api-dev.headspin.io/v1/apps/keys

The complete list is also included below. Metadata fields are either app-derived at upload time or user-provided at either upload time or later updated using the <code class="dcode">/metadata</code> route.

Key Type Description Examples
app_id unique The UUID of an uploaded app. 90e6af71-c04d-47aa-ae07-c3260df6d5a7
app_identifier derived The app's dot-separated package name or bundle identifier. io.headspin.ios
app_name derived The app's display name. HeadSpin iOS
app_type derived The app's platform-specific type. ipa or apk
build_commit provided The version control commit hash. f1cbfa75e51dc739fbc5483364385a718925541d
build_timestamp provided The epoch time (in seconds) the build was created. 1661330831.006
build_type provided The build configuration. debug, release, production, ...
file_size derived The size of the build (in bytes). 9525531
os_minimum derived The minimum supported OS version of the build.¹ 12.0
os_type derived The app's target operating system. ios or android
region provided The app's target region. usa, mena, ...
release_type provided The release configuration. distribution, development, play-store, ...
tags provided Miscellaneous user data to help identify an upload. {"custom_field": "value", ...}
upload_timestamp derived The epoch time (in seconds) the build was uploaded. 1661337471.927
version_number derived The build's internal version number. 1
version_semantic derived The build's human-readable semantic version. 1.0.0
version_tag provided Description of a build. feature-branch, nightly
Notes

¹ Each operating system defines its own convention of a minimum OS or SDK version, while others may not use this convention at all. A <code class="dcode">null</code> value could mean that the operating system either does not presently use the convention, or the app build failed to make the value known, even if the underlying binary uses libraries that do in fact have some minimum OS/SDK dependency. In this case, HeadSpin treats a <code class="dcode">os_minimum</code> value of <code class="dcode">null</code> as install-at-your-own-risk and the user is responsible for installing the app on a device with the appropriate OS version.

Selectors as query parameters

Metadata selectors are defined in the API request URL as query parameters. The selector will find apps matching all provided <code class="dcode">key:value</code> pairs. There are several operators to combine the selector parameters, including <code class="dcode">and</code>, <code class="dcode">or</code>, and <code class="dcode">not</code>. A list of avaiable operators is provided below:

Operator Description Example Example Explanation
+ and os_type:ios+region:usa All iOS apps with region usa
, or region:usa,region:mena Apps with region usa or mena
!= not region:!=usa All apps except those with region usa
<, <=, >, >= comparisons upload_timestamp:>=1661337471+upload_timestamp:<1661817600 Apps uploaded between 08/24/22 10:37:51 am GMT (inclusive) and 08/30/22 (exclusive)

Below is an example of a metadata selector in an API call. This call returns the latest <code class="dcode">Android</code> app uploaded by your organization with a <code class="dcode">minSdkVersion</code> of <code class="dcode">21</code>:


curl 'https://<your_api_token>@api-dev.headspin.io/v1/apps/os_type:android+os_minimum:21/latest'

Wildcards in Selectors

Metadata selector values may use * wildcards for more flexible matching.

For example, this call returns the latest app uploaded by your organization with a semantic versioning major-minor version of 2.3:


curl 'https://<your_api_token>@api-dev.headspin.io/v1/apps/version_semantic:2.3.*/latest'

API Reference

General

Upload an app

List uploaded apps and their metadata

Get the most recently uploaded app

Get the following most recently uploaded apps

List the available Metadata Selector keys

Manage apps with Metadata Selectors

Install an app on a device by metadata selector

Uninstall an app from a device by metadata selector

List apps and their metadata matched by metadata selector

Get the most recently uploaded app matched by metadata selector

Get the following most recently uploaded apps matched by metadata selector

Update metadata for apps matched by metadata selector

Delete apps matched by metadata selector

Upload additional app file for apps matched by metadata selector

Get additional app file metadata for apps matched by metadata selector

Delete additional app file for apps matched by metadata selector

Manage apps by App ID

Install an app on a device by app ID

Uninstall an app from a device by app ID

Get app metadata by app ID

Update app metadata by app ID

Download an app by app ID

Delete an app by app ID

Upload additional app file by app ID

Get additional app file metadata by app ID

Delete additional app file by app ID

Legacy API

Please note that this App Management API structure is our latest API for management and tracking of applications; we strongly encourage all users to utilize this method for app management on HeadSpin. However, if it is absolutely necessary for systems compatibility, you can find the deprecated legacy App API here. If you are unsure which method you should use, we still encourage you to stick with this document's App Management API, but you are welcome to reach out to HeadSpin to discuss your specific API needs and goals.

Upload an app

Route Method
/v1/app/upload POST

Request Body

The request's body should be multipart/form-data that passes your app file and, optionally, a JSON object containing the metadata for your app. To perform a multipart request, use <code class="dcode">curl</code>'s optional flag <code class="dcode">-F app=@<path-to-app> -F metadata=<json-object></code>, for example<code class="dcode"> -F app="@/Users/headspin/Downloads/HeadSpin.ipa" -F metadata='{"region": "usa"}'</code>

Example

Upload an app:


curl -X POST https://<your_api_token>@api-dev.headspin.io/v1/app/upload -F app="@HeadSpin.ipa"

Upload an app and set the metadata:


curl -X POST https://<your_api_token>@api-dev.headspin.io/v1/app/upload -F app="@HeadSpin.apk" -F metadata='{"region": "usa"}'

Response

  • <code class="dcode">{"app_id": "<app-id>"}</code> if the app is successfully uploaded.
  • <code class="dcode">{"status": "Invalid or corrupted app file.", "status_code": 400}</code> if the app was invalid or unsupported.
  • <code class="dcode">{"status": "Failed to upload app.", "status_code": 500}</code> if there was a problem uploading the app.

List uploaded apps and their metadata

Route Method
/v1/apps GET

Optional Parameters

Apps are retrieved in descending order of their upload timestamp. Use the following parameters to page through results.

  • <code class="dcode">/v1/apps?limit=N</code>: retrieve up to at most N apps per page, defaults to 100.
  • <code class="dcode">/v1/apps?page=N:</code> the zero-indexed page number, defaults to 0.

Example

Retrieve the 100 most recently uploaded apps.


curl https://<your_api_token>@api-dev.headspin.io/v1/apps

Retrieve the 50 most recently uploaded apps.


curl https://<your_api_token>@api-dev.headspin.io/v1/apps?limit=50

Retrieve the 51st-100th most recently uploaded apps.


curl "https://<your_api_token>@api-dev.headspin.io/v1/apps?limit=50&page=1"

Retrieve all apps.


curl https://<your_api_token>@api-dev.headspin.io/v1/apps?limit=0

Response

A JSON object, containing an array of uploaded apps and their metadata. Example:


{
  "apps": [
    {
      "app_id": "34336ebd-2616-4784-a0fb-8ceb314a717e",
      "app_identifier": "io.headspin.android",
      "app_name": "HeadSpin Android",
      "app_type": "apk",
      "build_commit": null,
      "build_timestamp": null,
      "build_type": null,
      "file_size": 19051062,
      "files": {},
      "os_minimum": "21",
      "os_type": "android",
      "region": "mena",
      "release_type": null,
      "tags": null,
      "upload_timestamp": 1661337631.006,
      "validation_hashes": {
          "md5": "f3d9fbe152d0865f23bf9e036612c34d",
          "sha1": "5174ab4254a32d00975365e2e563561041e9bc84",
          "sha256": "1e0ebbe108bb6aba5a6361e3da8fc70f0358153ee727ebe92327056cf5880921"
      },
      "version_number": "1",
      "version_semantic": "1.0.0",
      "version_tag": null
    },
    {
      "app_id": "90e6af71-c04d-47aa-ae07-c3260df6d5a7",
      "app_identifier": "io.headspin.ios",
      "app_name": "HeadSpin iOS",
      "app_type": "ipa",
      "build_commit": null,
      "build_timestamp": null,
      "build_type": null,
      "file_size": 9525531,
      "files": {},
      "os_minimum": "12.0",
      "os_type": "ios",
      "region": "usa",
      "release_type": null,
      "tags": null,
      "upload_timestamp": 1661337471.927,
      "validation_hashes": {
          "md5": "41d6005e49013b7d25928434e7cb71d9",
          "sha1": "3950db3152c0a5064338ab98cb61fa94d3680eb9",
          "sha256": "0e027d7cc6d857b05b64ceca3eca9ed12aa10191a47ed1ae7325d02c3205383c"
      },
      "version_number": "1",
      "version_semantic": "1.0",
      "version_tag": null
    }
  ]
}

Get the most recently uploaded app

Route Method
/v1/apps/latest GET

Example


curl https://<your_api_token>@api-dev.headspin.io/v1/apps/latest

Response

A JSON object representing the latest app and its metadata. Example:


{
  "app_id": "f167be2d-3e39-4db3-a3c9-0fb8cdf89ebe",
  "app_identifier": "io.headspin.android",
  "app_name": "HeadSpin Android",
  "app_type": "apk",
  "build_commit": null,
  "build_timestamp": null,
  "build_type": null,
  "file_size": 19069181,
  "files": {},
  "os_minimum": "21",
  "os_type": "android",
  "region": "mena",
  "release_type": null,
  "tags": null,
  "upload_timestamp": 1661337631.006,
  "validation_hashes": {
      "md5": "8455beffc6b566289fddaed4bb6fa369",
      "sha1": "e538ff02797290546a5b6cfe967b94f253d48cf0",
      "sha256": "fbdf64409b1e5de575dc9f43e61d42ebc4dd5f54ef15d4f2b601437ba6399b82"
  },
  "version_number": "3",
  "version_semantic": "1.0.2",
  "version_tag": null
}

Get the following most recently uploaded apps

Route Method
/v1/apps/previous GET

Optional Parameters

  • <code class="dcode">/v1/apps/previous?limit=N</code>: retrieve up to at most N following most recent apps, defaults to 1.

Example


curl https://<your_api_token>@api-dev.headspin.io/v1/apps/previous?limit=2

Response

A JSON object representing the following most recent apps up to the limit. Example:


{
  "apps": [
    {
      "app_id": "34336ebd-2616-4784-a0fb-8ceb314a717e",
      "app_identifier": "io.headspin.android",
      "app_name": "HeadSpin Android",
      "app_type": "apk",
      "build_commit": null,
      "build_timestamp": null,
      "build_type": null,
      "file_size": 19492881,
      "files": {},
      "os_minimum": "21",
      "os_type": "android",
      "region": "mena",
      "release_type": null,
      "tags": null,
      "upload_timestamp": 1661901921.718,
      "validation_hashes": {
          "md5": "41d6005e49013b7d25928434e7cb71d9",
          "sha1": "ce0cdc118365c6108e2b04c48b87fdf1f98a3063",
          "sha256": "76cc5c3ff3f568969c1b667ee5988b2bcd4f55d97fbca8126b8daaf9f61244a2"
      },
      "version_number": "2",
      "version_semantic": "1.0.1",
      "version_tag": null
    },
    {
      "app_id": "1f2851bf-3b56-4ba0-9f9d-85b59af4162d",
      "app_identifier": "io.headspin.android",
      "app_name": "HeadSpin Android",
      "app_type": "apk",
      "build_commit": null,
      "build_timestamp": null,
      "build_type": null,
      "file_size": 19051062,
      "files": {},
      "os_minimum": "21",
      "os_type": "android",
      "region": "mena",
      "release_type": null,
      "tags": null,
      "upload_timestamp": 1661337631.006,
      "validation_hashes": {
          "md5": "f3d9fbe152d0865f23bf9e036612c34d",
          "sha1": "5174ab4254a32d00975365e2e563561041e9bc84",
          "sha256": "1e0ebbe108bb6aba5a6361e3da8fc70f0358153ee727ebe92327056cf5880921"
      },
      "version_number": "1",
      "version_semantic": "1.0.0",
      "version_tag": null
    },
  ]
}

List the available Metadata Selector keys

Route Method
/v1/apps/keys GET

Example


curl https://<your_api_token>@api-dev.headspin.io/v1/apps/keys

Response

A JSON object, containing an array of available Metadata Selector keys. Example:


{
  "keys": [
    "app_id",
    "app_identifier",
    "app_name",
    "app_type",
    "build_commit",
    "build_timestamp",
    "build_type",
    "file_size",
    "os_minimum",
    "os_type",
    "region",
    "release_type",
    "tags",
    "upload_timestamp",
    "version_number",
    "version_semantic",
    "version_tag"
  ]
}

Install an app on a device by metadata selector

Retrieve the most recently uploaded app matched by the metadata selector and install it on the target device.

Route Method
/v1/apps/{metadata_selector}/latest/install/{device_id} POST

Optional Parameters

  • <code class="dcode">/v1/apps/{metadata_selector}/latest/install/{device_id}?sign=false</code>: disable automated signing. iOS only, see idevice-api for signing documentation.

Example

Install the latest iOS app with a <code class="dcode">MinimumOSVersion</code> of <code class="dcode">12.0</code>:


curl -X POST https://<your_api_token>@api-dev.headspin.io/v1/apps/os_type:ios+os_minimum:12.0/latest/install/{ios-device-id}

Response

A JSON object, containing the result of the install attempt. Example:


{
    "returncode": 0,
    "status": 0,
    "stdout": "Install ipa 'app.ipa'\nUploading app to device at 'PublicStaging/install-1668030723698048000.ipa'..\nUploaded app in 318.79737ms\nInstalling app 'io.headspin.ios'\nInstall: CreatingStagingDirectory (5%)\nInstall: ExtractingPackage (15%)\nInstall: InspectingPackage (20%)\nInstall: TakingInstallLock (20%)\nInstall: PreflightingApplication (30%)\nInstall: InstallingEmbeddedProfile (30%)\nInstall: InstallingEmbeddedProfile (30%)\nInstall: VerifyingApplication (40%)\nInstall: CreatingContainer (50%)\nInstall: InstallingApplication (60%)\nInstall: PostflightingApplication (70%)\nInstall: SandboxingApplication (80%)\nInstall: GeneratingApplicationMap (90%)\nInstalled 'app.ipa'\n",
    "summary": "ok"
}

Uninstall an app from a device by metadata selector

Retrieve the most recently uploaded app matched by the metadata selector and uninstall it from the target device.

Route Method
/v1/apps/{metadata_selector}/uninstall/latest/{device_id} POST

Example

Uninstall an <code class="dcode">Android</code> app with <code class="dcode">package</code> name <code class="dcode">io.headspin.android</code>:


curl -X POST https://<your_api_token>@api-dev.headspin.io/v1/apps/os_type:android+app_identifier:io.headspin.android/latest/uninstall/{android-device-id}

Response

A JSON object, containing the result of the uninstall attempt. Example:


{
    "returncode": 0,
    "status": 0,
    "stdout": "Success\n",
    "summary": "ok"
}

List apps and their metadata matched by metadata selector

Retrieve all apps matched by the metadata selector.

Route Method
>/v1/apps/{metadata_selector}/metadata GET

Example

Retrieve all Android apps.


curl -X GET https://<your_api_token>@api-dev.headspin.io/v1/apps/os_type:android/metadata

Response

A JSON object, containing an array of apps matched by the metadata selector. Example:


{
  "apps": [
    {
      "app_id": "34336ebd-2616-4784-a0fb-8ceb314a717e",
      "app_identifier": "io.headspin.android",
      "app_name": "HeadSpin Android",
      "app_type": "apk",
      "build_commit": null,
      "build_timestamp": null,
      "build_type": null,
      "file_size": 19492881,
      "files": {},
      "os_minimum": "21",
      "os_type": "android",
      "region": "mena",
      "release_type": null,
      "tags": null,
      "upload_timestamp": 1661901921.718,
      "validation_hashes": {
          "md5": "41d6005e49013b7d25928434e7cb71d9",
          "sha1": "ce0cdc118365c6108e2b04c48b87fdf1f98a3063",
          "sha256": "76cc5c3ff3f568969c1b667ee5988b2bcd4f55d97fbca8126b8daaf9f61244a2"
      },
      "version_number": "2",
      "version_semantic": "1.0.1",
      "version_tag": null
    },
    {
      "app_id": "1f2851bf-3b56-4ba0-9f9d-85b59af4162d",
      "app_identifier": "io.headspin.android",
      "app_name": "HeadSpin Android",
      "app_type": "apk",
      "build_commit": null,
      "build_timestamp": null,
      "build_type": null,
      "file_size": 19051062,
      "files": {},
      "os_minimum": "21",
      "os_type": "android",
      "region": "mena",
      "release_type": null,
      "tags": null,
      "upload_timestamp": 1661337631.006,
      "validation_hashes": {
          "md5": "f3d9fbe152d0865f23bf9e036612c34d",
          "sha1": "5174ab4254a32d00975365e2e563561041e9bc84",
          "sha256": "1e0ebbe108bb6aba5a6361e3da8fc70f0358153ee727ebe92327056cf5880921"
      },
      "version_number": "1",
      "version_semantic": "1.0.0",
      "version_tag": null
    },
  ]
}

Get the most recently uploaded app matched by metadata selector

Retrieve the most recently uploaded app matched by the metadata selector.

Route Method
/v1/apps/{metadata_selector}/latest GET

Example

Get the latest iOS app with a MinimumOSVersion of 12.0:


curl -X GET https://<your_api_token>@api-dev.headspin.io/v1/apps/os_type:ios+os_minimum:12.0/latest

Response

A JSON object representing the latest app and its metadata. Example:


{
  "app_id": "f167be2d-3e39-4db3-a3c9-0fb8cdf89ebe",
  "app_identifier": "io.headspin.android",
  "app_name": "HeadSpin Android",
  "app_type": "apk",
  "build_commit": null,
  "build_timestamp": null,
  "build_type": null,
  "file_size": 19069181,
  "files": {},
  "os_minimum": "21",
  "os_type": "android",
  "region": "mena",
  "release_type": null,
  "tags": null,
  "upload_timestamp": 1661337631.006,
  "validation_hashes": {
      "md5": "8455beffc6b566289fddaed4bb6fa369",
      "sha1": "e538ff02797290546a5b6cfe967b94f253d48cf0",
      "sha256": "fbdf64409b1e5de575dc9f43e61d42ebc4dd5f54ef15d4f2b601437ba6399b82"
  },
  "version_number": "3",
  "version_semantic": "1.0.2",
  "version_tag": null
}

Get the following most recently uploaded apps matched by metadata selector

Route Method
/v1/apps/{metadata_selector}/previous GET

Optional Parameters

  • <code class="dcode">/v1/apps/{metadata_selector}/previous?limit=N</code>: retrieve up to at most N following most recent apps, defaults to 1.

Example

Get the second and third most recently uploaded <code class="dcode">Android</code> apps with a <code class="Dcode">minSdkVersion</code> of <code class="dcode">21</code>:


curl -X GET https://<your_api_token>@api-dev.headspin.io/v1/apps/os_type:android+os_minimum:21/previous?limit=2

Response

A JSON object representing the following most recent apps up to the limit. Example:


{
  "apps": [
    {
      "app_id": "34336ebd-2616-4784-a0fb-8ceb314a717e",
      "app_identifier": "io.headspin.android",
      "app_name": "HeadSpin Android",
      "app_type": "apk",
      "build_commit": null,
      "build_timestamp": null,
      "build_type": null,
      "file_size": 19492881,
      "files": {},
      "os_minimum": "21",
      "os_type": "android",
      "region": "mena",
      "release_type": null,
      "tags": null,
      "upload_timestamp": 1661901921.718,
      "validation_hashes": {
          "md5": "41d6005e49013b7d25928434e7cb71d9",
          "sha1": "ce0cdc118365c6108e2b04c48b87fdf1f98a3063",
          "sha256": "76cc5c3ff3f568969c1b667ee5988b2bcd4f55d97fbca8126b8daaf9f61244a2"
      },
      "version_number": "2",
      "version_semantic": "1.0.1",
      "version_tag": null
    },
    {
      "app_id": "1f2851bf-3b56-4ba0-9f9d-85b59af4162d",
      "app_identifier": "io.headspin.android",
      "app_name": "HeadSpin Android",
      "app_type": "apk",
      "build_commit": null,
      "build_timestamp": null,
      "build_type": null,
      "file_size": 19051062,
      "files": {},
      "os_minimum": "21",
      "os_type": "android",
      "region": "mena",
      "release_type": null,
      "tags": null,
      "upload_timestamp": 1661337631.006,
      "validation_hashes": {
          "md5": "f3d9fbe152d0865f23bf9e036612c34d",
          "sha1": "5174ab4254a32d00975365e2e563561041e9bc84",
          "sha256": "1e0ebbe108bb6aba5a6361e3da8fc70f0358153ee727ebe92327056cf5880921"
      },
      "version_number": "1",
      "version_semantic": "1.0.0",
      "version_tag": null
    },
  ]
}

Update metadata for apps matched by metadata selector

Accepts a JSON object containing a dictionary of metadata fields, retrieves apps matched by metadata selector, and updates only the referenced fields, preserving the others.

Route Method
/v1/apps/{metadata_selector}/metadata PATCH

Request Body

The request's body should be a JSON object containing the metadata to update. To include the JSON object, use <code class="dcode">curl</code>'s optional flag <code class="dcode">--data-binary <json-object></code>, for example <code class="dcode">--data-binary '{"region": "usa"}'</code>

Example

Update metadata for <code class="dcode">iOS</code> apps with <code class="dcode">release_type</code> set to <code class="dcode">distribution</code>:


curl -X PATCH https://<your_api_token>@api-dev.headspin.io/v1/apps/os_type:ios+release_type:distribution/metadata --data-binary '{"build_type": "production"}'

Response


{
  "modified_app_ids": ["f3e1b4ed-715c-404d-b91b-26cda0c0e54f", "90e6af71-c04d-47aa-ae07-c3260df6d5a7"]
}

Delete apps matched by metadata selector

Delete all apps matched by the metadata selector.

Route Method
/v1/apps/{metadata_selector}/delete DELETE

Example


curl -X DELETE https://<your_api_token>@api-dev.headspin.io/v1/apps/upload_timestamp:<=1661337631/delete

Response

A JSON object, containing an array of deleted apps matched by the metadata selector. Example:


{
  "deleted_app_ids": ["f3e1b4ed-715c-404d-b91b-26cda0c0e54f", "90e6af71-c04d-47aa-ae07-c3260df6d5a7"]
}

Upload additional app file for apps matched by metadata selector

Some HeadSpin features require access to additional files associated with your app, such as binary debug information.

Route Method
/v1/apps/{metadata_selector}/files/{file_type} PUT

Request Body

The request's body should be the additional app file. To include the additional app file, use <code class="dcode">curl</code>'s optional flag <code class="dcode">--data-binary @<path-to-file></code>, for example <code class="dcode">--data-binary "@/Users/headspin/Downloads/dSYMs.zip"</code>

Example

Upload an iOS app's Debug Symbol files (dSYMs):


curl -X PUT https://<your_api_token>@api-dev.headspin.io/v1/apps/os_type:ios+app_identifier:io.headspin.ios/files/dsyms --data-binary "@dSYMs.zip"

Response


{
  "modified_app_ids": ["f3e1b4ed-715c-404d-b91b-26cda0c0e54f", "90e6af71-c04d-47aa-ae07-c3260df6d5a7"]
}

Get additional app file metadata for apps matched by metadata selector

Retrieve the metadata for an additional app file for all apps matched by metadata selector.

Route Method
/v1/apps/{metadata_selector}/files/{file_type} GET

Example

Get the metadata for an additional app file for all matching apps:


curl -X GET https://<your_api_token>@api-dev.headspin.io/v1/apps/os_type:ios+app_identifier:io.headspin.ios/files/dsyms

Response

A JSON object representing the metadata for an app's additional file.


{
  "f3e1b4ed-715c-404d-b91b-26cda0c0e54f": {
    "dsyms": {
      "file_id": "df2d6bd9-f878-4df4-a13c-e17c1feaa4e0",
      "file_size": 44247230,
      "md5": "109892144fd619ae3ba4df31dbbbc22e",
      "sha1": "41858155e5569fc8101c316f7f4141142de9ac34",
      "sha256": "87a806f966d90932a5b266c51dad3c69b3569718e29d3c32c04d3b78c4568ccb"
    }
  },
  "90e6af71-c04d-47aa-ae07-c3260df6d5a7": {
    "dsyms": {
      "file_id": "ee721428-0eac-4f55-a410-55ce66b90c94",
      "file_size": 44247230,
      "md5": "109892144fd619ae3ba4df31dbbbc22e",
      "sha1": "41858155e5569fc8101c316f7f4141142de9ac34",
      "sha256": "87a806f966d90932a5b266c51dad3c69b3569718e29d3c32c04d3b78c4568ccb"
    }
  }
}

Delete additional app file for apps matched by metadata selector

Route Method
/v1/apps/{metadata_selector}/files/{file_type} DELETE

Example

Delete the Debug Symbol files for all matched apps:


curl -X DELETE https://<your_api_token>@api-dev.headspin.io/v1/apps/os_type:ios+app_identifier:io.headspin.ios/files/dsyms

Response


{
  "modified_app_ids": ["f3e1b4ed-715c-404d-b91b-26cda0c0e54f", "90e6af71-c04d-47aa-ae07-c3260df6d5a7"]
}

Install an app on a device by app ID

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

Optional Parameters

  • <code class="dcode">/v1/app/{app_id}/install/{device_id}?sign=false</code>: disable automated signing. iOS only, see idevice-api 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

Example


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

Get app metadata by app ID

Route Method
/v1/app/{app_id}/metadata GET

Example


curl -X GET https://<your_api_token>@api-dev.headspin.io/v1/app/{app_id}/metadata

Response

A JSON object representing the app and its metadata. Example:


{
  "app_id": "90e6af71-c04d-47aa-ae07-c3260df6d5a7",
  "app_identifier": "io.headspin.ios",
  "app_name": "HeadSpin iOS",
  "app_type": "ipa",
  "build_commit": null,
  "build_timestamp": null,
  "build_type": null,
  "file_size": 9525531,
  "files": {},
  "os_minimum": "12.0",
  "os_type": "ios",
  "region": "usa",
  "release_type": null,
  "tags": null,
  "upload_timestamp": 1661337471.927,
  "validation_hashes": {
      "md5": "41d6005e49013b7d25928434e7cb71d9",
      "sha1": "3950db3152c0a5064338ab98cb61fa94d3680eb9",
      "sha256": "0e027d7cc6d857b05b64ceca3eca9ed12aa10191a47ed1ae7325d02c3205383c"
  },
  "version_number": "1",
  "version_semantic": "1.0",
  "version_tag": null
}

Update app metadata by app ID

Accepts a JSON object containing a dictionary of metadata fields and updates only the referenced fields, preserving the others.

Route Method
/v1/app/{app_id}/metadata PATCH

Request Body

The request's body should be a JSON object containing the metadata to update. To include the JSON object, use <code class="dcode">curl</code>'s optional flag <code class="dcode">--data-binary <json-object></code>, for example <code class="dcode">--data-binary '{"region": "usa"}'</code>

Example

Update an app's metadata:


curl -X PATCH https://<your_api_token>@api-dev.headspin.io/v1/app/{app_id}/metadata --data-binary '{"build_type": "production"}'

Response


{
  "status": "Modified app with app_id 90e6af71-c04d-47aa-ae07-c3260df6d5a7.",
  "status_code": 200
}

Download an app by app ID

Route Method
/v1/app/{app_id}/download GET

Example


curl -L https://<your_api_token>@api-dev.headspin.io/v1/app/{app_id}/download -o HeadSpin.ipa

This example uses <code class="dcode">curl</code> to perform the download. The -L and -o options are recommended:

  • <code class="dcode">-L</code>: The app is downloaded from our data service, which has a different endpoint from our API server to which the API request is made.
  • <code class="dcode">-o {path-to-save-app}</code>: Writes the app as a file on your local system.

Response

The response contains the app.

Delete an app by app ID

Route Method
/v1/app/{app_id}/delete DELETE

Example


curl -X DELETE https://<your_api_token>@api-dev.headspin.io/v1/app/{app_id}/delete

Response


{
  "status": "Deleted app with app_id 90e6af71-c04d-47aa-ae07-c3260df6d5a7.",
  "status_code": 200
}

Upload additional app file by app ID

Some HeadSpin features require access to additional files associated with your app, such as binary debug information.

Route Method
/v1/app/{app_id}/files/{file_type} PUT

Request Body

The request's body should be the additional app file. To include the additional app file, use <code class="dcode">curl</code>'s optional flag <code class="dcode">--data-binary @<path-to-file></code>, for example <code class="dcode">--data-binary "@/Users/headspin/Downloads/dSYMs.zip"</code>

Example

Upload an iOS app's Debug Symbol files (dSYMs):


curl -X PUT https://<your_api_token>@api-dev.headspin.io/v1/app/{app_id}/files/dsyms --data-binary "@dSYMs.zip"

Response


{
  "status": "Updated files for app with app_id 90e6af71-c04d-47aa-ae07-c3260df6d5a7.",
  "status_code": 200
}

Get additional app file metadata by app ID

Retrieve the metadata for one of an app's additional app files.

Route Method
/v1/app/{app_id}/files/{file_type} GET

Example

Get the metadata for an app's additional files:


curl -X GET https://<your_api_token>@api-dev.headspin.io/v1/app/{app_id}/files/dsyms

Response

A JSON object representing the metadata for an app's additional file.


{
  "dsyms": {
    "file_id": "9a770978-24ce-4b4f-88df-7f1e5253fa48",
    "file_size": 44247230,
    "md5": "109892144fd619ae3ba4df31dbbbc22e",
    "sha1": "41858155e5569fc8101c316f7f4141142de9ac34",
    "sha256": "87a806f966d90932a5b266c51dad3c69b3569718e29d3c32c04d3b78c4568ccb"
  }
}

OR


{
  "status": "File not found.",
  "status_code": 404
}

if the app does not possess the additional app file.

Delete additional app file by app ID

Route Method
/v1/app/{app_id}/files/{file_type} DELETE

Example

Delete an <code class="dcode">iOS</code> app's Debug Symbol files:


curl -X DELETE https://<your_api_token>@api-dev.headspin.io/v1/app/{app_id}/files/dsyms

Response


{
  "status": "Deleted file for app with app_id 90e6af71-c04d-47aa-ae07-c3260df6d5a7.",
  "status_code": 200
}