API: Versions

This Developer API for versions lets you list versions of an app, upload, create, or update a version, or delete a single or delete multiple versions. All endpoints require authentication with an API token.

Reference

The following string needs to be replaced with the values for your apps:

  • APP_ID: The unique identifier for your app. You can get it from your app page on HockeyApp or through the List of Apps API, field "public_identifier".

List Versions

List all versions of an app. The endpoint returns all versions for developer and members, but only released versions for testers.

GET /api/2/apps/APP_ID/app_versions

Parameters:

  • page - optional, set to 1 or greater to enforce pagination (necessary if you want to access more than 500 versions)

  • include_build_urls - optional, set to "true" to include the direct build URLs in the response JSON; note that this param can only be used by developers or members of the app (not by testers)

Example:

curl \
  -H "X-HockeyAppToken: 4567abcd8901ef234567abcd8901ef23" \
  https://rink.hockeyapp.net/api/2/apps/0873e2b98ad046a92c170a243a8515f6/app_versions

Response:

Status: 200
Body:
{
    "app_versions": [
        {
            "version": "208",
            "mandatory": false,
            "config_url": "https://rink.hockeyapp.net/manage/apps/1266/app_versions/208",
            "download_url":"https://rink.hockeyapp.net/apps/0873e2b98ad046a92c170a243a8515f6/app_versions/208
            "timestamp": 1326195742,
            "appsize": 157547,
            "device_family": null,
            "notes": "<p>Fixed bug when users could not sign in.</p>\n",
            "status": 2,
            "shortversion": "1.1",
            "minimum_os_version": null,
            "title": "HockeyApp"
        },
        {
            "version": "195",
            "mandatory": false,
            "config_url": "https://rink.hockeyapp.net/manage/apps/1266/app_versions/195",
            "timestamp": 1325597848,
            "appsize": 157591,
            "device_family": null,
            "notes": "<ul>\n<li>Added action bar with native support for Android 3.x and 4.0.</li>\n<li>Added grid view on Android tablets.</li>\n<li>Added &quot;Check for Updates&quot; to menu.</li>\n<li>Changed layout of detail view.</li>\n<li>Updated HockeySDK + various bug fixes.</li>\n</ul>\n",
            "status": 1,
            "shortversion": "1.1",
            "minimum_os_version": null,
            "title": "HockeyApp"
        },

        ...
    ],
    "status": "success"
}

Statistics

Get statistics about downloads, installs, and crashes for all versions.

GET /api/2/apps/APP_ID/statistics

Example:

curl \
  -H "X-HockeyAppToken: 4567abcd8901ef234567abcd8901ef23" \
  https://rink.hockeyapp.net/api/2/apps/0873e2b98ad046a92c170a243a8515f6/statistics

Response:

