FreeSoft
English EN
PhoneGap archiveDocumentation

Documentation

PhoneGap Build Developer API

Original phonegap build developer api instructions, examples and requirements from the archived project documentation.

Recovered documentationHistorical reference
Archive note. Historical reference. PhoneGap tools and the former Adobe services are no longer maintained as described in the original material. Recovered text and newly written explanations are identified below; consult current platform documentation for active development.

Historical workflow

The recovered instructions below explain the former PhoneGap workflow. PhoneGap Build is closed, and old account, upload and signing operations no longer run on the hosted service. PhoneGap Build archive.

Reference sections

Original source: Developer API

The PhoneGap Build API allows applications to use the PhoneGap Build web service to create, build, update, and download PhoneGap apps. It integrates easily into IDEs, shell scripts, app builders, and elsewhere.

The core sections discussed in this documentation article are:

Here are some additional notes on using the API.

JSON

All successful requests return either a JSON-encoded string or a binary file. All requests that fail return a JSON-encoded string in the following form, with an appropriate status code:

{
  "error":"some error message"
}

When using the API, check each returned status code; if it's not 200, check the error field on the parsed response, for example:

if (res.status != 200)
  console.log(JSON.parse(res.body).error)

As is standard in HTTP, a 4xx status indicates an error with the request, while a 5xx status indicates an server error. Contact PhoneGap's support forums if you get a 500 error, or an unexpected 400 error.

JSONP

JSONP access is available for PhoneGap Build developers: just add a callback parameter to your requests, and the JSONP response body is wrapped in that function:

$ curl https://build.phonegap.com/api/v1/me?auth_token=ASTRINGTOKEN&callback=exec
exec({
  "username":"alunny",
  "email":"[email protected]"
})

This allows you to access the PhoneGap Build API using <script> tags.

HATEOAS

Wherever possible, the PhoneGap Build API v1 uses Hypermedia as the Engine of Application State (HATEOAS). This means you can access the source of the api (/api/v1), then follow nested resources' link attributes to navigate the application, with no knowledge of the other routes within your application.

The home resource for the API v1 is the same as the /me resource, which represents the current user.

Original source: OAuth

The Oauth authorization protocol allows third party applications access user information from PhoneGap Build without ever seeing the user's login information. Client Applications are pre-registered with PhoneGap Build, and users can view and manage which applications are interacting with PhoneGap Build on their behalf.

If you're looking for documentation on simple token authentication, go here. Note that we don't recommend this for integrating production applications with the PhoneGap Build Developer API.

Client Application Registration

As an application developer, you first need to register your client application with Build:

  • Name: A suitable display name for your application.
  • Main Application Url: A url where a user can go to see what this application is.
  • Callback Url: The url we'll redirect to after a user allows your application to interact with your Build account. More info on this below.

We'll generate a couple of fields for you:

  • Client ID: A unique identifier that you'll include in requests, identifying your application.
  • Client Secret: Don't share this, it will verify that the request is indeed from your application.

Web Application Flow

You've registered your application and are ready to hook it into PhoneGap Build. The first thing you'll do is redirect users to PhoneGap Build where we'll ask them if they want to allow your app to access their resources:

GET https://build.phonegap.com/authorize?client_id=abcdef

If they allow, we'll redirect to the Callback Url that you indicated when you registered your application, along with a code parameter. If they deny, we'll redirect to your Callback Url with an error parameter (error=authorization_refused).

Now that the user has allowed your application to access Build, you need to request an access token from us:

POST https://build.phonegap.com/authorize/token?client_id=abcdef&client_secret=123456&code=a1b2c3

If those params fail to check out, you'll get an error with the following format:

{ "error" : "invalid request" }

If they do check out, we'll respond with a json object containing your access token:

{ "access_token": "xyz123" }

Save it.

Now, you can make requests to PhoneGap Build on behalf of this user:

GET https://build.phonegap.com/api/v1/me?access_token=xyz123

Non Web Application Flow

Its possible that you're creating an application that doesn't include a web server or browser to allow users to authorize your application to access the PhoneGap Build API. Don't fret, there is a solution. Users will obtain a simple auth token from Build (in their account settings), which they'll then pass to your application. If they give that token to your application, they have authorized it to access Build. You'll then exchange that simple auth token for an Oauth client access token. Of course, you'll still need to register your application with Build as above.

POST https://build.phonegap.com/authorize?client_id=abcdef&client_secret=123456&auth_token=789hij

For example, via curl:

curl -X POST https://build.phonegap.com/authorize?client_id=abcdef&client_secret=123456&auth_token=789hij

If those params fail to check out, you'll get an error with the following format:

{ "error" : "Invalid authentication token." }

If they do check out, we'll respond with a json object containing your access token:

{ "access_token": "xyz123" }

