API: Basics and Authentication

HockeyApp provides two different APIs:

  1. The Client API is used by our SDKs to provide features like in-app updates, crash reporting, and feedback. This API requires no authentication. It should be accessed through the domain sdk.hockeyapp.net.

  2. The Developer API is intended for developers to upload new builds, to manage data like crash reports, or in combination with third party libraries and apps. This API requires an API token for authentication. It should be accessed through the domain rink.hockeyapp.net.

Tools

Windows

The built in HockeyApp command line tool for APIs from Windows is called Hoch (Hoch.exe) and is installed with HockeyApp for Windows App.

Mac OS X

The built in HockeyApp command line tool for APIs from Mack OS X is called Puck and is installed with HockeyApp for Mac OS X App.

Multi-Platform

You can use the HockeyApp APIs from standard third-party tools such as: cURL or the Jenkins HockeyApp Plugin.
You can also write Python, Ruby, or PowerShell scripts to call the HockeyApp APIs.

Note: If you have any issues accessing the HockeyApp APIs please confirm that you are using the most updated version of command line tools.

Schema

All API access is over HTTPS. The base path for all endpoints is /api/2. Many API methods take optional parameters:

  • For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter.

  • For POST and PUT requests, parameters not included in the URL should be submitted as form data (application/x-www-form-urlencoded or multipart/form-data). All strings and plain text files must be encoded as UTF-8.

Authentication

Requests that require authentication need to set the HTTP header X-HockeyAppToken to a valid API token. Each user can create multiple tokens under API Tokens in the account menu.

Example request:

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

There are three types of tokens:

  • Full-Access tokens allow read and write access to all endpoints.

  • Upload-Only tokens allow read access to all endpoints plus write access to upload new builds. Note that it is not possible to release a build through the API with this kind of token.

  • Read-Only tokens allow read access to all endpoints

Authentication API

You can retrieve all tokens and create a new token programmatically through the endpoint /api/2/auth_tokens. This is the only endpoint that requires authentication via the user's email and password.

GET /api/2/auth_tokens

Lists all API tokens for the logged user.

Request:

curl --user EMAIL:PASSWORD https://rink.hockeyapp.net/api/2/auth_tokens

Response:

{
    "tokens": [
        {
            "token": "4567abcd8901ef234567abcd8901ef23",
            "rights": 2
        },
        {
            "token": "1234567abcd8901ef234567abcd8901e",
            "rights": 0
        }
    ],
    "status": "success"
}

The token rights are encoded as integer value: 0 = Full Access, 1 = Upload Only, 2 = Read Only, 3 = Upload & Release.

POST /api/2/auth_tokens

Creates a new token.

Parameters:

  • rights - The token type as integer: 0 = Full Access, 1 = Upload Only, 2 = Read Only, 3 = Upload & Release
  • name - optional, the name that should be assigned to the newly created API token

Request:

curl --user EMAIL:PASSWORD -F "rights=2" https://rink.hockeyapp.net/api/2/auth_tokens

Response:

{
    "tokens": [
        {
            "token": "67abcd8901ef234567abcd8901ef2345",
            "rights": 0
        }
    ],
    "status": "success"
}

Response Format

We prefer JSON as the response format of the Developer API. Alternatively, it is possible to get XML by setting the parameter format to xml.

Example:

curl --user EMAIL:PASSWORD https://rink.hockeyapp.net/api/2/auth_tokens?format=xml

Response:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <tokens>
    <token>
      <token>4567abcd8901ef234567abcd8901ef23</token>
      <rights>2</rights>
    </token>
    <token>
      <token>1234567abcd8901ef234567abcd8901e</token>
      <rights>0</rights>
    </token>
  </tokens>
  <status>success</status>
</response>

JSON-P Callbacks

You can send a callback parameter to any GET call to have the results wrapped in a JSON function. This is typically used when browsers want to embed HockeyApp content in web pages by getting around cross domain issues. The response includes the same data output as the regular API.

Pagination

Requests that return multiple items will be paginated to 25 items by default. You can specify further pages with the page parameter. For some resources, you can also set a higher page size (50 or 100) with the per_page parameter.

Rate Limiting

We limit requests to 60 per minute and App ID. If the limit is exceeded, please throttle your script or contact us.