Skip to main content
POST
JavaScript

Authorizations

Authorization
string
header
required

An Account API key, account-scoped JWT, App API key, or user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************.

Headers

Idempotency-Key
string

A unique key that makes this request safe to retry. See Idempotent requests.

Maximum string length: 255
Example:

"d9105228-4a08-46b1-8b91-42fed586d383"

Api-Version-Date
string

Pins the request to a dated API version.

Example:

"2026-08-13"

Path Parameters

id
string
required

The app to deploy, prefixed app_.

Body

application/json
draft
boolean

Upload the build without making it live. Defaults to false, which deploys and promotes in one step.

Example:

false

Response

deployment started

app_id
string
required

The app being deployed, prefixed app_.

Example:

"app_xxxxxxxxxxxxxx"

build_id
string | null
required

The build the deployment produced, prefixed abld_, or null until it succeeds.

draft
boolean
required

Whether the running or last deployment uploaded a build without making it live.

Example:

false

error
string | null
required

Why the deployment failed, or null when it did not.

estimated_duration_ms
integer | null
required

How long this deployment is expected to take in total, estimated from previous runs.

Example:

150000

estimated_remaining_ms
integer | null
required

How much longer the deployment is expected to take. Held above zero until it actually finishes.

Example:

91000

finished_at
integer | null
required

When the deployment ended, in milliseconds since the epoch, or null while it is still running.

phase
enum<string> | null
required

The stage a running deployment has reached, or null when none is running. Later phases dominate the wall clock: process_archive waits on the upload pipeline and promote waits for the build to go live.

Available options:
install,
build,
typecheck,
upload_build,
upload_source,
process_archive,
create_build,
promote,
null
Example:

"process_archive"

progress
number | null
required

Fraction of the deployment estimated to be complete, from 0 to 1. Stops just short of 1 until the run ends.

Example:

0.39

started_at
integer | null
required

When the deployment began, in milliseconds since the epoch, or null when none has run.

Example:

1767268800000

status
enum<string>
required

Whether the app has anything to publish, and what a publish in flight is doing. unpublished means publishing would ship something new; no_source means the sandbox holds no copy of this app, so there is nothing to publish from.

Available options:
published,
unpublished,
publishing,
failed,
no_source
Example:

"publishing"

url
string | null
required

Where the deployed site is served, or null unless the deployment went live.