Promote a release from one deployment to another

POST

/v1/apps/{appName}/deployments/{sourceDeploymentName}/promotions

const url = 'https://api.aetherpush.com/v1/apps/example/deployments/example/promotions';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"destination":"Production","packageInfo":{"description":"Promoted from Staging after QA","rollout":25,"isMandatory":false}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

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

accessKeyAuth
apiKeyAuth
deploy

Parameters

Path Parameters

appName

required

string

sourceDeploymentName

required

string

Name of the source deployment to promote from.

Request Body^required

application/json

object

destination

required

Name of the destination deployment to promote into.

string

packageInfo

Caller-supplied package metadata for release upload, patch, and promote bodies. The package hash is not an input here; the server computes it from the uploaded bytes and returns it on Package.

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

Release selector on PATCH and promote. On upload the server ignores a caller-supplied value and mints the next vN label.

string

/^v[1-9][0-9]{0,8}$/

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

201

Promotion successful.

application/json

object

package

required

object

appVersion

string

blobUrl

required

Signed URL to download the package bundle.

string format: uri

description

string

isDisabled

boolean

isMandatory

boolean

isAutoHalted

True when this release is currently held by the automatic release halt: the package is disabled and a halt event exists at its current auto-halt generation. Present on GET /v1/apps/{appName}/deployments/{deploymentName}/history (and the paginated form of that route). False after an override re-enables the release, after a manual disable with no live halt event, or when the package is enabled. Omitted on Package responses that do not compute the flag.

boolean

label

Server-minted release id (for example v3). Omitted when the package has no label. Never null and never an empty string.

string

originalDeployment

Set when releaseMethod is Promote.

string

originalLabel

Set when releaseMethod is Promote or Rollback.

string

packageHash

SHA-256 hash of the package contents. The server computes this from the uploaded bytes; callers do not supply it.

string

releaseMethod

string

Allowed values: Upload Promote Rollback

rollout

Percentage of devices eligible for this release (1-100). Full rollout is always 100 in responses; the server stores completed rollouts as null and normalises them at the REST boundary.

integer

>= 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

Location

string

400

Missing destination, or invalid packageInfo.

application/json

One of:

Error
ValidationError

Error

Standard error envelope. code is the stable machine identifier for client branching and i18n. The wording of error is a human-readable fallback and is not part of the contract. Specialized responses keep narrower code enums where clients already branch on them.

object

error

required

Human-readable error message.

string

code

required

Stable machine code. Prefer this over matching on error. The values this API can answer with are listed in the ApiErrorCode schema of the raw document at https://api.aetherpush.com/openapi.yaml. The field stays an open string here so that a release adding a value does not invalidate this response.

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.",
  "code": "not_found",
  "requestId": "req_abc123"
}

401

Unauthenticated.

application/json

Error

object

error

required

Human-readable error message.

string

code

required

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.",
  "code": "not_found",
  "requestId": "req_abc123"
}

403

The API key’s scopes do not grant deploy, which answers required_scopes; or the caller’s role on the app does not grant releases.promote, which answers a plain error. Access keys and login sessions hold wildcard scope, so they never receive the scope refusal, and a Viewer receives the role refusal. Other refusals raised before the route, such as a request that did not arrive through the trusted edge, also answer a plain error.

application/json

One of:

Error
InsufficientScopesError

Error

object

error

required

Human-readable error message.

string

code

required

string

requestId

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

string

InsufficientScopesError

Returned when an API key’s scopes do not grant the scope a management route requires. required_scopes lists what the route asked for, not what the key holds. Access keys and login sessions carry wildcard scope and pass the check without reaching this response, so only apiKeyAuth callers receive it. A key whose only scope is keys gets this on every management route, because that scope grants nothing, which is also why keys never appears in required_scopes.

object

error

required

string

code

required

string

Allowed values: insufficient_scopes

required_scopes

required

The scopes the route requires. Only these three appear: no management route requires keys.

Array<string>

Allowed values: read deploy apps

requestId

string

Examples

The API key's scopes do not grant deploy

{
  "error": "Insufficient permissions",
  "code": "insufficient_scopes",
  "required_scopes": [
    "deploy"
  ],
  "requestId": "req_abc123"
}

The caller's role does not grant releases.promote

{
  "error": "This action requires the releases.promote permission on the app!",
  "code": "forbidden",
  "requestId": "req_abc123"
}

404

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

application/json

Error

object

error

required

Human-readable error message.

string

code

required

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.",
  "code": "not_found",
  "requestId": "req_abc123"
}

409

The destination is in an unfinished rollout (unfinished_rollout), the promoted package is identical to the destination’s current release (duplicate_release), the source release was disabled by the release auto-halt and the promotion would ship its bundle enabled again (release_halted), the next minted label already exists on the destination (release_label_collision), or the stored version is a range that overlaps a different release already on the destination (promote_range_overlap). Read code rather than error to tell them apart. The halted refusal applies only when the committed package would be enabled: a promotion with "isDisabled": true goes through and can be re-enabled in the destination once it is safe. A source release disabled by hand and never halted promotes as usual, and so does one re-enabled after a halt and later disabled again by hand, since re-enabling ends that halt. A source deployment with no releases at all, or a label not found in its history, answers 404, not 409, and a conflict raised outside those causes answers the plain error shape, which carries a code of its own.

