Builds (API v2) – App47, Inc.

Introduction

This article explains how to manage builds for your apps.

App47 APIv2 (BETA) Builds

The Builds end point allows you create, update, list, view, and delete builds for an application in your account. You must have the proper permissions in your account in order to use this end point with your member token.

To use this API you must have the following permissions:

Action	Required permission
List Builds	At least read permission on the specific app
Show Build	At least read permission on the specific app
Edit Build	At least edit permission on the specific app
Create Build	At least edit permission on the specific app
Delete Build	Manage permission on the specific app
Activate Build	Manage permission on the specific app
Deactivate Build	Manage permission on the specific app
Resubmit Build	Manage permission on the specific app

For more information on how to configure your APIv2 calls, please consult the APIv2 Overview.

Parameters

When fetching, creating or updating information about builds, the input parameters in the following table are provided through the App47 API:

Parameter Name	Input	Output	Type(s)	Description
activateable	No	Yes	Private	If the build is activatable, meaning is it valid and not the current active build
active	No	Yes	Private build	If this is the active build for the given platform and environment
aetx_file_id	Yes	No	When creating a windows phone 8 build that requires a AETX file, the Uploaded File Id previously uploaded
android_id	Yes	No	Public	The Android ID “com.evernote” to use for this public build.
build_upload_file_id	Yes	No	Private build	ID returned from Uploaded file API
build_upload	Yes	No	Private build	Raw file input in HTTPS POST action
dsym_file_id	Yes	No	Private build	ID returned from Uploaded file API
dsym_file	Yes	No	Private build	Raw file input in HTTPS POST action
environment	Yes	Yes	All	Environments can be “Test” or “Production”. For Windows and Android builds you can update this parameter, however on iOS you cannot change this value
external_id	Yes	No	Public	The iTunes ID to use for this public build.
make_active	Yes	No	Private builds	If the build should be made activate after validation, default is false.
message	No	Yes	Private	Last message by the build processor
minimum_os_version	No	Yes	All	Minimum OS Version supported by this build
name	Yes	No	Public	If you wish to over ride the name from the public app store.
notify_users_on_activation	Yes	Yes	If users should be notified when this build is activated, default is true
platform	No	Yes	All	The platform for this build, Android, iOS, Windows
release_notes	Yes	Yes	All	Release notes for this build
reset_bundle_identifier	Yes	No	If the bundle identifier for the app should be reset based on this build. Default is false.
reuse_version_number	Yes	No	If the build processor should allow the version number to be reused. Default is false.
state	No	Yes	Private build	The current state of this build, i.e., uploaded, processed, invalid, active
supported_cpu_types	No	Yes	All	Supported CPU architectures
target_model	No	All	Windows	The target model for this build
unique_identifier	No	Yes	Private	The Unique identifier for this build, and, thusly, for this application. If a subsequent build is uploaded with a different unique_identifier, the build will be flagged as an error. To over ride this, see reset_bundle_identifier
update_app_icon	Yes	No	If the app icon should be updated based on the icon image file contained in the build. Default is false and currently only supported on the iOS platform.
update_app_name	Yes	No	If the app name should be updated based on the name contained in the manifest file. Default is false an currently only supported on the iOS platform.
profile_expiration_date	No	Yes	Private	For iOS builds, the date when the associated profile for the build will expire
profile_name	No	Yes	Private	For iOS builds, the name of the profile used to sign the application
url	No	Yes	All	The location of the build file
version	No	Yes	All	The version number for the build

Build States

There are four build states for apps:

uploaded - The build has been uploaded to the system and not yet processed.
processing - The build processor has started processing the build for verification and distribution.
processed - The build has been processed and is available for activation.
invalid - The build has been processed and there is an error with the build, please see the message field for more details.

List Builds

In order to list builds for the application in your account, you must have at least read access.

End Point

GET https://cirrus.app47.com/api/v2/apps/«app_id»/builds

Example:

curl -H"Access-Token: <<your token>>"  https://cirrus.app47.com/api/v2/apps/<<app_id>>/builds

Input Parameters

Parameter	Description	Required?	Example(s)/Allowed Values
environment	Show builds only in the requested environment	No	Valid values are Production, Test
platform	Show builds only for a specific platform	No	Valid values are Android, iOS and WP8
active	Show builds that are active or not active	No	true or false

Example, to list only builds on the Android platform:

curl -H"Access-Token: <<your token>>"  https://cirrus.app47.com/api/v2/apps/<<app_id>>/builds?platform=android

Expected Output

If valid, it will return a result with:

