Notice: This resource is no longer being actively maintained and as a result some information may be out of date or inaccurate. Please see for technical instructions or for support related concerns.
RUN@cloud » CloudBees API

CloudBees API

Last modified by Michael Neale on 2013/01/15 22:22

The Query API is a HTTP-based programming interface that provides operations for managing the CloudBees services and resources.

An example implementation of this can be found here


The query api described here is not really a "RESTful" api - the best example of how it works is in the code: If you are consuming this api from any JVM language, it is recommended to do that. We do have plans for a full RESTful style api in future covering a wider set of features. 

API Actions


Deploys an application archive using the specified app_id. If the application ID does not exist, it will be created.

Note: this method uploads files, so it uses the HTTP multipart/form-data content type instead of application/form-url-encoded.


  • app_id* - fully qualified application id (format: username/appname)
  • archive* - archive file content
  • archive_type* - type of the archive. Expected values: ear or war
  • description - deployment description
  • environment - config environment to use when running the application
  • src - optional archive source (makes the source available for download to application members)
  • parameters - JSON object for non-standard config parameters
    • containerType - the type of application container (valid values: jboss or tomcat)

Deletes an application


  • app_id* - fully qualified application id (format: username/appname)

Returns basic information about an application (id, title, create date, status, urls)


  • app_id* - fully qualified application id (format: username/appname)

Returns a list of the applications that the authenticated requestor is a member of.

Parameters: none


Redeploys the specified application using the currently active snapshot.


  • app_id* - fully qualified application id (format: username/appname)

Updates the application metadata fields


  • app_id* - fully qualified application id (format: username/appname)
  • title* - the application title

Starts a stopped application


  • app_id* - fully qualified application id (format: username/appname)

Undeploys an application from all servers, and displays a "service unavailable" message for inbound application requests.


  • app_id* - fully qualified application id (format: username/appname)
  • reason - description of why the application was stopped

Creates a new MySQL database


  • domain - the account/domain name
  • database_id* - the database name (must be unique)
  • database_password* - the database password
  • database_username* - the database username

Deletes a MySQL database


  • database_id* - the database name

Retrieves the basic info about a database (owner, username, password, create date, status, host, port)


  • database_id* - the database name (must be unique)
  • fetch_password - optionally fetch the database password. Expected values: true or false. Default is false.

Returns the list of databases available to the authenticated requestor.

Parameters: none

Using the API

Query requests are GET or POST HTTP requests that are composed of:

    a set of common parameters that must be specified in all requests (see common query parameters below)
    a parameter named action (see [api:actions])
    a set parameters supported by the specified action.

The HTTP endpoint for all requests is:

Common Query parameters

All Query API requests support a common set of parameters that are used to setup various aspects of the query invocation.

    api_key (required) - ID assigned by CloudBees for api requests. For the 0.1 version of the API, this is your CloudBees username.
    format (optional, default: xml) - the format of the result. Currently, only the xml format is supported.
    sig - the authentication signature of the request. See 'Query API authentication' below to calculate this value.
    sig_version (required) - the version of the signature algorithm used to sign the request (expected value: 1)
    timestamp (required) - the time that the query was generated formatted as the number of seconds since Jan 1, 1970 UTC.
    v (required) - the version of the api being used (expected value: 0.1)

Query API Authentication

The CloudBees Query API supports two forms of authentication:

  • OAuth authentication
  • Signed URLs

OAuth authentication (for registered OAuth Client Apps only)

If you have registered an OAuth client app with CloudBees, you were assigned a Client ID and Secret.  This can be used to obtain OAuth tokens that can be used to impersonate the user who is accessing your application.  To use OAuth with the CloudBees API, your application must obtain a token with one or more of the following scopes:

  • - scope with authority to make all CloudBees API calls.  [Note that this is a very powerful scope, that many users will not allow]
  • ...more scopes with reduced privileges will be available soon 

Once your application obtains an API-scoped OAuth token, you can sent HTTPS requests to the API using the Bearer authentication scheme.  This scheme relies on the standard HTTP Authorization header,with a type of 'Bearer' and a value which is the Base64-encoded version of the user's OAuth token obtained by your application.

The following is an example of a curl command that uses the Bearer authentication scheme:
curl -H "Authorization: Bearer BASE64_ENCODED_TOKEN"

Signed URLs

Signed requests to the query API include a signature parameter which is used to validate that the request was generated by a sender that knows the secret associated with the API key. The method for creating the signature is as follows:

  • Calculate the signature input string
    • Gather the list of query parameters that will be used in the request query string or POST body (this includes the query action parameters and the default parameters required for every query API request, with the exception of the sig parameter, which is being calculated)
    • Sort all query parameters by parameter name    
    • Create the signature string by concatenating the sorted name/value pairs
  • Generate the signature value
    • Create an MD5 hash of the signature input string + your  API secret
    • Convert the resulting hash bytes to base64
    • Use the resulting value as the sig request parameter

Whenever a query API request is received by the server, the server will calculate the signature for the request based upon this same method, using the secret associated with the api_key included in the request. If the signature sent by the client does not match the signature calculated by the server, then the request will be rejected

Java Example

see here

Created by Spike Washburn on 2011/07/20 03:07