BuildMaster Documentation

Release & Build Deployment

API Usage

All of these endpoints require that an API Key with Release & Build Deployment access is passed into each request. The examples use a query string for simplicity, but you could also use a header, form value, or JSON property. See Using API Keys for more information.

Data Specification

This endpoint receives data entirely as key/value parameters and sends data using the following JSON objects:

Release

Build

Deployment

Property

Format

id

An integer representing the system-unique identifier of the release.

number

A string representing the application-unique identifier of the release.

name

A string representing the non-unique name or alias for the release.

sequence

An integer representing the sequence relative to other releases in the application.

template

A string of the template name used for this release, or null if no template is used.

status

A string consisting of active, deployed, or canceled.

createdBy

A string representing the user who created the release, or SYSTEM if created non-interactively.

createdOn

A string representing the UTC date when the release was created, in ISO 8601 format (yyyy-MM-ddThh:mm:ss).

canceledBy

A string representing the user who canceled the release, or SYSTEM if created non-interactively.

canceledOn

A string representing the UTC date when the release was created, in ISO 8601 format (yyyy-MM-ddThh:mm:ss).

targetDate

A string representing the UTC date of the target release date in ISO 8601 format (yyyy-MM-ddThh:mm:ss).

applicationId

An integer representing the system-unique identifier of the application for the release.

applicationName

A string representing the system-unique name of the application for the release.

pipelineId

An integer representing the system-unique identifier of the pipeline used by the release.

pipelineName

A string representing the name of the pipeline used by the release.

furthestBuildId

An integer representing the system-unique identifier of the active or deployed build that has made it furthest in the pipeline for the release.

furthestBuildNumber

A string representing the application-unique number of the active or deployed build that has made it furthest in the pipeline for the release.

latestBuildId

An integer representing the system-unique identifier of the active or deployed build that was most recently created.

latestBuildNumber

A string representing the application-unique number of the active or deployed build that was most recently created.

Property

Format

id

An integer representing the system-unique identifier of the build.

number

A string representing the release-unique identifier of the build.

status

A string consisting of active, deployed, or rejected.

createdBy

A string representing the user who created the build, or SYSTEM if created non-interactively.

createdOn

A string representing the UTC date when the build was created, in ISO 8601 format (yyyy-MM-ddThh:mm:ss).

rejectedBy

A string representing the user who rejected the build, or SYSTEM if rejected non-interactively.

rejectedOn

A string representing the UTC date when the build was rejected, in ISO 8601 format (yyyy-MM-ddThh:mm:ss).

pipelineId

An integer representing the system-unique identifier of the pipeline used by the build.

pipelineName

A string representing the name of the pipeline used by the build.

furthestStage

A string representing the name the furthest stage the build has advanced to in the pipeline.

applicationId

An integer representing the system-unique identifier of the application for the build.

applicationName

A string representing the system-unique name of the application for the build.

releaseId

An integer representing the system-unique identifier of the release for the build.

releaseNumber

A string representing the application-unique number of the release for the build.

releaseName

A string representing the name of the release for the build.

Property

Format

id

An integer representing the system-unique identifier of the deployment.

plan

A string representing the name of the plan used for deployment.

status

A string consisting of
pending,
executing,
succeeded,
warned, or
failed

started

A string representing the UTC date when the deployment actually started, in ISO 8601 format (yyyy-MM-ddThh:mm:ss), or null if the execution hasn't started.

ended

A string representing the UTC date when the deployment completed, in ISO 8601 format (yyyy-MM-ddThh:mm:ss), or null if the execution hasn't completed.

createdBy

A string representing the user who initiated the deployment, or SYSTEM if initiated non-interactively.

createdOn

A string representing the UTC date when the deployment was initiated, in ISO 8601 format (yyyy-MM-ddThh:mm:ss).

canceledBy

A string representing the user who canceled the deployment (SYSTEM if canceled non-interactively), or null if the deployment was not canceled.

canceledOn

A string representing the UTC date when the deployment was canceled, in ISO 8601 format (yyyy-MM-ddThh:mm:ss), or null if the deployment was not canceled.

pipelineId

An integer representing the system-unique identifier of the pipeline used by the deployment.

pipelineName

A string representing the name of the pipeline used by the deployment.

pipelineStageName

A string representing the name the stage in the pipeline used by the deployment.

environmentId

An integer representing the system-unique identifier of the environment used by the deployment, or null if no environment is in context.

environmentName

A string representing the name of the environment used by the deployment, or null if no environment is in context.

applicationId

An integer representing the system-unique identifier of the application for the deployment.

applicationName

A string representing the system-unique name of the application for the deployment.

releaseId

An integer representing the system-unique identifier of the release for the deployment.

releaseNumber

A string representing the application-unique number of the release for the deployment.

releaseName

A string representing the name of the release for the deployment.

buildId

An integer representing the system-unique identifier of the build for the deployment.

buildNumber

A string representing the release-unique number of the build for the deployment.

Endpoint Specifications

This endpoint receives data entirely as key/value parameters, which may be specified in both the querystring and body (application/x-www-form-urlencoded); duplicate keys will result in an failed request (400 status).

Get Releases

GET or POST /api/releases

Returns a status of 200 and a body with an array of release objects based on the specified optional filter parameters:

Filter

Parameter Specification

Application

Either a key named applicationId with an integer value, or a key named applicationName with any value.

Release

Either a key named releaseId with an integer value, a key named releaseNumber with any value, or a key named releaseName with any value.

Pipeline

Either a key named pipelineId with an integer value, or a key named pipelineName with any value.

Status

