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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" 'https://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 -H "Authorization: Bearer <your_api_token>" 'https://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 -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v1/app/upload -F app="@headspin.ipa"
Upload an app and set the metadata:
curl -X POST -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v1/apps
Retrieve the 50 most recently uploaded apps.
curl -H "Authorization: Bearer <your_api_token>" https://api-dev.headspin.io/v1/apps?limit=50
Retrieve the 51st-100th most recently uploaded apps.
curl -H "Authorization: Bearer <your_api_token>" "https://api-dev.headspin.io/v1/apps?limit=50&page=1"
Retrieve all apps.
curl -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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 -H "Authorization: Bearer <your_api_token>" https://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
}