Success set to true
Skip - the number of records that were skipped (The API will return sets of 100 records)
Total - The total number of builds for this app
Count - The total number of builds returned in this response
List - List of builds you have access to and match the input parameters
A md5 has of the results element
HTTP result code 200

{
  "results":
    {
      "skip": 0,
      "total": 0,
      "count": 0,
      "list": [],
      "success":true
    },
  "md5":"896d94e5e2f4eb6b6bfa19144c7794e5"
}

If invalid, it will return a result with:

Success set to false
A message indicating the error
A md5 has of the results element
HTTP result code that is *not* 200

{
  "results":
    {
      "message":"Invalid platform type (blah)",
      "success":true
    },
  "md5":"896d94e5e2f4eb6b6bfa19144c7794e5"
}

Show a Specific Build

Showing a specific build for a given app is done by App ID. The App ID can be found on your portal, in the My Apps section, or on the previous call to list all apps.

You must have at least read access on the requested app in order for this call to work correctly.

End Point

GET https://cirrus.app47.com/api/v2/apps/«app_id»/builds/«build_id»

Example:

curl -H"Access-Token: <<your token>>"  https://cirrus.app47.com/api/v2/apps/<<app_id>>/builds/<<build_id>>

Expected Output

{
  "results":
    {
      "build":
        {
          "id":"4ea84a6006e7280001000018",
          "created":"2014-04-02T20:24:05Z",
          "modified":"2014-04-02T20:24:05Z",
          "environment":"Test",
          "platform":"iOS,
          "version":"processing",
          "release_notes":"testing defect fix",
          "target_model":"iPad",
          "minimum_os_version":"6.1",
          "supported_cpu_types":"All",
          "state":"processed",
          "active":false,
          "url":"https://s3.amazonaws.com:443/App-Builds/BizzyTime/Agent/1319651936.apk",
          "unique_identifier":"com.app47.testagent",
          "release_date":"2014-06-19T20:24:48+00:00",
          "message":"",
          "profile_expiration_date":"2015-07-23T12:32:00",
          "profile_name":"AdHoc",
          "activateable":true,
          "notify_users_on_activation":true
        },
      "success":true
    },
  "md5":"d6222186316b7cadb854bab4f802ee14"
}

Update a Build

In order to update a specific build for an app in your account, you will need to use the App ID and build ID. The App ID can be found on your portal, in the My Apps section, or on the previous call to list all apps. You may only update builds you have at least have Edit privileges on the app.

Parameters that are allowed during update can be found in the table above where the Input column contains a Yes in the row and the type of app you are updating is listed in Type(s) column.

End Point

PUT https://cirrus.app47.com/api/v2/apps/«app_id»/builds/«build_id»

Example:

curl -X PUT -H"Access-Token: <<your token>>" -H"Content-Type: application/json" -d '{"build": { "release_notes": "Now is the time for all good men to come to the aid of their country." } }'  https://cirrus.app47.com/api/v2/apps/<<app_id>>/builds/<<build_id>>

Expected Output

{
  "results":
    {
      "build":
        {
          "id":"4ea84a6006e7280001000018",
          "created":"2014-04-02T20:24:05Z",
          "modified":"2014-04-02T20:24:05Z",
          "environment":"Test",
          "platform":"iOS,
          "version":"processing",
          "release_notes":"Now is the time for all good men to come to the aid of their country.",
          "target_model":"iPad",
          "minimum_os_version":"6.1",
          "supported_cpu_types":"All",
          "state":"processed",
          "active":false,
          "url":"https://s3.amazonaws.com:443/App-Builds/BizzyTime/Agent/1319651936.apk",
          "unique_identifier":"com.app47.testagent",
          "release_date":"2014-06-19T20:24:48+00:00",
          "message":"",
          "profile_expiration_date":"2015-07-23T12:32:00",
          "profile_name":"AdHoc",
          "activateable":true,
          "notify_users_on_activation":true
        },
      "success":true
    },
  "md5":"d6222186316b7cadb854bab4f802ee14"
}

Create a Build

You may either first upload a file and obtain the Uploaded File Id, or upload the build in one API call. If the files are large in the case of iOS with both IPA and DSYM(zip) files it's recommend to use the Uploaded File API.

Once you have this, you can use that uploaded file id to create a new build.

You may only create builds for apps you have edit permission too.

Parameters that are allowed during create can be found in the table above where the Input column contains a Yes in the row and the type of app you are updating is listed in Type(s) column.

End Point using Uploaded File API

POST https://cirrus.app47.com/api/v2/apps/«app_id»/builds

Example:

