Skip to content
AetherAether Docs

Upload a new release

POST
/v1/apps/{appName}/deployments/{deploymentName}/release
curl --request POST \
  --url https://api.aetherpush.com/v1/apps/example/deployments/example/release \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form package=@file \
  --form 'packageInfo={"appVersion":"1.0.0","description":"Bug fixes","isMandatory":false}'

Uploads a new release package to the deployment. Accepts either a flat JS bundle file or a zip archive containing the bundle plus assets. The packageInfo part is a JSON-encoded string containing release metadata (appVersion, description, isMandatory, rollout, etc.).

Rate limited to 100 uploads per IP per 15 minutes.

Returns 409 if the uploaded package is byte-identical to the current release on this deployment, or if the previous release is still in an unfinished rollout.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

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

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typemultipart/form-data
object
package
required

The package archive to upload. Either a flat JS bundle file or a zip containing the bundle plus assets. Sent as a multipart file part.

string format: binary
packageInfo
required

JSON-encoded string containing a PackageInfo object. Note this is a string field in the multipart body, not a nested JSON object. Example value (URL-encoded by the multipart encoder):

{"appVersion":"1.0.0","description":"Bug fixes","isMandatory":false}

See the PackageInfo schema for valid fields.

string

Responses

Section titled “Responses”

201

Section titled “201”

Release uploaded and committed.

Media typeapplication/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

Section titled “Headers”
Location
string

400

Section titled “400”

Missing file, invalid packageInfo JSON, or validation error.

Media typeapplication/json
One of:
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

Section titled “401”

Unauthenticated.

Media typeapplication/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

Section titled “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.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.

Media typeapplication/json
One of:
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

Examples

The API key's scopes do not grant deploy

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

404

Section titled “404”

App or deployment not found.

Media typeapplication/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"
}

409

Section titled “409”

Either the uploaded package is identical to the current release on this deployment (duplicate_release), the previous release is still in an unfinished rollout (unfinished_rollout), the next minted label already exists on this deployment (release_label_collision), or the uploaded version is a range and a different release would be served that bundle (release_range_overlap). A concrete release counts only when its version satisfies the range. An enabled release that already has this same range still allows the upload when every release that would be served the bundle is disabled. Read code rather than error to tell them apart. A release_label_collision or release_range_overlap answers after the package blob has already been stored and counts toward the storage quota; the request creates no release and retrying stores another blob. A conflict raised outside those causes answers the plain error shape, which carries a code of its own.

Media typeapplication/json
Any of:
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

Examples

The package is identical to the current release

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

413

Section titled “413”

The multipart upload exceeded the file size, file count, or part count limit. The body is the Error envelope; error names which limit fired. JSON bodies on other operations that exceed 10 KB use the same status with error set to “The provided resource is too large.”

Media typeapplication/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

Examples

The package file is larger than UPLOAD_SIZE_LIMIT_MB

{
  "error": "The uploaded file is larger than the size limit of 50 megabytes.",
  "code": "upload_file_too_large",
  "requestId": "req_abc123"
}

429

Section titled “429”

Three causes share this status. The tenant limiter answers JSON RateLimitErrorResponse (error, retryAfterSeconds) with Retry-After. The plan’s storage quota answers the Error envelope and no Retry-After. The per-address release-upload limiter answers the plain text Too many requests, please try again later. as text/html, with Retry-After and X-RateLimit-*.

One of:
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

Examples

Tenant management budget spent

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

Headers

Section titled “Headers”
Retry-After
integer
>= 1

Present for the tenant limiter and the upload limiter, not for storage quota.

503

Section titled “503”

The release could not finish for a reason the server expects to pass: database contention on this deployment (lock wait expired or deadlock), or a database failure while reading back the stored package to sign its URL. No release was created and no existing release was changed. The uploaded package has already been stored and counts toward the storage quota, so a retry uploads it again. The body includes retryAfterSeconds and the response sets Retry-After to the same value.

Media typeapplication/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

Section titled “Headers”
Retry-After
integer

Seconds to wait before retrying.