deploy.apps.update

Change an app, including its release command and health checks

PATCH /deploy/api/apps/{id}IAM deploy:UpdateAppChanges stateDestructive

Takes effect on the next deployment.

Request syntax

PATCH /deploy/api/apps/{id}
{
  "name": "string",
  "branch": "string",
  "deployOnPush": "boolean",
  "rootDir": "string",
  "builder": "enum",
  "buildCommand": "string",
  "startCommand": "string",
  "imageRef": "string",
  "composeSource": "enum",
  "composeFile": "string",
  "composePath": "string",
  "composeService": "string",
  "composePort": "number",
  "port": "number",
  "instanceType": "string",
  "replicas": "number",
  "locations": "array of string",
  "releaseCommand": "string",
  "releaseService": "string",
  "releaseTimeoutSec": "number",
  "healthCheck": "object",
  "composeHealthChecks": "map of string"
}

Path parameters

  • idRequired

    string

    Constraints: uuid

Request body

  • nameOptional

    string

    New display name

    Constraints: 1-64 chars

  • branchOptional

    string

    Branch the app deploys from; null returns to the repository’s default branch

    Constraints: 1-255 chars

    May be null.

  • deployOnPushOptional

    boolean

    Whether each commit pushed to the branch is deployed

  • rootDirOptional

    string

    Directory in the repository the app is built from

    Constraints: 1-255 chars, /^[A-Za-z0-9._/-]+$/

  • builderOptional

    enum

    How the app is built: railpack, dockerfile, image or compose (see Create an app)

    One of: railpack, dockerfile, forgejo_actions, image, compose

  • buildCommandOptional

    string

    Replaces the detected build command; null returns to the detected one

    Constraints: max 1024 chars

    May be null.

  • startCommandOptional

    string

    Replaces the detected start command; null returns to the detected one

    Constraints: max 1024 chars

    May be null.

  • imageRefOptional

    string

    Container image the app runs, for builder image

    Constraints: 1-512 chars, /^[a-z0-9]([a-z0-9._-]*[a-z0-9])?(:[0-9]+)?(\/[a-z0-9]([a-z0-9._-]*[a-z0-9])?)*(:[A-Za-z0-9._-]+|@sha256:[a-f0-9]{64})?$/

  • composeSourceOptional

    enum

    Compose apps: inline (composeFile) or git (composePath in the repository)

    One of: inline, git

  • composeFileOptional

    string

    Compose apps: the new compose file text, checked when saved

    Constraints: max 131072 chars

  • composePathOptional

    string

    Compose apps: path of the compose file in the repository

    Constraints: 1-255 chars, /^[A-Za-z0-9._/-]+$/

  • composeServiceOptional

    string

    Compose apps: the service published on the app’s domains

    Constraints: 1-63 chars

  • composePortOptional

    number

    Compose apps: the container port of composeService that receives traffic

    Constraints: integer, 1-65535

  • portOptional

    number

    Port the app listens on in its container

    Constraints: integer, 1-65535

  • instanceTypeOptional

    string

    Machine size of each machine, an instance type, e.g. performance-2 (the provider’s own names are still accepted, deprecated)

    Constraints: 1-32 chars

  • replicasOptional

    number

    Number of machines; more than one puts a load balancer in front

    Constraints: integer, 1-10

  • locationsOptional

    array of string

    Locations the machines are spread over in order, all in one region (e.g. fsn1, nbg1); empty means the region’s own location

    Constraints: /^[a-z]{3}\d$/

  • releaseCommandOptional

    string

    Command run once per deployment with /bin/sh -c in the new image, before traffic moves to it (e.g. database migrations); null or omitted runs none

    Constraints: 1-4096 chars

    May be null.

  • releaseServiceOptional

    string

    Compose apps: the service whose image and environment run the release command; omitted or null, the published service

    Constraints: 1-63 chars

    May be null.

  • releaseTimeoutSecOptional

    number

    Seconds the release command may run before the deployment fails; a new app gets 600

    Constraints: integer, 10-3600

  • healthCheckOptional

    object

    The HTTP check a new container must pass before it gets traffic; null or omitted means GET / on the app port, any status below 500

    Constraints: JSON

    May be null.

  • composeHealthChecksOptional

    map of string

    Compose apps: health checks for services other than the published one, keyed by service name

    Constraints: key=<json>

    May be null.

Response

