deploy.apps.get

Describe an app with its environment, deployments, domains and machines

GET /deploy/api/apps/{id}IAM deploy:DescribeAppRead

Environment values are included only with deploy:ManageEnv, the compose file only with deploy:UpdateApp.

Without deploy:ManageEnv the answer is reduced rather than refused.

Request syntax

GET /deploy/api/apps/{id}

Path parameters

  • idRequired

    string

    Constraints: uuid

Response

200 with `data`: `app` (all its settings, status and defaultUrl), `env` (its variables), `envRedacted` and `composeFileRedacted` (whether they were withheld), `deployments` (the last 50, newest first), `domains`, and `targets` (each machine with its health, sync state and instance).

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

Fields of data

  • appAlways

    object

    The app with all its settings
  • app.​idAlways

    string

    App id
  • app.​orgIdAlways

    string

    Organization the app belongs to
  • app.​nameAlways

    string

    Display name
  • app.​slugAlways

    string

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

    string, may be null

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

    string, may be null

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

    string, may be null

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

    boolean

    Whether each commit pushed to the branch is deployed
  • app.​rootDirAlways

    string

    Directory in the repository the app is built from
  • app.​imageRefAlways

    string, may be null

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

    one of inline, git, may be null

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

    string, may be null

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

    string, may be null

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

    number, may be null

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

    one of machine, pooled

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

    number

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

    number

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

    string, may be null

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

    string, may be null

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

    number, may be null

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

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

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

    string, may be null

    Build command replacing the detected one; null: the detected one
  • app.​startCommandAlways

    string, may be null

    Start command replacing the detected one; null: the detected one
  • app.​portAlways

    number

    Port the app listens on in its container
  • app.​releaseCommandAlways

    string, may be null

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

    string, may be null

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

    number

    Seconds the release command may run
  • app.​healthCheckAlways

    object, may be null

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

    string

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

    number

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

    number

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

    number

    Seconds a new container has to start answering
  • app.​composeHealthChecksAlways

    map, may be null

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

    string

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

    number

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

    number

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

    number

    Seconds a new container has to start answering
  • app.​instanceTypeAlways

    string

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

    number

    Number of machines
  • app.​locationsAlways

    array of string

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

    number, may be null

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

    string, may be null

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

    string, may be null

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

    string, may be null

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

    number

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

    string, may be null

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

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

    created, provisioning, active, suspended, error or deleting
  • app.​reconcileErrorAlways

    string, may be null

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

    object, may be null

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

    string

    When a machine reported
  • app.​tlsReport.​entriesAlways

    array of object

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

    string

    Hostname
  • app.​tlsReport.​entries[].​okAlways

    boolean

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

    string

    Why not, as the TLS handshake said it
  • app.​envChangedAtAlways

    string, may be null

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

    string

    When the app was created
  • app.​updatedAtAlways

    string

    When the app was last changed
  • app.​composeFileAlways

    string, may be null

    Compose file text; null without one or without deploy:UpdateApp
  • app.​defaultUrlAlways

    string

    The app’s default hostname
  • envAlways

    array of object

    Its variables; empty without deploy:ManageEnv (see envRedacted)
  • env[].​idAlways

    string

    Variable id
  • env[].​appIdAlways

    string

    The app
  • env[].​keyAlways

    string

    Variable name
  • env[].​valueKindAlways

    one of plain, secret

    plain (a value) or secret (a bound Secret)
  • env[].​plainValueAlways

    string, may be null

    The value of a plain variable; null for a secret
  • env[].​kmsSecretIdAlways

    string, may be null

    The Secret bound to a secret variable; null for plain, or when it was deleted
  • env[].​createdAtAlways

    string

    When it was first set
  • env[].​updatedAtAlways

    string

    When it was last changed
  • envRedactedAlways

    boolean

    True when the variables were withheld
  • composeFileRedactedAlways

    boolean

    True when the compose file was withheld
  • deploymentsAlways

    array of object

    The last 50 deployments, newest first
  • deployments[].​idAlways

    string

    Deployment id
  • deployments[].​appIdAlways

    string

    The app deployed
  • deployments[].​orgIdAlways

    string

    Organization the deployment belongs to
  • deployments[].​generationAlways

    number

    The app generation this deployment represents
  • deployments[].​triggerAlways

    one of push, manual, rollback

    What started it
  • deployments[].​gitCommitShaAlways

    string, may be null

    Commit built; null for an image or compose app
  • deployments[].​imageRefAlways

    string, may be null

    Image run, by digest once built; null for a compose deployment
  • deployments[].​composeDigestAlways

    string, may be null

    sha256 of the compose file pinned to it; null for other builders
  • deployments[].​composeImagePinsAlways

    map, may be null

    Compose: service name → image digest, for images whose signature was checked; null: none
  • deployments[].​envSnapshotAlways

    array of object, may be null

    The environment when it started (secrets by reference), what a rollback restores; null on older deployments and for a caller without deploy:ManageEnv
  • deployments[].​envSnapshot[].​keyAlways

    string

    Variable name
  • deployments[].​envSnapshot[].​valueKindAlways

    one of plain, secret

    plain or secret
  • deployments[].​envSnapshot[].​plainValueAlways

    string, may be null

    The value of a plain variable; null for a secret
  • deployments[].​envSnapshot[].​kmsSecretIdAlways

    string, may be null

    The Secret bound, for a secret; null for plain
  • deployments[].​statusAlways

    one of queued, building, pushing, deploying, live, failed, superseded

    queued, building, pushing, deploying, live, failed or superseded
  • deployments[].​releaseCommandAlways

    string, may be null

    Release command pinned when it started; null: none
  • deployments[].​releaseStatusAlways

    one of pending, running, succeeded, failed, skipped

    Where the release command stands; skipped when there is none
  • deployments[].​releaseExitCodeAlways

    number, may be null

    Exit code of the release command; null until it ran
  • deployments[].​buildLogRefAlways

    string, may be null

    Unused; always null
  • deployments[].​buildExitCodeAlways

    number, may be null

    Exit code the builder reported; null until it finished
  • deployments[].​errorMessageAlways

    string, may be null

    Why it failed; null unless failed
  • deployments[].​createdByAlways

    string, may be null

    IAM user who started it; null for a push or the platform
  • deployments[].​reasonAlways

    string, may be null

    Why it was started, as the starter said; null: none
  • deployments[].​statusHistoryAlways

    array of object

    Every status it passed through, oldest first
  • deployments[].​statusHistory[].​statusAlways

    string

    Status entered
  • deployments[].​statusHistory[].​atAlways

    string

    When
  • deployments[].​bundleKeyAlways

    string, may be null

    Pooled hosting: storage key of the uploaded bundle; null otherwise
  • deployments[].​bundleSha256Always

    string, may be null

    Pooled hosting: sha256 of the bundle
  • deployments[].​bundleBytesAlways

    number, may be null

    Pooled hosting: size of the bundle, in bytes
  • deployments[].​branchAlways

    string, may be null

    Pooled hosting: branch the commit was pushed to
  • deployments[].​previewAlways

    boolean

    Pooled hosting: a preview at its own URL rather than production
  • deployments[].​hostingSummaryAlways

    object, may be null

    Pooled hosting: what the bundle contains; null until read
  • deployments[].​hostingSummary.​kindAlways

    one of static, hybrid, fallback

    static: files only; hybrid: some routes need the server; fallback: all do
  • deployments[].​hostingSummary.​nextVersionAlways

    string, may be null

    Next.js version of the build; null if unknown
  • deployments[].​hostingSummary.​filesAlways

    number

    Number of files served without the server
  • deployments[].​hostingSummary.​nodeRoutesAlways

    array of object

    Routes the app’s server answers
  • deployments[].​hostingSummary.​nodeRoutes[].​pathAlways

    string

    Route
  • deployments[].​hostingSummary.​nodeRoutes[].​reasonAlways

    string

    Why it needs the server
  • deployments[].​createdAtAlways

    string

    When it was started
  • deployments[].​liveAtAlways

    string, may be null

    When it went live; null if it never did
  • domainsAlways

    array of object

    Custom domains
  • domains[].​idAlways

    string

    Domain id
  • domains[].​appIdAlways

    string

    The app it serves
  • domains[].​domainAlways

    string

    Hostname, or *.host for every subdomain
  • domains[].​isPrimaryAlways

    boolean

    Whether it is the app’s primary domain
  • domains[].​tlsStatusAlways

    one of pending, active, failed

    Certificate state
  • domains[].​dnsVerifiedAtAlways

    string, may be null

    When it was last seen pointing at the app; null if never
  • domains[].​createdAtAlways

    string

    When it was added
  • domains[].​updatedAtAlways

    string

    When it was last changed
  • targetsAlways

    array of object

    Each machine with its health and sync
  • targets[].​idAlways

    string

    Target id
  • targets[].​deploymentIdAlways

    string

    Deployment the machine was set up for
  • targets[].​healthAlways

    one of pending, healthy, unhealthy, stale

    As of now; stale when the machine stopped reporting
  • targets[].​lastReportedAtAlways

    string, may be null

    Last report about this deployment; null if none
  • targets[].​createdAtAlways

    string

    When the target was created
  • targets[].​syncAlways

    one of in_sync, out_of_sync, unknown

    Whether the machine runs the deployment it should
  • targets[].​syncReasonAlways

    string

    Why, in one sentence
  • targets[].​rollingOutAlways

    boolean

    Out of sync only because a rollout is in progress
  • targets[].​expectedAlways

    object, may be null

    What it should run; null when nothing is desired
  • targets[].​expected.​generationAlways

    number

    App generation
  • targets[].​expected.​imageRefAlways

    string, may be null

    Image; null for compose
  • targets[].​expected.​composeDigestAlways

    string, may be null

    Compose file digest; null for an image
  • targets[].​runningAlways

    object, may be null

    What it says it runs; null before its first report
  • targets[].​running.​generationAlways

    number

    App generation
  • targets[].​running.​imageRefAlways

    string, may be null

    Image; null for compose
  • targets[].​running.​composeDigestAlways

    string, may be null

    Compose file digest; null for an image
  • targets[].​driftSinceAlways

    string, may be null

    Since when it runs something else; null while in sync
  • targets[].​reportedAtAlways

    string, may be null

    When it last reported anything; null if never
  • targets[].​instanceAlways

    object, may be null

    The machine; null when it was deleted
  • targets[].​instance.​idAlways

    string

    Instance id (i-…)
  • targets[].​instance.​nameAlways

    string, may be null

    Instance name
  • targets[].​instance.​stateAlways

    string

    Instance state, e.g. running
  • targets[].​instance.​publicIpAlways

    string, may be null

    Public IPv4 address; null if none
  • targets[].​instance.​regionIdAlways

    string

    Region
  • targets[].​instance.​serverTypeAlways

    string, may be null

    Instance type; null if unknown

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:DescribeApp 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 get 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_get.