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 andrew.lunny@nitobi.com -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":"andrew.lunny@nitobi.com",
            "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 andrew.lunny@nitobi.com -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":"andrew.lunny@nitobi.com",
            "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 andrew.lunny@nitobi.com -d 'data={"title":"API V1 App","repo":"https://alunny@github.com/alunny/phonegap-start.git","create_method":"remote_repo"}' https://build.phonegap.com/api/v1/apps
{
    "error":"Private repository URLs not supported - try removing "alunny@""
}

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 andrew.lunny@nitobi.com -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":"andrew.lunny@nitobi.com",
            "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 andrew.lunny@nitobi.com -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":"andrew.lunny@nitobi.com",
            "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 andrew.lunny@nitobi.com -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":"andrew.lunny@nitobi.com",
            "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 andrew.lunny@nitobi.com -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 andrew.lunny@nitobi.com -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 andrew.lunny@nitobi.com -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 andrew.lunny@nitobi.com -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 andrew.lunny@nitobi.com -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 andrew.lunny@nitobi.com -d 'data={"email":"newguy@nitobi.com","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":"newguy@nitobi.com",
                "role":"developer"
            },
            {
                "person":"nobody@nitobi.com",
                "role":"tester"
            }
        ],
        "active":[
            {
                "person":"admin@nitobi.com",
                "role":"admin",
                "id":9,
                "link":"/api/v1/apps/9/collaborators/9"
            },
            {
                "person":"foo@bar.com",
                "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 andrew.lunny@nitobi.com -d 'data={"role":"tester"}' -X PUT https://build.phonegap.com/api/v1/apps/12/collaborators/13
{
    "id":13,
    "person":"foo@bar.com",
    "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 andrew.lunny@nitobi.com -F cert=@My_Certificate.p12 -F profile=@MyDevices.mobileprovision -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 andrew.lunny@nitobi.com -F keystore=@android.keystore -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 andrew.lunny@nitobi.com -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 andrew.lunny@nitobi.com -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 andrew.lunny@nitobi.com -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 andrew.lunny@nitobi.com -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 andrew.lunny@nitobi.com -X DELETE https://build.phonegap.com/api/v1/apps/12/collaborators/13
{
    "success":"foo@bar.com 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 andrew.lunny@nitobi.com -X DELETE https://build.phonegap.com/api/v1/keys/android/8
{
    "success":"android key 8 deleted"
}
Edit this page on GitHub

Looking for more help?

If you're having issues that aren't solved here, be sure to check out the following:

PhoneGap Forum

PhoneGap/Cordova community forum to use for finding info and posting issues.
Go to the forum

Stackoverflow

For PhoneGap specific questions.
Get the answers

Meetup.com

Consider finding (or starting) a local Cordova/PhoneGap meetup group.
See what's happening