200 with `data`: the app with the change applied, and its defaultUrl.

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Fields of data

  • idAlways

    string

    App id
  • orgIdAlways

    string

    Organization the app belongs to
  • nameAlways

    string

    Display name
  • slugAlways

    string

    Short name used in the default hostname, unique in the organization
  • environmentIdAlways

    string, may be null

    Secrets environment the app runs in, which decides which secret a name resolves to; null: shared secrets only
  • gitRepositoryIdAlways

    string, may be null

    Git repository the app builds from; null for an app that runs an image
  • branchAlways

    string, may be null

    Branch the app deploys from; null means the repository’s default branch
  • deployOnPushAlways

    boolean

    Whether each commit pushed to the branch is deployed
  • rootDirAlways

    string

    Directory in the repository the app is built from
  • imageRefAlways

    string, may be null

    Container image the app runs, for builder image; null otherwise
  • composeSourceAlways

    one of inline, git, may be null

    Compose apps: where the compose file comes from; null for other builders
  • composePathAlways

    string, may be null

    Compose apps with composeSource git: path of the compose file in the repository
  • composeServiceAlways

    string, may be null

    Compose apps: the service published on the app’s domains
  • composePortAlways

    number, may be null

    Compose apps: the container port of composeService that receives traffic
  • hostingAlways

    one of machine, pooled

    machine: its own machines; pooled: a Next.js app on shared hosts
  • memoryMbAlways

    number

    Pooled hosting: memory reserved for the app’s server while it runs, in MB
  • idleSecondsAlways

    number

    Pooled hosting: seconds without a request after which the server is stopped
  • poolHostIdAlways

    string, may be null

    Pooled hosting: the shared host the app is placed on; null until placed
  • dataSavedAtAlways

    string, may be null

    Pooled hosting: when the app’s data directory was last saved; null if never
  • dataBytesAlways

    number, may be null

    Pooled hosting: size of the last saved data directory, in bytes
  • builderAlways

    one of railpack, dockerfile, forgejo_actions, image, compose, nextjs

    How the app is built; nextjs for pooled hosting
  • buildCommandAlways

    string, may be null

    Build command replacing the detected one; null: the detected one
  • startCommandAlways

    string, may be null

    Start command replacing the detected one; null: the detected one
  • portAlways

    number

    Port the app listens on in its container
  • releaseCommandAlways

    string, may be null

    Command run once per deployment before traffic moves; null: none
  • releaseServiceAlways

    string, may be null

    Compose apps: service the release command runs in; null: the published service
  • releaseTimeoutSecAlways

    number

    Seconds the release command may run
  • healthCheckAlways

    object, may be null

    HTTP check a new container must pass; null means GET / below 500
  • healthCheck.​pathAlways

    string

    Path requested with GET on the container
  • healthCheck.​portWhen present

    number

    Container port probed; absent means the app’s (or published service’s) port
  • healthCheck.​expectedStatusWhen present

    number

    The one HTTP status that counts as healthy; absent means any status below 500
  • healthCheck.​timeoutSecWhen present

    number

    Seconds a new container has to start answering
  • composeHealthChecksAlways

    map, may be null

    Compose apps: health checks of other services, by service name; null: none
  • composeHealthChecks.​<key>.​pathAlways

    string

    Path requested with GET on the container
  • composeHealthChecks.​<key>.​portWhen present

    number

    Container port probed; absent means the app’s (or published service’s) port
  • composeHealthChecks.​<key>.​expectedStatusWhen present

    number

    The one HTTP status that counts as healthy; absent means any status below 500
  • composeHealthChecks.​<key>.​timeoutSecWhen present

    number

    Seconds a new container has to start answering
  • instanceTypeAlways

    string

    Machine size of each machine (pooled for pooled hosting), e.g. performance-2
  • replicasAlways

    number

    Number of machines
  • locationsAlways

    array of string

    Locations the machines are spread over in order; empty: the region’s own location
  • hetznerLoadBalancerIdAlways

    number, may be null

    The app’s load balancer, when it has more than one machine or location; else null
  • loadBalancerIpv4Always

    string, may be null

    Public address of the app’s load balancer; null without one
  • ecrRepositoryIdAlways

    string, may be null

    Repository of the organization’s registry the app pulls from; null: none
  • serviceAccountIamUserIdAlways

    string, may be null

    The app’s own identity its machines sign in with; null until provisioned
  • generationAlways

    number

    Counter raised with every new desired deployment; machines roll when it changes
  • activeDeploymentIdAlways

    string, may be null

    The deployment live now; null before the first one
  • statusAlways

    one of created, provisioning, active, suspended, error, deleting

    created, provisioning, active, suspended, error or deleting
  • reconcileErrorAlways

    string, may be null

    Why the last provisioning or teardown step failed; null when nothing failed
  • tlsReportAlways

    object, may be null

    Certificate state a machine last reported, hostname by hostname; null: none yet
  • tlsReport.​atAlways

    string

    When a machine reported
  • tlsReport.​entriesAlways

    array of object

    One entry per hostname the machine serves
  • tlsReport.​entries[].​hostAlways

    string

    Hostname
  • tlsReport.​entries[].​okAlways

    boolean

    Whether a certificate is served for it
  • tlsReport.​entries[].​errorWhen present

    string

    Why not, as the TLS handshake said it
  • envChangedAtAlways

    string, may be null

    When the environment or a binding last changed; null if never
  • createdAtAlways

    string

    When the app was created
  • updatedAtAlways

    string

    When the app was last changed
  • composeFileAlways

    string, may be null

    Compose apps with composeSource inline: the compose file text; null otherwise
  • defaultUrlAlways

    string

    The app’s default hostname

Checked against the handlers: every route test validates their answers against this schema.

Errors

  • 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
  • 401No credentials, or an access key that is unknown, revoked or expired.
  • 403The caller's policies do not allow deploy:UpdateApp on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
  • 404The resource does not exist in your organization.

Examples

The required parameters only, with example values. Replace id and the other placeholders with your own.

dcloud deploy apps update id

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_deploy_apps_update.