And now you can make your requests on behalf of the user.

GET https://build.phonegap.com/api/v1/me?access_token=xyz123
Original source: API Authentication

Version 1 supports two forms of authentication: basic authentication over HTTPS, and token authentication.

When using basic authentication, use your PhoneGap Build credentials (username and password) to authenticate each request:

$ curl -u [email protected] https://build.phonegap.com/api/v1/me
{
  "created_at":"2010-10-12T19:10:16Z",
  "updated_at":"2010-11-29T19:58:00Z",
  "username":"alunny",
  "email":"[email protected]"
}

To use token authentication, use basic authentication to post to /token with your request, and the token returns in the response:

$ curl -u [email protected] -X POST -d "" https://build.phonegap.com/token
{
  "token":"ASTRINGTOKEN"
}

Then pass this token as a parameter for any call that you make:

$ curl https://build.phonegap.com/api/v1/me?auth_token=ASTRINGTOKEN
{
  "username":"alunny",
  "email":"[email protected]"
}

Both forms of authentication are supported. All unauthenticated requests return a 401 (unauthorized) status code.

All the examples documented here use token authentication for clarity.

NOTE: Users who registered using Github authentication may not have PhoneGap Build credentials, and therefore may not be able to use basic authentication. To retrieve an authententication token for your Github-linked account, go to Edit Account, on the top right of the site's navigation bar. Find the Authentication Tokens section, where you can obtain, as well as create, reset, or delete your token. Note that resetting or deleting a token invalidates any further requests using the previous token.

Original source: Read API

Back to:

This section details read methods for version 1 of the API. See The PhoneGap Build API for an overview, or The PhoneGap Build Write API for write methods.

Please note that example responses are formatted for the sake of legibility. Actual JSON responses will have no significant whitespace.

The API's read interface includes the following:

GET/api/v1/me Get A User's Profile and Resources

GET/api/v1/apps Get A User's Apps

GET/api/v1/apps/:id Get A User's App by Id

GET/api/v1/apps/:id/:platform Download A User's App by Platform

GET/api/v1/keys Get Meta-data About A User's Keys

GET/api/v1/keys/:platform Get Meta-Data About A User's Platfom Keys

GET/api/v1/keys/:platform/:id Get Meta-Data About A Specific Key

GET https://build.phonegap.com/api/v1/me

Get a JSON-encoded representation of the authenticated user, as well as a listing of associated resources.

This should be the starting point for applications that traverse the PhoneGap Build API. It is aliased to https://build.phonegap.com/api/v1:

$ curl -u [email protected] https://build.phonegap.com/api/v1/me
{
    "id": 1,
    "username":"alunny",
    "email":"[email protected]",
    "apps": {
        "id": 2,
        "link": "/api/v1/apps",
        "all": [
            {
                "title": "A Single App",
                "role": "owner",
                "link": "/api/v1/apps/1234"
            }
        ]
    },
    "keys": {
        "ios": {
            "all":[
                {
                    "id": 34,
                    "default":true,
                    "title": "iOS Development Key",
                    "link": "/api/v1/keys/ios/34"
                },
                {
                    "id": 82,
                    "default":false,
                    "title": "iOS Distribution Key",
                    "link": "/api/v1/keys/ios/82"
                }
            ],
            "link":"/api/v1/keys/ios"
        },
        "android": {
            "all":[
                {
                    "id": 56,
                    "default":false,
                    "title": "Android Release Certificate",
                    "link": "/api/v1/keys/android/56"
                }
            ],
            "link":"/api/v1/keys/android"
        },
        "winphone": {
            "all": [
                {
                    "id": 72,
                    "title": "Windows Publisher Key",
                    "link": "/api/v1/keys/winphone/72",
                    "default": false
                }
            ],
            "link": "/api/v1/keys/winphone",
        }
        "link": "/api/v1/keys"
    },
    "link": "/api/v1/me"
}

GET https://build.phonegap.com/api/v1/apps

Get a JSON-encoded representation of the authenticated user's apps.

API clients can follow the link attribute for each app to get further details, including the associated signing keys and collaborators:

