Roll back a deployment to a previous release

POST

/v1/apps/{appName}/deployments/{deploymentName}/rollbacks

const url = 'https://api.aetherpush.com/v1/apps/example/deployments/example/rollbacks';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"targetRelease":"v3"}'
};

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/rollbacks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "targetRelease": "v3" }'

Rolls back the deployment to a previous release. If targetRelease is omitted, rolls back to the immediately previous release. If specified, rolls back to that exact label.

The rollback creates a new release with the contents of the target — it does not delete the current release. The new release always has isDisabled: false and rollout: 100 (full rollout).

Cannot roll back across appVersion changes.

Authorizations

accessKeyAuth
apiKeyAuth
deploy

Parameters

Path Parameters

appName

required

string

deploymentName

required

string

Request Body

application/json

object

targetRelease

Optional label of the release to roll back to (e.g. v3). If omitted, the deployment is rolled back to the immediately previous release.

string

/^v[1-9][0-9]*$/

Example

{
  "targetRelease": "v3"
}

Responses

201

Rollback successful; new release created.

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

401

Unauthenticated.

application/json

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"
}

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.rollback, 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.rollback

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

404

App or deployment not found, no releases on the deployment, no prior release to roll back to, or target label 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 target release is already the current release (rollback_target_current), its appVersion differs from the current release’s (rollback_version_mismatch), the target was disabled by the release auto-halt and the rollback would ship its bundle again at 100% (release_halted), or the next minted label already exists on this deployment (release_label_collision). Read code rather than error to tell them apart. The halted refusal covers the no-target rollback too, whose implicit target is the immediately previous release. Roll back to a healthy release with an explicit target label, or re-enable the halted release first to override the halt. A release disabled by hand and never halted rolls back as usual, and so does one re-enabled after a halt and later disabled again by hand, since re-enabling ends that halt. A conflict raised outside those causes answers the plain error shape, which carries a code of its own.

application/json

Any of:

Error
RollbackConflictError

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

RollbackConflictError

Returned with HTTP 409 by the rollback endpoint. rollback_target_current means the requested label is already the deployment’s latest release; rollback_version_mismatch means the target targets a different binary version than the current release, so the request is refused; upload a new release for the current binary instead. release_halted means the rollback target is disabled because the release auto-halt pulled it back for failed installs, and the rollback would have shipped its bundle again at 100%. Roll back to a healthy release with an explicit target label, or re-enable the halted release first to override the halt. A release disabled by hand and never halted rolls back as usual, and so does one re-enabled after a halt and later disabled again by hand, since re-enabling ends that halt. release_label_collision means the next minted label already exists on the deployment, which is data drift rather than a concurrent writer.

object

error

required

string

code

required

string

Allowed values: rollback_target_current rollback_version_mismatch release_halted release_label_collision

requestId

string

Examples

The target label is already the latest release

{
  "error": "Cannot perform rollback because the target release (v3) is already the latest release.",
  "code": "rollback_target_current",
  "requestId": "req_abc123"
}

The target targets a different binary version

{
  "error": "Cannot perform rollback to a different app version. Upload a new release for the current binary version instead.",
  "code": "rollback_version_mismatch",
  "requestId": "req_abc123"
}

The rollback target was pulled back by the release auto-halt

{
  "error": "Cannot roll back to release \"v3\": it is disabled, and the release auto-halt halted it for failed installs. Roll back to a healthy release with an explicit target label, or override the halt by re-enabling release \"v3\" first.",
  "code": "release_halted",
  "requestId": "req_abc123"
}

The minted label already exists on this deployment

{
  "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"
}

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 rollback could not finish because of database contention on this deployment (lock wait expired or deadlock). No release was created and no existing release was changed. The rollback reuses the target release’s package, so a retry uploads nothing. 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.