Support & Documentation

Deployment Tracking: API Code Samples

The ClientWebAPI exposes command endpoints that can start, complete, or cancel a deployment request.A Deployment Request is applied to an app environment at the specified version. The app environment is identified by the string keys AppName and EnvironmentName. The deployment request Version is also an identifying string. When evaluating the current state of a deployment request, it will be located by these three strings. We do some basic validation to ensure deployment requests do not violate the allowed state transitions. An example of an invalid deployment request would be to send a cancel command for an app environment that does not already have a pending start request at the same version.

Deployment requests are processed by the client 5 min maintenance job. All requests with a status of completed will result in the creation of a Deployment record which will then be visible to clients in the Retrace UI.



Authentication is performed by setting the request authorization header in the following format, where ApiKey is the client's specific activation key. 

Authorization: ApiKey {API_KEY}


Example Bash (cURL) API Requests

Start Deployment (Bash)

curl -X POST \ \

 -H 'authorization: ApiKey GwsN94G6zUmH1x7f8qPCBYlnMUdN6YRay4bYWTBjIm' \

 -H 'content-type: application/json' \

 -d '{

   "Name": "BourneAgain",

   "Uri": "localhost",

   "Branch": "master",

   "Commit": "rOapzPyAtzUR9s7yDJYlGz2vUYbcl0P6gMVglrygJ2",

   "Version": "v1.0",

   "AppName": "FooApp",

   "EnvironmentName": "Prod"


Complete Deployment (Bash)

curl -X POST \ \

 -H 'authorization: ApiKey cb9pHw629iE8RSc5lom5AXvZWdRLwkunPy4WdqbAMZ' \

 -H 'content-type: application/json' \

 -d '{

   "Version": "v1.0",

   "AppName": "FooApp",

   "EnvironmentName": "Prod"


Cancel Deployment (Bash)

curl -X POST \ \

 -H 'authorization: ApiKey 3hxOisvOpzFUaYKN3h9nzsVXXLrjehUi1IlsacP3TZ' \

 -H 'content-type: application/json' \

 -d '{

   "Version": "v1.0",

   "AppName": "FooApp",

   "EnvironmentName": "Prod"


Example Powershell API Requests
















# build the post url


if (!$hostApi) { $hostApi= '' }

$post = $hostApi.TrimEnd('/') + '/api/v1/deployments/' + $action

# build the authorization header

$headers = @{'authorization'='ApiKey ' + $apiKey}

# build the body of the post

if (!$name) { $name = $version }

$bodyObj = @{ Version=$version; AppName=$app; EnvironmentName=$env; }

if ($action -eq "start" -or $action -eq "complete"){

   $bodyObj.Name = $name

   if ($uri) { $bodyObj.Uri = $uri }

   if ($branch) { $bodyObj.Branch = $branch }

   if ($commit) { $bodyObj.Commit = $commit }


$body =  ConvertTo-Json $bodyObj

# send the request

Invoke-WebRequest -Uri $post -Method POST -ContentType "application/json" -Headers $headers -Body $body

Calling stackify-deploy.ps1

# full deployment start => complete

ps > .\stackify-deploy.ps1 start -apiKey "LvCD4JAoT3chg7ywcVVdwoTbVsEqDuMzje9Q466oKE" -app "FooApp" -env "Prod" -version "v1.0" -name "BourneAgain" -branch "master" -commit "ca35857d2cc6050a2525491840922a6d5d359006" -uri "localhost"

ps > .\stackify-deploy.ps1 complete -apiKey "AfespKXokIw5qRq1KQmPc6JGJ7emnPgj8GPI8070UT" -app "FooApp" -env "Prod" -version "v1.0"

# cancel a deployment

ps > .\stackify-deploy.ps1 cancel -apiKey "0wIVpNkCDgGnItQwgCfc7S5J3cOybDdFUGmeHf6ExS" -app "FooApp" -env "Prod" -version "v1.0"

# full deploymment => complete

ps > .\stackify-deploy.ps1 complete -apiKey "SUN98aIxmzZUkUX8BYNsybDcxJctxEuYjHCKX9M0jo" -app "FooApp" -env "Prod" -version "v1.0" -name "BourneAgain" -branch "master" -commit "ca35857d2cc6050a2525491840922a6d5d359006" -uri "localhost"

Bamboo Notes:

The powershell script can be imported from the build tools repository and called from the repository directory like so:




Any arguments which may contain spaces will need to be enclosed in escaped double quotes (\")


complete -env \"<EnvironmentName>\" -app "<AppName>" -apiKey "<ApiKey>" -version "${bamboo.deploy.release}-b${bamboo.buildNumber}" -uri "${bamboo.resultsUrl}" -branch "${bamboo.planRepository.branch}" -commit "${bamboo.planRepository.revision}"


If you encounter any issues while implementing the Deployment Tracking API sample code, do not hesitate to reach out to the support team for additional help (


Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request


Powered by Zendesk