$ curl -u [email protected] https://build.phonegap.com/api/v1/apps
{
    "apps":[
        {
            "title":"My Index",
            "id":1,
            "package":"com.my.index",
            "version":"0.0.1",
            "repo":null,
            "description":"An Index of My Applications",
            "debug":false,
            "private":true,
            "link":"/api/v1/apps/1",
            "build_count":4,
            "phonegap_version":"cli-6.3.0",
            "hydrates":false,
            "status":{
                "android":"complete",
                "ios":null,
                "winphone":"pending"
            },
            "phonegap_versions":{
                "android":"5.2.1",
                "ios":"4.2.0",
                "winphone":"4.4.1"
            },
            "download":{
                "android":"/api/v1/apps/1/android",
            },
            "error":{
            },
            "icon":{
                "filename":"icon.png",
                "link":"/api/v1/apps/1/icon"
            },
            "role":"admin"
        },
        {
            "title":"PhoneGap: Getting Started",
            "id":2,
            "package":"com.phonegap.getting.started",
            "version":"1.0.0",
            "repo":"https://github.com/phonegap/phonegap-start.git",
            "description":"A template for getting started with
                    PhoneGap development and build.phonegap.com",
            "debug":false,
            "private":true,
            "share":true,
            "link":"/api/v1/apps/2",
            "phonegap_version":"cli-6.3.0",
            "build_count":12,
            "status": {
                "android":"complete",
                "ios":"complete",
                "winphone":"complete"
            },
            "phonegap_versions":{
                "android":"5.2.1",
                "ios":"4.2.0",
                "winphone":"4.4.1"
            },
            "download":{
                "android":"/api/v1/apps/1/android",
                "ios":"/api/v1/apps/1/ios",
                "winphone":"/api/v1/apps/1/winphone"
            },
            "error":{},
            "icon":{
                "filename":"big-icon.png",
                "link":"/api/v1/apps/2/icon"
            },
            "role":"admin"
        }
    ],
    "link":"/api/v1/apps"
}

GET https://build.phonegap.com/api/v1/apps/:id

Get a JSON-encoded representation of a particular app, if the authenticated user has permission to access it.

In addition to the fields provided in the list of all apps, this detail view includes:

  • keys: all of the keys that the app is currently being built with. This include the owner's default key for a platform, if selected

  • collaborators: each person who has access to this app, along with their role, if the authenticated user is the owner of the app. Collaborators who are registered with PhoneGap Build are listed under active; collaborators you have invited who have not yet created an account are listed as pending:

$ curl -u [email protected] https://build.phonegap.com/api/v1/apps/2
{
    "title":"PhoneGap: Getting Started",
    "id":2,
    "package":"com.phonegap.getting.started",
    "version":"1.0.0",
    "repo":"https://github.com/phonegap/phonegap-start.git",
    "description":"A template for getting started with
            PhoneGap development and build.phonegap.com",
    "debug":false,
    "private":true,
    "share":false,
    "link":"/api/v1/apps/2",
    "phonegap_version":"cli-6.3.0",
    "last_build":"2014-12-03 13:52:10 -0800",
    "build_count":12,
    "status": {
        "android":"complete",
        "ios":"complete",
        "winphone":"complete"
    },
    "phonegap_versions":{
        "android":"5.2.1",
        "ios":"4.2.0",
        "winphone":"4.4.1"
    },
    "download":{
        "android":"/api/v1/apps/1/android",
        "ios":"/api/v1/apps/1/ios",
        "winphone":"/api/v1/apps/1/winphone"
    },
    "error":{},
    "icon":{
        "filename":"big-icon.png",
        "link":"/api/v1/apps/2/icon"
    },
    "role":"admin",
    "keys":{},
    "collaborators":{
        "link":"/api/v1/apps/9/collaborators",
        "active":[
            {
                "id":9,
                "person":"[email protected]",
                "role":"admin",
                "link":"/api/v1/apps/9/collaborators/9"
            },
            {
                "id":13,
                "person":"[email protected]",
                "role":"developer",
                "link":"/api/v1/apps/9/collaborators/13"
            }
        ],
        "pending":[
            {
                "person":"[email protected]",
                "role":"tester"
            }
        ]
    }
}

If the app does not exist, or you do not have access to it, an error message returns with status code 404:

$ curl -u [email protected] https://build.phonegap.com/api/v1/apps/520394
{
    "error":"app #54 not available"
}

GET https://build.phonegap.com/api/v1/apps/:id/:platform

Download the app package for the given platform. Available platforms are android, ios, and winphone.

If successful, this API method returns a 302 redirect to the application binary, and the body of the response references the file's URL:

$ curl -Lu [email protected] https://build.phonegap.com/api/v1/apps/50/android
{
    "location":""http://s3.amazonaws.com/build.phonegap.com/some-long-guid/app.apk"
}

If your API client can follow redirects, you can save the response directly:

$ curl -Lu [email protected] https://build.phonegap.com/api/v1/apps/50/android > app_50.apk

When downloading, be sure you have the right file extension:

  • apk for Android
  • ipa for iOS
  • xap for Windows Phone

If the app package is unavailable for the specified platform, an error message returns with status code 404:

$ curl -u [email protected] https://build.phonegap.com/api/v1/apps/52/android
{
    "error":"app #52 download unavailable for android"
}

GET https://build.phonegap.com/api/v1/keys

Get a JSON-encoded list of all the signing keys associated with your account.

