BuildMaster Release & Build Deployment API
The Release & Build Deployment API offers a simple mechanism for creating releases, creating builds, and deploying builds.
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 a failed request (400 status).
All API endpoints are accessed through the following base URL:
/api/releases/...
🚀 Releases Endpoints
Create Release - Creates a release
Get Releases - Returns a list of all releases
Restore Release - Restores a release
Cancel Release - Cancels a release
🛠 Builds Endpoints
Create Build - Creates a build
Deploy Build - Deploys a build
Get Build - Returns a list of all builds
Reject Build - Rejects a build
⚙ Deployments Endpoint
Get Deployments - Returns a list of all deployments
Authentication
An API Key with the Release & Build Deployment permission is required to use this API.
It can be passed to each endpoint in one of four ways, depending on the content type of the expected request:
| Method | Name or Key | Details |
|---|---|---|
| Request header | X-ApiKey |
all content types |
| Querystring value | key |
all content types |
| Form value | key |
only applications/x-www-form-urlencoded content type |
| JSON property | API_Key |
on root object, only application/json content type |
To specify an API Key, use the request header (X-ApiKey), querystring (key), or api:«api-key» as the user name. See API Access and API Key to learn more.
For example, to authenticate with the API key a1b2c3d4e5 to the create build endpoint, you could specify the API key as follows:
curl -X POST -H "X-ApiKey: a1b2c3d4e5" "/api/releases/builds/create"
If the provided API key is either missing, unknown/incorrect or does not have permission, the following message is returned:
The specified API key does not have the proper permissions to perform this action.
Data Specifications
In BuildMaster 6.1 and earlier, these data objects contained a pipelineId which was an integer identifier for the pipeline used by the release. However, since BuildMaster 6.2, pipelines are stored in raft repositories (which can be a zip file or a git repository) and therefore no longer have a native identifier.
ReleaseInfo Object Properties
ReleaseInfo is a set of key/value pairs that correspond to the fields on a Release. It's used as output data for the Create Release and Get Releases endpoints, returning ReleaseInfo as a JSON-formatted object.
| Property | Format |
|---|---|
id |
An integer representing the system-unique identifier of the release. |
releaseNumber |
A string representing the application-unique identifier of the release. |
releaseName |
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. |
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. |
JSON Object
{
"id": 1,
"number": "1.0.1",
"name": "1.0.1",
"sequence": 1,
"status": "active",
"createdBy": "MikeJones",
"createdOn": "2024-03-04T09:03:43.9200000Z",
"applicationId": 1,
"applicationName": "ProfitCalculator",
"pipelineName": "Release",
"furthestBuildId": 3,
"furthestBuildNumber": "2",
"latestBuildId": 3,
"latestBuildNumber": "2",
"deployables": [],
"furthestPackageId": 3,
"furthestPackageNumber": "2",
"latestPackageId": 3,
"latestPackageNumber": "2",
"releaseName": "1.0.1",
"releaseNumber": "1.0.1"
}
BuildInfo Object Properties
BuildInfo is a set of key/value pairs that correspond to the fields on a Build. It's used as output data for the Create Build and Get Build endpoints, returning BuildInfo as a JSON-formatted object.
| Property | Format |
|---|---|
id |
An integer representing the system-unique identifier of the build. |
buildNumber |
A string representing the build-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). |
pipelineName |
A string representing the name of the pipeline used by the build. |
furthestStage |
A string representing the name of 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. |
JSON Object
{
"id": 1,
"number": "3",
"status": "active",
"createdBy": "API",
"createdOn": "2024-03-05T02:46:56.0800000Z",
"applicationId": 2,
"applicationName": "TaxCalculator",
"pipelineName": "Release",
"releaseId": 4,
"releaseNumber": "1.0.1",
"releaseName": "1.0.1",
"buildNumber": "3"
}
DeploymentInfo Object Properties
DeploymentInfo is a set of key/value pairs that correspond to the fields on a Release. It's used as both input and output data for the Deploy Build and Get Deployments endpoints, returning DeploymentInfo as a JSON-formatted object.
| 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. |
pipelineName |
A string representing the name of the pipeline used by the deployment. |
pipelineStageName |
A string representing the name of 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. |
{
"id": 1,
"plan": "Deploy",
"status": "succeeded",
"started": "2024-03-04T09:31:20.5100000Z",
"ended": "2024-03-04T09:31:20.6100000Z",
"createdBy": "SYSTEM",
"createdOn": "2024-03-04T09:31:15.4900000Z",
"pipelineName": "Release",
"pipelineStageName": "Integration",
"applicationId": 1,
"applicationName": "TaxCalculator",
"releaseId": 1,
"releaseNumber": "1.0.1",
"releaseName": "1.0.1",
"buildId": 1,
"buildNumber": "2",
"packageId": 1,
"packageNumber": "2"
}