Rename a deployment
const url = 'https://api.aetherpush.com/v1/apps/example/deployments/example';const options = { method: 'PATCH', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"name":"Production-V2"}'};
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 \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "Production-V2" }'Updates the deployment’s name. Requires the deployments.manage permission (Owner or Admin) to rename a deployment. Note that renaming changes the resource path — clients must update their references.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”object
Example
{ "name": "Production-V2"}Responses
Section titled “Responses”Deployment renamed.
object
object
Deployment key consumed by the React Native SDK at runtime. Replaced with “(hidden)” for accounts without the deploymentKeys.read capability.
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
{ "deployment": { "name": "Production", "key": "AbCdEf1234567890", "package": { "appVersion": "1.0.0", "label": "v3", "releaseMethod": "Upload" } }}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 apps, which answers
required_scopes; or the caller’s role on the app does not grant
deployments.manage, which answers a plain error. Access keys and
login sessions hold wildcard scope, so they never receive the
scope 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 apps
{ "error": "Insufficient permissions", "code": "insufficient_scopes", "required_scopes": [ "apps" ], "requestId": "req_abc123"}The caller's role does not grant deployments.manage
{ "error": "This action requires the deployments.manage permission on the app!", "code": "forbidden", "requestId": "req_abc123"}App or deployment 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"}This app already has a deployment with that name
(deployment_name_in_use). Read code rather than error.
The pre-check answers a message naming the name; a concurrent
rename that loses idx_deployments_app_name answers the generic
conflict body with the same code. A conflict outside that cause
answers the plain error shape with resource_already_exists.
Rename never answers deployment_key_in_use.
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 deployment creation endpoint and
by the deployment rename endpoint.
code names which unique index fired, so a caller can act on it
without matching on error, whose wording is not part of the
contract. deployment_name_in_use means this app already has a
deployment with that name. deployment_key_in_use means the key
is already registered on Aether, on this app or another, including
one the caller cannot see. A generated key can also hit that index:
keys are 256 bits of randomness and are not retried on collision.
code reports one unique. An insert that violates both still
answers a single code. A conflict outside those two causes answers
the plain Error shape with a generic code such as
resource_already_exists. Listing the app’s deployments remains
the complete way to tell “already created with this key” from
“name taken” from “key held elsewhere”.
object
Examples
This app already has a deployment with that name
{ "error": "A deployment named 'Beta' already exists.", "code": "deployment_name_in_use", "requestId": "req_abc123"}A conflict outside the named cause
{ "error": "The provided resource already exists.", "code": "resource_already_exists", "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.