This returns a short listing of all the associated keys, very similar to the list you see when requesting /api/v1/me:

$ curl -u [email protected] https://build.phonegap.com/api/v1/keys
{
    "keys":{
        "ios":{
            "all":[
                {
                    "id":8,
                    "title":"My Dev Certificate",
                    "default":false,
                    "cert_name":"My_Dev_Cert.p12",
                    "provision":"My_Devices.mobileprovision",
                    "link":"/api/v1/keys/ios/8",
                    "role":"developer",
                    "locked":true
                }
            ],
            "link":"/api/v1/keys/ios"
        },
        "android":{
            "all":[
                {
                    "id":1,
                    "title":"Android Release Key",
                    "default":false,
                    "alias":"release",
                    "link":"/api/v1/keys/android/1",
                    "locked":true
                }
            ],
            "link":"/api/v1/keys/android"
        },
        "winphone":{
            "all":[
                {
                    "id": 72,
                    "title": "Windows Publisher Key",
                    "link": "/api/v1/keys/winphone/72",
                    "default": false
                }
            ],
            "link": "/api/v1/keys/winphone",
        }
    },
    "link":"/api/v1/keys"
}

GET https://build.phonegap.com/api/v1/keys/:platform

Get a JSON-encoded list of all the signing keys associated with your account, for a specific platform. That platform can be either ios or android:

$ curl -u [email protected] https://build.phonegap.com/api/v1/keys/ios
{
    "keys":[
        {
            "id":8,
            "title":"My Dev Certificate",
            "default":false,
            "cert_name":"My_Dev_Cert.p12",
            "provision":"My_Devices.mobileprovision"
            "link":"/api/v1/keys/ios/8",
            "role":"developer",
            "locked":true
        }
    ],
    "link":"/api/v1/keys/ios"
}

$ curl -u [email protected] https://build.phonegap.com/api/v1/keys/android
{
    "keys":[
        {
            "id":1,
            "title":"Android Release Key",
            "default":false,
            "alias":"releasing",
            "link":"/api/v1/keys/android/1",
            "locked":true
        }
    ],
    "link":"/api/v1/keys/android"
}

$ curl -u [email protected] https://build.phonegap.com/api/v1/keys/winphone
{
    "keys":[
        {
            "id": 72,
            "title": "Windows Publisher Key",
            "link": "/api/v1/keys/winphone/72",
            "default": false
        }
    ],
    "link":"/api/v1/keys/winphone"
}

GET https://build.phonegap.com/api/v1/keys/:platform/:id

Get a JSON-encoded representation of a single signing key:

$ curl -u [email protected] https://build.phonegap.com/api/v1/keys/ios/8
{
    "id":8,
    "title":"My Dev Certificate",
    "default":false,
    "cert_name":"My_Dev_Cert.p12",
    "provision":"My_Devices.mobileprovision"
    "link":"/api/v1/keys/ios/8",
    "role":"developer",
    "locked":true
}

$ curl -u [email protected] https://build.phonegap.com/api/v1/keys/android/1
{
    "id":1,
    "title":"Android Release Key",
    "default":false,
    "alias":"releasing",
    "link":"/api/v1/keys/android/1",
    "locked":true
}

$ curl -u [email protected] https://build.phonegap.com/api/v1/keys/winphone/72
{
    "id": 72,
    "title": "Windows Publisher Key",
    "link": "/api/v1/keys/winphone/72",
    "default": false
}

If the requested key is not available, then a 404 status returns, along with the error message as JSON:

$ curl -u [email protected] https://build.phonegap.com/api/v1/keys/ios/8989898
{
    "error":"could not find ios key #8989898"
}
Original source: Write API

Back to:

This section details write methods for version 1 of the API. See The PhoneGap Build API for an overview, or The PhoneGap Build Read API for read methods.

All write API methods expect JSON-encoded content. Many also accept file uploads. API requests should have the content type multipart/form-data, and bodies of JSON requests should be named data.

The API's write interface includes the following:

POST/api/v1/apps Create a New App

PUT/api/v1/apps/:id Update an Existing App

POST/api/v1/apps/:id/build Start a Build For a Specific App

POST/api/v1/apps/:id/build/:platform Start a Build for an App for a Specific Platform

POST/api/v1/apps/:id/collaborators Add a Collaborator To an App

PUT/api/v1/apps/:id/collaborators/:id Update a Collaborator On a App

POST/api/v1/keys/:platform Add a Signing Key for A Specific Platform

PUT/api/v1/keys/:platform/:id Update/Unlock a Signing Key for a Specific Platform

DELETE/api/v1/apps/:id Delete an App

DELETE/api/v1/apps/:id/collaborators/:id Delete a Collaborator for an App

DELETE/api/v1/keys/:platform/:id Delete a Key