A key named status with a value of active, canceled, or deployed.

This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.

Create Release

POST or PUT /api/releases/create

Returns a status of 200 and a body with a release object that was created with the following input parameters:

Input

Parameter Specification

Application

Required. Either a key named applicationId with an integer value, or a key named applicationName with any value.

Release Number

Required. A key named releaseNumber with any value.

Pipeline

Required. Either a key named pipelineId with an integer value, or a key named pipelineName with any value.

Release Name

Optional. A key named releaseName with any value.

Variables

Optional. Any number of parameters with a key name consisting of a valid variable name prefixed with $, and with any value.

This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.

Create Release from Template

POST or PUT /api/releases/create-from-template

Returns a status of 200 and a body with a release object that was created with the following input parameters:

Input

Parameter Specification

Application

Required. Either a key named applicationId with an integer value, or a key named applicationName with any value.

Release Number

Required. A key named releaseNumber with any value.

Template

Required. A key named template with any value.

Release Name

Optional. A key named releaseName with any value.

Variables

Optional. Any number of parameters with a key name consisting of a valid variable name prefixed with $, and with any value.

This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.

Cancel Release

POST or PUT /api/releases/cancel

Returns a status of 200 if the release was canceled:

Input

Parameter Specification

Release

Required. Either a key named releaseId with an integer value, or a key named releaseNumber with any value.

Application

Required if releaseNumber is specified, otherwise must not be set. Either a key named applicationId with an integer value, or a key named applicationName with any value.

Reason

Optional. A key named reason with any value.

This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.

Restore Release

POST or PUT /api/releases/restore

Returns a status of 200 if the release was restored:

Input

Parameter Specification

Release

Required. Either a key named releaseId with an integer value, or a key named releaseNumber with any value.

Application

Required if releaseNumber is specified, otherwise must not be set. Either a key named applicationId with an integer value, or a key named applicationName with any value.

This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.

Get Builds

GET or POST /api/releases/builds

Returns a status of 200 and a body with an array of build objects based on the specified optional filter parameters:

Filter

Parameter Specification

Application

Either a key named applicationId with an integer value, or a key named applicationName with any value.

Release

Either a key named releaseId with an integer value, a key named releaseNumber with any value, or a key named releaseName with any value.

Build

Either a key named buildId with an integer value, or a key named buildNumber with any value.

Pipeline

Either a key named pipelineId with an integer value, or a key named pipelineName with any value.

Stage

A key named furthestStage with any value.

Status

A key named status with a value of active, rejected, or deployed.

This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.

Create Build

POST or PUT /api/releases/builds/create

Returns a status of 200 and a body with a build object that was created with the following input parameters:

Input

Parameter Specification

Release

Required. Either a key named releaseId with an integer value, or a key named releaseNumber with any value.

Application

Required if releaseNumber is specified, otherwise must not be set. Either a key named applicationId with an integer value, or a key named applicationName with any value.

Build Number

Optional. A key named buildNumber with any value; if not specified, the build number will be automatically generated.

Variables

Optional. Any number of parameters with a key name consisting of a valid variable name prefixed with $, and with any value.

This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.

Get Deployments

GET or POST /api/releases/builds/deployments

Returns a status of 200 and a body with an array of deployment objects based on the specified optional filter parameters:

Filter

Parameter Specification

Application

Either a key named applicationId with an integer value, or a key named applicationName with any value.

Release

Either a key named releaseId with an integer value, a key named releaseNumber with any value, or a key named releaseName with any value.

Build

Either a key named buildId with an integer value, or a key named buildNumber with any value.

Deployment

A key named deploymentId with an integer value.

Pipeline

Either a key named pipelineId with an integer value, or a key named pipelineName with any value.

Stage

A key named pipelineStageName with any value.

Environment

Either a key named environmentId with an integer value, or a key named environmentName with any value.

Status

A key named status with a value of pending, executing, succeeded, warned, or failed.

This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.

Deploy Build

POST or PUT /api/releases/builds/deploy

Returns a status of 200 and a body with an array of deployment objects that were created with the following input parameters:

Input

Parameter Specification

Build

Required. Either a key named buildId with an integer value, or a key named buildNumber with any value.

Release

Required if buildNumber is specified, otherwise must not be set. Either a key named releaseId with an integer value, or a key named releaseNumber with any value.

Application

Required if releaseNumber is specified, otherwise must not be set. Either a key named applicationId with an integer value, or a key named applicationName with any value.

To Stage

Optional. A key named toStage with any value. If not supplied, the next stage in the pipeline will be used.

Force

Optional. A key named force with a value of true or false.

Start Time

Optional. A key named startTime with the timestamp when the deployment should start. If not supplied, the deployment will start immediately. If the timestamp does not contain a date, it defaults to today. If a date is specified without a time, it defaults to midnight. If there is no time zone specified, it defaults to the server's local time zone.
Available in BuildMaster 6.0.2+

Variables

Optional. Any number of parameters with a key name consisting of a valid variable name prefixed with $, and with any value.

This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.

Reject Build

POST or DELETE /api/releases/builds/reject

Returns a status of 200 if the build was rejected:

Input

Parameter Specification

Build

Required. Either a key named buildId with an integer value, or a key named buildNumber with any value.

Release

Required if buildNumber is specified, otherwise must not be set. Either a key named releaseId with an integer value, or a key named releaseNumber with any value.

Application

Required if releaseNumber is specified, otherwise must not be set. Either a key named applicationId with an integer value, or a key named applicationName with any value.

This may also return a status of 400 (invalid parameters) or 403 (invalid key) as well as an error message as the body.