curl -X POST -H"Access-Token: <<your token>>" -H"Content-Type: application/json" -d '{"build": { "build_upload_file_id": "114fa14238d3b81f6a00003e", "release_notes":"New build"} }'  https://cirrus.app47.com/api/v2/apps/<<app_id>>/builds

Expected Output

{
  "results":
    {
      "build":
        {
          "id":"4ea84a6006e7280001000018",
          "created":"2014-04-02T20:24:05Z",
          "modified":"2014-04-02T20:24:05Z",
          "environment":"Test",
          "platform":"iOS,
          "version":"uploaded",
          "release_notes":"New build",
          "target_model":"",
          "minimum_os_version":"",
          "supported_cpu_types":"All",
          "state":"processed",
          "active":false,
          "url":"https://s3.amazonaws.com:443/App-Builds/BizzyTime/Agent/1319651936.apk",
          "unique_identifier":"com.app47.testagent",
          "release_date":"2014-06-19T20:24:48+00:00",
          "message":"",
          "profile_expiration_date":"",
          "profile_name":"",
          "activate able":false,
          "notify_users_on_activation":true
        },
      "success":true
    },
  "md5":"d6222186316b7cadb854bab4f802ee14"
}

End Point using Direct Upload

POST https://cirrus.app47.com/api/v2/apps/«app_id»/builds

Example:

curl -X POST -H"Access-Token: <<your token>>" https://cirrus.app47.com/api/v2/apps/<<app_id>>/builds -F 'build[build_upload]=@filename.ipa' -F 'build[make_active]=true'

Expected Output

{
  "results":
    {
      "build":
        {
          "id":"4ea84a6006e7280001000018",
          "created":"2014-04-02T20:24:05Z",
          "modified":"2014-04-02T20:24:05Z",
          "environment":"Test",
          "platform":"iOS,
          "version":"uploaded",
          "release_notes":"",
          "target_model":"",
          "minimum_os_version":"",
          "supported_cpu_types":"All",
          "state":"uploaded",
          "active":false,
          "url":"https://s3.amazonaws.com:443/App-Builds/BizzyTime/Agent/1319651936.apk",
          "unique_identifier":"",
          "release_date":"",
          "message":"",
          "profile_expiration_date":"",
          "profile_name":"",
          "activateable":false,
          "notify_users_on_activation":true
        },
      "success":true
    },
  "md5":"d6222186316b7cadb854bab4f802ee14"
}

Delete a Build

Delete an build associated with an app in your account. You may only delete builds if your member has the Admin permission on the requested app.

End Point

DELETE https://cirrus.app47.com/api/v2/apps/«app_id»/builds/«build_id»

Example:

curl -X DELETE -H"Access-Token: <<your token>>"  https://cirrus.app47.com/api/v2/apps/<<app_id>>/builds/<<build_id>>

Expected Output

{
  "results":
    {
      "message":"Build was deleted",
      "success":true
    },
  "md5":"f3d0a22e47ce6158551f483e07b16fe1"
}

Activate a Build

Activating a specific build, it will cause the currently active build to be inactive for the given environment and platform.

You may only activate builds if your member has the Admin permission on the requested app.

End Point

PUT https://cirrus.app47.com/api/v2/apps/«app_id»/builds/«build_id»/activate

Example:

curl -X PUT -H"Access-Token: <<your token>>"  https://cirrus.app47.com/api/v2/apps/<<app_id>>/builds/<<build_id>>/activate

Expected Output

{
  "results":
    {
      "success":true
    },
  "md5":"f3d0a22e47ce6158551f483e07b16fe1"
}

Deactivate a Build

You may only deactivate builds if your member has the Admin permission on the requested app.

End Point

PUT https://cirrus.app47.com/api/v2/apps/«app_id»/builds/«build_id»/deactivate

Example:

curl -X PUT -H"Access-Token: <<your token>>"  https://cirrus.app47.com/api/v2/apps/<<app_id>>/builds/<<build_id>>/deactivate

Expected Output

{
  "results":
    {
      "success":true
    },
  "md5":"f3d0a22e47ce6158551f483e07b16fe1"
}

Resubmit a Build

Resubmit a specific build for processing is done with the build processor.

You may only resubmit builds if your member has the Admin permission on the requested app.

End Point

PUT https://cirrus.app47.com/api/v2/apps/«app_id»/builds/«build_id»/resubmit

Example:

curl -X PUT -H"Access-Token: <<your token>>"  https://cirrus.app47.com/api/v2/apps/<<app_id>>/builds/<<build_id>>/resubmit

Expected Output

{
  "results":
    {
      "success":true
    },
  "md5":"f3d0a22e47ce6158551f483e07b16fe1"
}