POST https://build.phonegap.com/api/v1/apps

Creates a new app. Required parameters:

  • title: You must specify a title for your app. Any title specified in your package's config.xml takes precedence.

  • create_method: How the app is created (described below). There are two valid values:

    • file: A file is being uploaded with the app content

    • remote_repo: You have a remote repository with your app content

Optional parameters:

  • package: Sets your app's package identifier. This can be modified after the app's creation, or in your config.xml file. Defaults to com.phonegap.www

  • version: Sets your app's version number. This can also be modified after the app's creation, or in your config.xml file. Defaults to 0.0.1

  • description: Sets your app's description. This can also be modified after creation, or in your config.xml file. Defaults to empty text.

  • debug: Builds your app in debug mode, as detailed in Remote Debugging Tools. Defaults to false.

  • keys: Set the signing keys to use for each platform you wish to sign. (See below for details.)

  • private: Whether your app can be publicly downloaded. Defaults to true.

  • tag: Which tag or branch to clone. Defaults to master.

  • share: Whether your private app can be publicly shared and viewed. Defaults to false.

  • phonegap_version: Which version of PhoneGap your app uses. See the Configuration Reference for details on which are supported, and which one is currently the default.

  • hydrates: Builds your app with hydration enabled, as described in Collaborating and Testing. Defaults to false.

create_method

A new app can be created from an archive file or from a remote git repository. You can choose which one of these to use by setting the create_method parameter in your JSON data.

The create method is immutable. An app created from a repository can never be changed to be file-backed, or vice versa. If you want to change at some later date, delete the old app and create a new one.

File-backed applications

To create a file-backed application, set the create_method parameter to file, and include a zip file (tar.gz) or an index.html file in the multipart body of your post, using file as a parameter name:

$ curl -F file=@/Users/alunny/index.html -u [email protected] -F 'data={"title":"API V1 App","package":"com.alunny.apiv1","version":"0.1.0","create_method":"file"}' https://build.phonegap.com/api/v1/apps
{
    "keys":{
        "ios":{
            "title":"ios-key",
            "default":true,
            "id":2,
            "link":"/api/v1/keys/ios/2"
         },
         "android":{
            "title":"release-key",
            "default":true,
            "id":2,
            "link":"/api/v1/keys/android/2"
         }
    },
    "download":{},
    "title":"API V1 App",
    "repo":null,
    "collaborators":[
        {
            "person":"[email protected]",
            "role":"admin"
        }
    ],
    "role":"admin",
    "id":26486,
    "icon":{
        "filename":null,
        "link":"/api/v1/apps/26486/icon"
    },
    "package":"com.alunny.apiv1",
    "version":"0.1.0",
    "description":null,
    "debug":false,
    "private":true,
    "share":false,
    "link":"/api/v1/apps/26486",
    "status":{
        "ios":"pending",
        "android":"pending",
        "winphone":"pending"
    },
    "error":{},
    "phonegap_version":"3.5.0",
    "hydrates":false,
    "build_count":null
}

Remote-repository backed applications

To create an app based on a remote repository, set the create_method parameter to remote_repo, and include a repo parameter with the repository's URL. Optionally include a tag parameter which indicates the branch or tag to pull from.

The URL has to be publicly accessible; PhoneGap Build does not authenticate against your repository. If you wish to keep your code private, use one of the other create_method options:

$ curl -u [email protected] -d 'data={"title":"API V1 App","repo":"https://github.com/alunny/phonegap-start.git", "tag":"master", "create_method":"remote_repo"}' https://build.phonegap.com/api/v1/apps
{
    "keys":{
        "ios":{
            "title":"ios-key",
            "default":true,
            "id":2,
            "link":"/api/v1/keys/ios/2"
         },
         "android":{
            "title":"release-key",
            "default":true,
            "id":2,
            "link":"/api/v1/keys/android/2"
         }
    },
    "download":{},
    "title":"alunnys Amazing App",
    "repo":"https://github.com/alunny/phonegap-start.git",
    "tag":"master",
    "collaborators":[
        {
            "person":"[email protected]",
            "role":"admin"
        }
    ],
    "role":"admin",
    "id":26488,
    "icon":{
        "filename":"blurry",
        "link":"/api/v1/apps/26488/icon"
    },
    "package":null,
    "version":null,
    "description":null,
    "debug":false,
    "private":true,
    "share":true,
    "link":"/api/v1/apps/26488,
    "status":{
        "ios":"pending",
        "android":"pending",
        "winphone":"pending"
    },
    "error":{},
    "phonegap_version":"3.5.0",
    "hydrates":false,
    "build_count":null
}

If you provide a repository URL that requires authentication, the response returns a 400 HTTP status code along with the error message in the body of the response:

