Skip to main content
POST
Deploy the App

Authorizations

Authorization
string
header
required

An API token for one organization. You create and revoke tokens in the dashboard. A token scoped to one App can reach only that App, so give that kind of token to an agent. An organization-wide token can create a short-lived one with POST /api/tokens.

Scopes

apps:write
OAuth

Change the organization's Apps: edit files, run commands, deploy, and manage Secrets.

apps:write
DPoP

Headers

Idempotency-Key
string

A key that identifies this request for retries, up to 200 printable characters. A retry with the same key and input returns the first request's result instead of repeating the work. If you omit the key, the API generates one and returns it in the Idempotency-Key response header.

Required string length: 1 - 200

Path Parameters

id
string
required

A unique ID that starts with app_.

Pattern: ^app_[0-9A-Za-z]{24}$
Example:

"app_Zj7XhMgplmTJcp5Dk4vcYuk0"

Body

application/json
commit_id
string

The ID of the commit to publish, from GET /api/apps/{id}/commits. Default: the sandbox's files as they are, committed first if they changed since the last commit.

Pattern: ^cmt_[0-9A-Za-z]{24}$

Response

The deployment.

id
string
required

The deployment's ID, which starts with dep_.

app_id
string
required

The ID of the App that the deployment belongs to.

commit_id
string | null
required

The ID of the deployed commit, or null if Judt didn't make the commit, such as a template's first commit.

commit_sha
string
required

The Git SHA of the deployed commit.

status
enum<string>
required

Where the deployment is:

  • publishing: the version is being built and published, after any database migrations that must run first.
  • starting: production points to this version, and it's starting.
  • succeeded: the version started serving. It stays succeeded after a later deployment replaces it or the App is unpublished. To see which deployment is serving now, check the App's production.deployment_id.
  • failed: the version wasn't published, or it didn't start serving. error says why.
  • disabled: the App was deleted while the version was publishing, so it never served.
Available options:
publishing,
starting,
succeeded,
failed,
disabled
error
object | null
required

Why the deployment failed, or null if it didn't fail.

migrations
object | null
required

The D1 database migrations that the source declares, or null until the source is checked.

published_at
string<date-time> | null
required

When the version was published, or null if it isn't published.

Example:

"2026-10-03T14:01:30.000Z"

created_at
string<date-time>
required

When the deployment was created.

Example:

"2026-10-03T14:01:30.000Z"