Status: 200
Body:
{
  "status": "success",
  "app_versions": [
    {
      "id": 1,
      "version": "11",
      "shortversion": "1.0.0",
      "created_at": "2013-03-10T19:14:40Z",
      "statistics": {
        "crashes": 123,
        "devices": 10,
        "downloads": 14,
        "installs": 10,
        "last_request_at": "2013-05-03T20:50:07Z",
        "usage_time": "28:10"
    },
    {
      "id": 2,
      "version": "12",
      "shortversion": "1.1.0",
      "created_at": "2013-03-28T22:53:41Z",
      "statistics": {
        "crashes": 101,
        "devices": 11,
        "downloads": 8,
        "installs": 8,
        "last_request_at": "2013-06-23T07:34:53Z",
        "usage_time": "53:23"
      }
    }
  ]
}

Upload Version

Upload an .ipa, .apk, .appx, or .zip file to create a new version for your app. Note that .zip files can only be parsed if they contain an .app, .appx, .appxbundle, or .dsym file. If you want to upload a custom .zip file or other file formats like .msi or .dmg, you need to use the Create Version and Update Version API.

POST /api/2/apps/APP_ID/app_versions/upload

Parameters:

  • ipa - optional (required, if dsym is not specified for iOS or Mac), file data of the .ipa for iOS, .app.zip for Mac OS X, or .apk file for Android

  • dsym - optional, file data of the .dSYM.zip file (iOS and OS X) or mapping.txt (Android); note that the extension has to be .dsym.zip (case-insensitive) for iOS and OS X and the file name has to be mapping.txt for Android.

  • notes - optional, release notes as Textile or Markdown (after 5k characters notes are truncated)

  • notes_type - optional, type of release notes:

    • 0 - Textile
    • 1 - Markdown
  • notify - optional, notify testers (can only be set with full-access tokens):

    • 0 - Don't notify testers
    • 1 - Notify all testers that can install this app
    • 2 - Notify all testers
  • status - optional, download status (can only be set with full-access tokens):

    • 1: Don't allow users to download or install the version
    • 2: Available for download or installation
  • strategy - optional, replace or add build with same build number

    • add to add the build as a new build to even if it has the same build number (default)
    • replace to replace to a build with the same build number
  • tags - optional, restrict download to comma-separated list of tags

  • teams - optional, restrict download to comma-separated list of team IDs; example:

    • 12,23,42 with 12, 23, and 42 being the database IDs of your teams
  • users - optional, restrict download to comma-separated list of user IDs; example:

    • 1224,5678 with 1224 and 5678 being the database IDs of your users
  • mandatory - optional, set version as mandatory:

    • 0 - no
    • 1 - yes
  • commit_sha - optional, set to the git commit sha for this build

  • build_server_url - optional, set to the URL of the build job on your build server

  • repository_url - optional, set to your source repository

Example:

curl \
  -F "status=2" \
  -F "notify=1" \
  -F "notes=Some new features and fixed bugs." \
  -F "notes_type=0" \
  -F "ipa=@hockeyapp.ipa" \
  -F "dsym=@hockeyapp.dSYM.zip" \
  -H "X-HockeyAppToken: 4567abcd8901ef234567abcd8901ef23" \
  https://rink.hockeyapp.net/api/2/apps/1234567890abcdef1234567890abcdef/app_versions/upload

Response:

Status: 201
Body:
{
    "title": "HockeyTest",
    "appsize": 1598428,
    "timestamp": 1308930206,
    "device_family": "iPhone/iPod",
    "minimum_os_version": "4.0",
    "notes": "<p>Some new features and fixed bugs.</p>",
    "version": "8",
    "shortversion": "1.0",
    "status": 2,
    "config_url": "https://rink.hockeyapp.net/manage/apps/123/app_versions/8",
    "public_url": "https://rink.hockeyapp.net/apps/1234567890abcdef1234567890abcdef"
}

Create Version

Create a version without uploading files.

POST /api/2/apps/APP_ID/app_versions/new

Parameters:

  • bundle_version - mandatory, set to CFBundleVersion (iOS and OS X) or to versionCode (Android)

  • bundle_short_version - optional, set to CFBundleShortVersionString (iOS and OS X) or to versionName (Android)

  • notes - optional, release notes as Textile or Markdown (after 5k characters notes are truncated)

  • notes_type - optional, type of release notes:

    • 0 - Textile
    • 1 - Markdown
  • status - optional, download status (can only be set with full-access tokens):

    • 1: Don't allow users to download or install the version
    • 2: Available for download or installation
  • tags - optional, restrict download to comma-separated list of tags

  • teams - optional, restrict download to comma-separated list of team IDs; example:

    • 12,23,42 with 12, 23, and 42 being the database IDs of your teams
  • users - optional, restrict download to comma-separated list of user IDs; example:

    • 1224,5678 with 1224 and 5678 being the database IDs of your users

Example:

curl \
  -F "bundle_short_version=1.0" \
  -F "bundle_version=23" \
  -H "X-HockeyAppToken: 4567abcd8901ef234567abcd8901ef23" \
  https://rink.hockeyapp.net/api/2/apps/1234567890abcdef1234567890abcdef/app_versions/new

Response:

Status: 201
Body:
{
    "title": "HockeyTest",
    "timestamp": 1308930206,
    "id": "1",
    "version": "23",
    "shortversion": "1.0",
    "status": 2,
    "config_url": "https://rink.hockeyapp.net/manage/apps/123/app_versions/8",
    "public_url": "https://rink.hockeyapp.net/apps/1234567890abcdef1234567890abcdef"
}

Update Version

Update the attributes of an existing version.

In combination with the endpoint to create a version, you also can use this endpoint

  • to upload the mapping.txt without the .apk file for Android apps, or
  • to upload additional .dSYM files for iOS and OS X apps, or
  • to upload .pkg or .dmg files for OS X apps, or
  • to upload .msi files for Windows apps, or
  • to upload .zip files for custom apps.

Please make sure that the uploaded file has the same version number as specified when creating this version.

PUT /api/2/apps/APP_ID/app_versions/ID

ID must be replaced by the internal ID of the version which is returned in the above JSON in the key "id".

Parameters:

  • ipa - optional, file data of the .ipa for iOS, .app.zip for Mac OS X, or .apk file for Android

  • dsym - optional, file data of the .dSYM.zip file (iOS and OS X) or mapping.txt (Android); note that the extension has to be .dsym.zip (case-insensitive) for iOS and OS X and the file name has to be mapping.txt for Android.

  • notes - optional, release notes as Textile or Markdown

  • notes_type - optional, type of release notes:

    • 0 - Textile
    • 1 - Markdown
  • notify - optional, notify testers (can only be set with full-access tokens):

    • 0 - Don't notify testers
    • 1 - Notify all testers that can install this app
  • status - optional, download status (can only be set with full-access tokens):

    • 1: Don't allow users to download or install the version
    • 2: Available for download or installation
  • tags - optional, restrict download to comma-separated list of tags

  • teams - optional, restrict download to comma-separated list of team IDs; example:

    • 12,23,42 with 12, 23, and 42 being the database IDs of your teams
  • users - optional, restrict download to comma-separated list of user IDs; example:

    • 1224,5678 with 1224 and 5678 being the database IDs of your users
  • mandatory - optional, set version as mandatory:

    • 0 - no
    • 1 - yes

Example:

curl \
  -X PUT \
  -F "ipa=@hockeyapp.ipa" \
  -F "dsym=@hockeyapp.dSYM.zip" \
  -F "status=2" \
  -F "notify=1" \
  -H "X-HockeyAppToken: 4567abcd8901ef234567abcd8901ef23" \
  https://rink.hockeyapp.net/api/2/apps/1234567890abcdef1234567890abcdef/app_versions/1

Response:

Status: 201

Delete Single Version

Delete a single version.

DELETE /api/2/apps/APP_ID/app_versions/ID

ID must be replaced by the internal ID of the version which is returned in the above JSON in the key "id".

Parameters:

  • strategy - optional, set to "purge" (default) or "soft"; "purge" completely removes the version, while "soft" keeps some data including stats and crashes

Example:

curl \
  -X DELETE \
  -H "X-HockeyAppToken: 4567abcd8901ef234567abcd8901ef23" \
  https://rink.hockeyapp.net/api/2/apps/1234567890abcdef1234567890abcdef/app_versions/23

Delete Multiple Versions

Delete multiple versions with one request.

POST /api/2/apps/APP_ID/app_versions/delete

Parameters:

  • strategy - optional, set to "purge" (default) or "soft"; "purge" completely removes the version, while "soft" keeps some data including stats and crashes

  • sort - optional, set to "version" to sort by version number (default) or to "date" to sort by creation date

  • number - optional, specifies the number of versions to be deleted (default: 0 = all)

  • keep - optional, specifies the number of versions to be kept (default: 0 = none)

Examples:

Delete all versions except the newest 3

curl \
  -F "keep=3" \
  -H "X-HockeyAppToken: 4567abcd8901ef234567abcd8901ef23" \
  https://rink.hockeyapp.net/api/2/apps/1234567890abcdef1234567890abcdef/app_versions/delete

Delete a maximum of 5 versions, but keep at least the newest

curl \
  -F "keep=1" \
  -F "number=5" \
  -H "X-HockeyAppToken: 4567abcd8901ef234567abcd8901ef23" \
  https://rink.hockeyapp.net/api/2/apps/1234567890abcdef1234567890abcdef/app_versions/delete

Response:

Status: 200
Body:
{
    "total_entries": 3
}

The value in "total_entries" is the number of deleted versions.