$ curl -u [email protected] -d 'data={"title":"API V1 App","repo":"https://[email protected]/alunny/phonegap-start.git","create_method":"remote_repo"}' https://build.phonegap.com/api/v1/apps
{
    "error":"Private repository URLs not supported - try removing &quot;alunny@&quot;"
}

If your PhoneGap Build account is linked to your Github account, you will be able to pull from your private Github repositories. Other authenticated urls will fail as above.

Signing keys

To sign your builds on PhoneGap Build, you must first upload one or more keys, through the POST https://build.phonegap.com/api/v1/keys method, or through the web interface. You can get a list of all the keys associated with your account by sending a GET request to the same URL.

In the data JSON hash that you send to the build server, you can specify the keys, per platform, by id, that you wish to use for this build.

The value for each platform can be the integer id, such as:

"keys":{"ios":123}

or an object, containing the password field, or the key_pw and keystore_pw fields for Android, such as:

"keys":{"ios":{"id":123,"password":"password1"}

Using the second form allows you to unlock the given key, without making a separate PUT request to https://build.phonegap.com/v1/keys/ios/123

Here is a sample post, using the first form:

$ curl -u [email protected] -d 'data={"title":"Signing Keys","repo":"https://github.com/alunny/phonegap-start.git","create_method":"remote_repo","keys":{"ios":123,"android":567,"winphone":72}}' https://build.phonegap.com/api/v1/apps
{
    "keys":{
        "ios":{
            "title":"new iOS key",
            "default":false,
            "id":123,
            "link":"/api/v1/keys/ios/123"
         },
         "android":{
            "title":"some android key",
            "default":false,
            "id":567,
            "link":"/api/v1/keys/android/567"
         },
         "winphone":{
             "id": 72,
             "title": "Windows Publisher Key",
             "link": "/api/v1/keys/winphone/72",
             "default": false
         }
    },
    "download":{},
    "title":"Remote Application",
    "repo":"https://github.com/phonegap/phonegap-start.git",
    "collaborators":[
        {
            "person":"[email protected]",
            "role":"admin"
        }
    ],
    "role":"admin",
    "id":36500,
    "icon":{
        "filename":"null",
        "link":"/api/v1/apps/36500/icon"
    },
    "package":null,
    "version":null,
    "description":null,
    "debug":false,
    "private":true,
    "link":"/api/v1/apps/36500,
    "status":{
        "ios":"pending",
        "android":"pending",
        "winphone":"pending"
    },
    "error":{},
    "phonegap_version":"3.5.0",
    "hydrates":false,
    "build_count":null
}

PUT https://build.phonegap.com/api/v1/apps/:id

Update an existing app, either its contents, its build settings, or both. The response is a JSON representation of the app, the same as for GET /api/v1/apps/:id.

App metadata like title, description and version should be updated via the config.xml file. Updating the build settings involves sending a JSON object as the parameter data. Available options in this JSON object are:

  • debug: whether to build your app in debug mode, as detailed in Remote Debugging Tools.

  • private: whether the app has restricted visibility.

  • share: whether the private app can be publicly viewed.

  • tag: which branch or tag to clone from the git repository.

Here is a simple example that update an app's version number:

$ curl -u [email protected] -X PUT -d 'data={"version":"0.2.0"}' https://build.phonegap.com/api/v1/apps/8
{
    "id":8,
    "version":"0.2.0",
    "keys":{
        "ios":null,
        "android":null
    },
    "repo":null,
    "download":{},
    "collaborators":[
        {
            "person":"[email protected]",
            "role":"admin"
        }
    ],
    "title":"App From API",
    "role":"admin",
    "icon":{
        "filename":null,
        "link":"/api/v1/apps/8/icon"
    },
    "package":null,
    "link":"/api/v1/apps/8",
    "debug":false,
    "private":true,
    "share":true,
    "description":null,
    "status":{
        "winphone":"pending",
        "ios":null,
        "android":"pending",
    },
    "error":{},
    "phonegap_version":"3.5.0",
    "hydrates":false,
    "build_count":12
}

By default, the app is built for all supported platforms once the metadata changes.

App Signing Keys

As with creating a new app, you can specify a signing key to use for each platform that you wish to build for. You can also put a key's credentials, which ensures the key is unlocked and ready to use.

This sample post selects a new Android key for an app, and unlocks it:

$ curl -u [email protected] -X PUT -d 'data={"keys":{"android": {"id":457,"key_pw":"password1","keystore_pw":"password2"}}' https://build.phonegap.com/api/v1/apps/36500

{
    "keys":{
        "ios":{
            "title":"new iOS key",
            "default":false,
            "id":123,
            "link":"/api/v1/keys/ios/123"
         },
         "android":{
            "title":"changed android key",
            "default":false,
            "id":457,
            "link":"/api/v1/keys/android/457"
         }
    },
    "download":{},
    "title":"Remote Application",
    "repo":"https://github.com/phonegap/phonegap-start.git",
    "collaborators":[
        {
            "person":"[email protected]",
            "role":"admin"
        }
    ],
    "role":"admin",
    "id":36500,
    "icon":{
        "filename":"null",
        "link":"/api/v1/apps/36500/icon"
    },
    "package":null,
    "version":null,
    "description":null,
    "debug":false,
    "private":true,
    "link":"/api/v1/apps/36500,
    "status":{
        "ios":"pending",
        "android":"pending",
        "winphone":"pending"
    },
    "error":{},
    "phonegap_version":"3.5.0",
    "hydrates":false,
    "build_count":null
}

Updating a file-based application

If the application has been created from a file upload, you can include a new index.html, zip, or tar.gz file as the file parameter in your request to update the contents:

$ curl -u [email protected] -X PUT -F file=@/Users/alunny/new/index.html https://build.phonegap.com/api/v1/apps/8

Updating a repo-based application

To update an application from a remote repository, simply add the pull field to your data hash, and set it to true:

$ curl -u [email protected] -X PUT -d 'data={"pull":"true"}' https://build.phonegap.com/api/v1/apps/8

PhoneGap Build then tries to download the new code from your remote repository, and rebuilds your app for all supported platforms.

POST https://build.phonegap.com/api/v1/apps/:id/build

Queue new builds for a specified app. The older builds are discarded, while new ones are queued.

The builds will use the most current app contents, as well as the selected signing keys. The response have a 202 (accepted) status:

$ curl -u [email protected] -X POST -d '' https://build.phonegap.com/api/v1/apps/12/build

To choose which platforms to build, include them as a JSON encoded parameter:

$ curl -u [email protected] -X POST -d 'data={"platforms":["android"]}' https://build.phonegap.com/api/v1/apps/12/build

Once the builds are queued, you will want to watch the results of GET /api/v1/apps/:id to check when each platform's status changes from pending to either complete or error.

POST https://build.phonegap.com/api/v1/apps/:id/build/:platform

A simpler URL to build for a single platform:

$ curl -u [email protected] -X POST -d '' https://build.phonegap.com/api/v1/apps/12/build/android

POST https://build.phonegap.com/api/v1/apps/:id/collaborators

Add a collaborator to work with you on a given application. You must be the app's owner/admin to do so.

Required parameters:

  • email: The email address of your new collaborator.

  • role: The new collaborator's level of access: either tester (read-only) or dev (read and write).

If the user is on the system, a 201 (created) HTTP status code results, which lets you know that the user can now access your app. If the user is not registered, a 202 (accepted) status results, and the collaboration is listed as pending.

A JSON representation of the affected app returns after the collaboration is added:

$ curl -u [email protected] -d 'data={"email":"[email protected]","role":"dev"}' https://build.phonegap.com/api/v1/apps/12/collaborators
{
    "id":12,
    "title":"App With Collaborators",
    "collaborators":{
        "link":"/api/v1/apps/9/collaborators",
        "pending":[
            {
                "person":"[email protected]",
                "role":"developer"
            },
            {
                "person":"[email protected]",
                "role":"tester"
            }
        ],
        "active":[
            {
                "person":"[email protected]",
                "role":"admin",
                "id":9,
                "link":"/api/v1/apps/9/collaborators/9"
            },
            {
                "person":"[email protected]",
                "role":"developer",
                "id":13,
                "link":"/api/v1/apps/9/collaborators/13"
            }
        ]
    },
    "package":"app.with.collaborators",
    ...
}

PUT https://build.phonegap.com/api/v1/apps/:id/collaborators/:id

Allows you to change the role for a particular collaborator on PhoneGap Build, either to dev or tester.

If you are not the owner of an app, a 401 unauthorized response results. You cannot change the email of a collaborator; attempts to do so return a 400 status:

$ curl -u [email protected] -d 'data={"role":"tester"}' -X PUT https://build.phonegap.com/api/v1/apps/12/collaborators/13
{
    "id":13,
    "person":"[email protected]",
    "role":"tester",
    "app":{
        "id":12,
        "download":{},
        "title":"My App",
        "role":"admin",
        "icon":{
            "filename":null,
            "link":"/api/v1/apps/12/icon"
        },
        "version":null,
        "package":null,
        "description":null,
        "debug":null,
        "link":"/api/v1/apps/12",
        "status":{
          "ios":"pending",
          "android":"pending",
          "winphone":"pending"
        },
        "phonegap_version":"3.5.0",
        "hydrates":false,
        "build_count":null,
        "error":{}
    },
    "link":"/api/v1/apps/12/collaborators/13"
}

POST https://build.phonegap.com/api/v1/keys/:platform

Add a signing key to your PhoneGap Build account. The platform parameter has to be specified in the URL, and different files are required depending on the platform you're targeting.

iOS Signing Keys

The following are required for iOS builds:

  • a p12 certificate file
  • a mobileprovision file
  • the password to access your certificate (optional)
  • a title for your certificate-profile pair

Details on how to obtain these files are in our iOS Signing documentation.

A sample post would look like this:

$ curl -u [email protected] -F cert=@My_Certificate.p12 -F [email protected] -F 'data={"title":"Developer Cert","password":"12345678"}' https://build.phonegap.com/api/v1/keys/ios
{
  "title":"Developer Cert",
  "default":false,
  "id":11,
  "link":"/api/v1/keys/ios/11",
  "provision":"meandmyteam.mobileprovision",
  "cert_name":"My_Certificate.p12",
  "role":"developer",
  "locked":false
}

If you omit the password parameter, your key is locked after the upload completes. You won't be able to build with it until you unlock the key.

Android Keys

The following are required for Android builds:

  • a keystore file
  • the alias used for that keystore
  • your keystore password (keystore_pw) (optional)
  • your private key password (key_pw) (optional)
  • a title for your key

Details on how to get your keystore file and the associated data are available in our Android Code Signing documentation.

Here is a sample post:

$ curl -u [email protected] -F [email protected] -F 'data={"title":"Android Key","alias":"release", "key_pw":"90123456","keystore_pw":"78901234"}' https://build.phonegap.com/api/v1/keys/android
{
    "title":"Android Key",
    "default":false,
    "id":2,
    "alias":"release",
    "link":"/api/v1/keys/android/2",
    "locked":false
}

If you omit one or both of the key_pw and keystore_pw parameters, your key is locked after the upload. You won't be able to build with it until you unlock the key.

Windows Phone Keys

The following are required for Windows Phone builds:

  • a title for your key
  • the publisher id from your Windows Phone store account.

Here is a sample post:

$ curl -u [email protected] -F 'data={"title":"Winphone Key","publisher_id":"04739CCE-16E5-4680-8644-0004225CBCF6"}' https://build.phonegap.com/api/v1/keys/winphone
{
  "title":"Winphone Key",
  "default":false,
  "id":72,
  "link":"/api/v1/keys/winphone/72",
}

If you omit one or both of the key_pw and keystore_pw parameters, your key is locked after the upload. You won't be able to build with it until you unlock the key.

PUT https://build.phonegap.com/api/v1/keys/:platform/:id

Updates an existing signing key on PhoneGap Build, used to unlock a signing key so it can be used for future builds. To unlock a key, you need to provide the appropriate credentials: a single password for iOS or two passwords for Android, one for the key, and one for the keystore.

NOTE: PhoneGap Build does not verify your key's password. If incorrect, an error results when you try to build with that key.

  • iOS example:

    $ curl -u [email protected] -d 'data={"password":"password1"}' -X PUT https://build.phonegap.com/api/v1/keys/ios/11
{
  "title":"Developer Cert",
  "default":false,
  "id":11,
  "link":"/api/v1/keys/ios/11",
  "provision":"meandmyteam.mobileprovision",
  "cert_name":"My_Certificate.p12",
  "role":"developer",
  "locked":false
}

  • Android example:

    $ curl -u [email protected] -d 'data={"key_pw":"password1","keystore_pw":"password2"}' -X PUT https://build.phonegap.com/api/v1/keys/android/2
{
    "title":"Android Key",
    "default":false,
    "id":2,
    "alias":"release",
    "link":"/api/v1/keys/android/2",
    "locked":false
}

DELETE https://build.phonegap.com/api/v1/apps/:id

Delete your application from PhoneGap Build, returning either a 202 (accepted) status, or 404 (if the app cannot be found):

$ curl -u [email protected] -X DELETE https://build.phonegap.com/api/v1/apps/8
{
    "success":"app 8 deleted"
}

DELETE https://build.phonegap.com/api/v1/apps/:id/collaborators/:id

Remove a collaborator from a project that you own:

$ curl -u [email protected] -X DELETE https://build.phonegap.com/api/v1/apps/12/collaborators/13
{
    "success":"[email protected] removed from app 9"
}

DELETE https://build.phonegap.com/api/v1/keys/:platform/:id

Delete a signing key from PhoneGap Build, returning either a 202 (accepted) status, or 404 (if the key cannot be found):

$ curl -u [email protected] -X DELETE https://build.phonegap.com/api/v1/keys/android/8
{
    "success":"android key 8 deleted"
}

Sources & archive notes

Recovered repository material is attributed to its original authors and distributed with its source license. Changes: FreeSoft layout, archive context, navigation, link and image locations. Apache License 2.0 · Notices and provenance. Editorial material is labeled separately.