Update metadata of an existing release
const url = 'https://api.aetherpush.com/v1/apps/example/deployments/example/release';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"packageInfo":{"rollout":50,"description":"Bumped rollout to 50%"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PATCH \ --url https://api.aetherpush.com/v1/apps/example/deployments/example/release \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "packageInfo": { "rollout": 50, "description": "Bumped rollout to 50%" } }'Patches mutable metadata of the latest release (or a specific
release identified by label in the body). Useful for changing
description, increasing rollout percentage, toggling
isDisabled, or correcting appVersion.
Returns 204 if no fields actually changed.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”object
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
Semver version or range that this release targets.
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.
Release selector on PATCH and promote. On upload the server
ignores a caller-supplied value and mints the next vN label.
Percentage of clients eligible for this release.
Example
{ "packageInfo": { "rollout": 50, "description": "Bumped rollout to 50%" }}Responses
Section titled “Responses”Release updated.
object
object
Signed URL to download the package bundle.
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.
Server-minted release id (for example v3). Omitted when the
package has no label. Never null and never an empty string.
Set when releaseMethod is Promote.
Set when releaseMethod is Promote or Rollback.
SHA-256 hash of the package contents. The server computes this from the uploaded bytes; callers do not supply it.
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.
Package size in bytes.
Unix timestamp in milliseconds.
Example
{ "package": { "appVersion": "1.0.0", "label": "v3", "releaseMethod": "Upload" }}No changes detected; release left untouched.
Validation 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
Human-readable error message.
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.
Unique identifier for the request, also exposed as the X-Request-Id response header.
object
object
Stable machine code for this field error.
Example
{ "error": "The requested resource was not found.", "code": "not_found", "requestId": "req_abc123"}Unauthenticated.
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
Human-readable error message.
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.
Unique identifier for the request, also exposed as the X-Request-Id response header.
Example
{ "error": "The requested resource was not found.", "code": "not_found", "requestId": "req_abc123"}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.deploy, 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.
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
Human-readable error message.
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.
Unique identifier for the request, also exposed as the X-Request-Id response header.
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
The scopes the route requires. Only these three appear: no
management route requires keys.
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.deploy
{ "error": "This action requires the releases.deploy permission on the app!", "code": "forbidden", "requestId": "req_abc123"}App, deployment, or labeled release not found.
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
Human-readable error message.
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.
Unique identifier for the request, also exposed as the X-Request-Id response header.
Example
{ "error": "The requested resource was not found.", "code": "not_found", "requestId": "req_abc123"}The rollout change was refused. A value that is not above the
current rollout, or any rollout change on a completed release,
answers the plain error shape with code set to
resource_already_exists. A rollout raise above the current
value, on a release that the release auto-halt disabled while
that rollout is still unfinished, answers release_halted;
the usual next step is a fixed release or a rollback. Sending
isDisabled: false in the same request overrides the halt,
re-enabling the release and setting its rollout together.
Re-enabling it alone, and edits to its other fields, are not
refused. Re-enabling also ends that halt: a release re-enabled
and later disabled again by hand accepts rollout changes, and
only a fresh automatic halt refuses them again. A release
disabled by hand that the auto-halt never disabled accepts
rollout changes. A new appVersion that is a different range
from the one the release already has answers release_range_overlap,
and no field in that request is written. A new spelling of the
same range is left as stored.
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
Human-readable error message.
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.
Unique identifier for the request, also exposed as the X-Request-Id response header.
Returned with HTTP 409 by the release update endpoint.
release_halted means the release is disabled, the release
auto-halt has halted it, and the request changes its rollout
without re-enabling it. release_range_overlap means the new
appVersion is a range and it is not the same range the release
already has. Nothing was changed. A new spelling of the same range
is not stored: the release keeps the app version string it already
has, and any other field in the request is still written. Read
code rather than error, whose wording is not part of the contract.
object
Examples
The requested rollout is not above the current one
{ "error": "Rollout value must be greater than \"50\", the existing value.", "code": "resource_already_exists", "requestId": "req_abc123"}The release is disabled and the auto-halt has halted it
{ "error": "Cannot change the rollout of release \"v3\": it is disabled, and the release auto-halt halted it for failed installs. Upload a new release for the same binary version, roll back to a healthy release with that same binary version, or override the halt by re-enabling the release and setting its rollout in the same request.", "code": "release_halted", "requestId": "req_abc123"}The new app version is a different range
{ "error": "The release was not updated because the new app version is a different range. Nothing was changed.", "code": "release_range_overlap", "requestId": "req_abc123"}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.
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
Example
{ "error": "Rate limit exceeded", "code": "tenant_rate_limit_exceeded", "retryAfterSeconds": 60}Headers
Section titled “Headers”Seconds until the tenant window resets.
The release could not be updated because of database contention
on this package (lock wait expired or deadlock). Nothing was
changed. The body includes retryAfterSeconds and the response
sets Retry-After to the same value.
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
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
Section titled “Headers”Seconds to wait before retrying.