Skip to content
AetherAether Docs

Promote a release from one deployment to another

POST
/v1/apps/{appName}/deployments/{sourceDeploymentName}/promotions
curl --request POST \
  --url https://api.aetherpush.com/v1/apps/example/deployments/example/promotions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "destination": "Production", "packageInfo": { "description": "Promoted from Staging after QA", "rollout": 25, "isMandatory": false } }'

Promotes the current release (or a specific labeled release) of the source deployment to the destination deployment. The destination deployment is identified in the request body, not the URL.

Optionally, packageInfo overrides allow modifying metadata for the promoted package (description, rollout, isMandatory, etc.) without re-uploading the bundle.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
appName
required
string
sourceDeploymentName
required
string

Name of the source deployment to promote from.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
destination
required

Name of the destination deployment to promote into.

string
packageInfo

Mutable package metadata. Used as the body shape for release patches and as a sub-object on promote/rollback bodies.

object
appVersion

Semver version or range that this release targets.

string
description

Release notes shown to the client. The limit is counted in UTF-16 code units, so characters outside the Basic Multilingual Plane consume two units each. JSON request bodies are additionally capped at 10 KB in total and refused with 413, so a description whose UTF-8 size approaches that can only be set on the multipart release upload. Promoting carries the source release’s description over without resending it; changing one afterwards means releasing again.

string
<= 10000 characters
isDisabled
boolean
isMandatory
boolean
label
string
/^v[1-9][0-9]*$/
packageHash

SHA-256 hash of the package contents.

string
rollout

Percentage of clients eligible for this release.

integer
>= 1 <= 100
Example
{
  "destination": "Production",
  "packageInfo": {
    "description": "Promoted from Staging after QA",
    "rollout": 25,
    "isMandatory": false
  }
}

Responses

Section titled “Responses”

201

Section titled “201”

Promotion successful.

Media typeapplication/json
object
package
required
object
appVersion
string
blobUrl
required

Signed URL to download the package bundle.

string format: uri
description
string
diffPackageMap

Map of source package hash to diff blob info.

object
key
additional properties
object
size
required
integer format: int64
url
required
string format: uri
isDisabled
boolean
isMandatory
boolean
label
string
manifestBlobUrl

Signed URL to the package manifest (file hash map).

string format: uri
originalDeployment

Set when releaseMethod is Promote.

string
originalLabel

Set when releaseMethod is Promote or Rollback.

string
packageHash
string
releasedBy

Account email of the releaser.

string format: email
releaseMethod
string
Allowed values: Upload Promote Rollback
rollout
integer | null
>= 1 <= 100
size
required

Package size in bytes.

integer format: int64
uploadTime

Unix timestamp in milliseconds.

integer format: int64
Example
{
  "package": {
    "appVersion": "1.0.0",
    "label": "v3",
    "releaseMethod": "Upload"
  }
}

Headers

Section titled “Headers”
Location
string

400

Section titled “400”

Missing destination, or invalid packageInfo.

Media typeapplication/json
object
error
required

Human-readable error message.

string
requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string
Example
{
  "error": "The requested resource was not found.",
  "requestId": "req_abc123"
}

401

Section titled “401”

Unauthenticated, or not a collaborator.

Media typeapplication/json
object
error
required

Human-readable error message.

string
requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string
Example
{
  "error": "The requested resource was not found.",
  "requestId": "req_abc123"
}

404

Section titled “404”

App, source deployment, destination deployment, or labeled release not found.

Media typeapplication/json
object
error
required

Human-readable error message.

string
requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string
Example
{
  "error": "The requested resource was not found.",
  "requestId": "req_abc123"
}

409

Section titled “409”

Source has no enabled releases, destination is in an unfinished rollout, or promoted package is identical to the destination’s current release.

Media typeapplication/json
object
error
required

Human-readable error message.

string
requestId

Unique identifier for the request, also exposed as the X-Request-Id response header.

string
Example
{
  "error": "The requested resource was not found.",
  "requestId": "req_abc123"
}