application/json

Any of:

Error
PromoteConflictError

Error

object

error

required

Human-readable error message.

string

code

required

string

requestId

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

string

PromoteConflictError

Returned with HTTP 409 by the promotion endpoint. code names which conflict occurred, so a caller can act on it without matching on error, whose wording is not part of the contract. duplicate_release means the promoted package is byte-identical to the destination’s current release for that binary version; unfinished_rollout means the destination’s current release is still rolling out; release_halted means the source release is disabled because the release auto-halt pulled it back for failed installs, and the promotion would have shipped its bundle enabled again. Promote a fixed release instead, or promote the halted one with "isDisabled": true and re-enable it in the destination once it is safe. Promotions whose committed package is disabled are not refused. release_label_collision means the next minted label already exists on the destination, which is data drift rather than a concurrent writer. promote_range_overlap means the stored version is a range and the destination already has a release, enabled or not, whose version intersects that range and is not the same range. No destination release was changed.

object

error

required

string

code

required

string

Allowed values: duplicate_release unfinished_rollout release_halted release_label_collision promote_range_overlap

requestId

string

Examples

The promoted package is identical to the destination's current release

{
  "error": "The uploaded package was not promoted because it is identical to the contents of the targeted deployment's current release.",
  "code": "duplicate_release",
  "requestId": "req_abc123"
}

The destination is still rolling out

{
  "error": "Cannot promote to an unfinished rollout release unless it is already disabled.",
  "code": "unfinished_rollout",
  "requestId": "req_abc123"
}

The source release was pulled back by the release auto-halt

{
  "error": "Cannot promote release \"v3\": it is disabled, and the release auto-halt halted it for failed installs. Promote a fixed release instead, or promote this one with \"isDisabled\": true and re-enable it in the destination deployment once it is safe.",
  "code": "release_halted",
  "requestId": "req_abc123"
}

The minted label already exists on the destination

{
  "error": "This release could not finish because the minted label \"v1\" already exists on this deployment. No release was created.",
  "code": "release_label_collision",
  "requestId": "req_abc123"
}

The stored version range overlaps a different destination release

{
  "error": "The package was not promoted because its version range overlaps a different release on the destination. No release was changed.",
  "code": "promote_range_overlap",
  "requestId": "req_abc123"
}

429

The tenant’s per-minute management API budget is spent. Retry-After and X-RateLimit-* say when to retry. This is not a plan quota: quota 429s use the Error envelope and do not set Retry-After.

application/json

RateLimitError

Returned with HTTP 429 when an endpoint-specific rate limit is hit, including the per-tenant management API budget. Not the process-wide address limiter (see GlobalAddressRateLimitErrorResponse). retryAfterSeconds indicates how long the client should wait before retrying, and matches the Retry-After header when that header is set. code names the limit that fired so clients can translate without matching on error.

object

error

required

string

code

required

string

retryAfterSeconds

required

integer

>= 1

requestId

string

Example

{
  "error": "Rate limit exceeded",
  "code": "tenant_rate_limit_exceeded",
  "retryAfterSeconds": 60
}

Headers

Retry-After

integer

>= 1

Seconds until the tenant window resets.

503

The promotion could not finish because of database contention on the destination deployment or on the source release row it verifies (lock wait expired or deadlock). The request wrote nothing and can be retried. The body includes retryAfterSeconds and the response sets Retry-After to the same value.

application/json

Returned with HTTP 503 when the server could not complete an operation for a reason it expects to pass, and says so rather than answering as though it had. On the management API, a release or deployment write could not finish because of database contention (lock wait expired, deadlock, or a serialization failure) and nothing was written, or a release upload could not read back the package it had just stored in order to sign its URL. On the acquisition endpoints, a database read the request depends on could not be completed: resolving a deployment key with nothing cached for it, reading that deployment’s releases, or refreshing the download URL of the release it would serve. The release and download-URL reads answer this way for the failures the server recognises as transient, and the deployment lookup answers this way for any failure it cannot serve from a cached entry, so an outage no longer produces a different status depending on which of them it reached. retryAfterSeconds is the minimum interval before a retry is useful for the path that failed, and is also sent as the Retry-After response header. Management lock-contention 503s use the commit lock wait; acquisition and other transient-read 503s use the deployment-cache failure grace. Those intervals are independent and can differ. code is connection_failed on every response this schema describes, management lock contention included. The operation and the message are what distinguish the paths.

object

error

required

string

code

required

string

retryAfterSeconds

required

integer

>= 1

requestId

string

Example

{
  "error": "This release could not finish because another release was committing to the same deployment. No release was created. Please try again.",
  "code": "connection_failed",
  "retryAfterSeconds": 5,
  "requestId": "req_abc123"
}

Headers

Retry-After

integer

Seconds to wait before retrying.

Promote a release from one deployment to another

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Example

Responses

201

Example

Headers

400

Example

401

Example

403

Examples

404

Example

409

Examples

429

Example

Headers

503

Example

Headers

Request Body^required