deploy.deployments.createStart a deployment of an app
imageRef deploys that image this once without changing the app. An image in this organization’s registry is resolved to a digest first. fromDeploymentId runs what that deployment ran; with trigger rollback it also restores the environment that deployment started with (restoreEnvironment, default true for a rollback, needs deploy:ManageEnv as well).
Request syntax
POST /deploy/api/apps/{id}/deployments
{
"trigger": "enum",
"gitCommitSha": "string",
"imageRef": "string",
"fromDeploymentId": "string",
"reason": "string",
"restoreEnvironment": "boolean"
}Path parameters
idRequiredstring
Constraints: uuid
Request body
triggerOptionalenum
rollback marks the deployment as a rollback and, with fromDeploymentId, restores that deployment’s environment by default
One of:
manual,rollbackDefault:
"manual"gitCommitShaOptionalstring
Commit to build; omitted, the head of the app’s branch
Constraints: 7-64 chars
imageRefOptionalstring
Image to run for this deployment only; the app’s own image is not changed
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})?$/
fromDeploymentIdOptionalstring
An earlier deployment of this app to run again: its image or pinned compose file, commit and release command
reasonOptionalstring
Why, shown on the deployment timeline beside who started it
Constraints: 1-500 chars
restoreEnvironmentOptionalboolean
With fromDeploymentId: also put back the environment that deployment started with; default true for a rollback, false otherwise
Response
201 with `data`: the new deployment (id, generation, trigger, status queued, gitCommitSha, imageRef, composeDigest, envSnapshot, reason, createdAt). envSnapshot is null unless the caller holds deploy:ManageEnv; the pinned compose file text is left out. Follow it with wait, events or build-log.
A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.
Fields of data
idAlwaysstring
Deployment idappIdAlwaysstring
The app deployedorgIdAlwaysstring
Organization the deployment belongs togenerationAlwaysnumber
The app generation this deployment representstriggerAlwaysone of push, manual, rollback
What started itgitCommitShaAlwaysstring, may be null
Commit built; null for an image or compose appimageRefAlwaysstring, may be null
Image run, by digest once built; null for a compose deploymentcomposeDigestAlwaysstring, may be null
sha256 of the compose file pinned to it; null for other builderscomposeImagePinsAlwaysmap, may be null
Compose: service name → image digest, for images whose signature was checked; null: noneenvSnapshotAlwaysarray 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:ManageEnvenvSnapshot[].keyAlwaysstring
Variable nameenvSnapshot[].valueKindAlwaysone of plain, secret
plain or secretenvSnapshot[].plainValueAlwaysstring, may be null
The value of a plain variable; null for a secretenvSnapshot[].kmsSecretIdAlwaysstring, may be null
The Secret bound, for a secret; null for plainstatusAlwaysone of queued, building, pushing, deploying, live, failed, superseded
queued, building, pushing, deploying, live, failed or supersededreleaseCommandAlwaysstring, may be null
Release command pinned when it started; null: nonereleaseStatusAlwaysone of pending, running, succeeded, failed, skipped
Where the release command stands; skipped when there is nonereleaseExitCodeAlwaysnumber, may be null
Exit code of the release command; null until it ranbuildLogRefAlwaysstring, may be null
Unused; always nullbuildExitCodeAlwaysnumber, may be null
Exit code the builder reported; null until it finishederrorMessageAlwaysstring, may be null
Why it failed; null unless failedcreatedByAlwaysstring, may be null
IAM user who started it; null for a push or the platformreasonAlwaysstring, may be null
Why it was started, as the starter said; null: nonestatusHistoryAlwaysarray of object
Every status it passed through, oldest firststatusHistory[].statusAlwaysstring
Status enteredstatusHistory[].atAlwaysstring
WhenbundleKeyAlwaysstring, may be null
Pooled hosting: storage key of the uploaded bundle; null otherwisebundleSha256Alwaysstring, may be null
Pooled hosting: sha256 of the bundlebundleBytesAlwaysnumber, may be null
Pooled hosting: size of the bundle, in bytesbranchAlwaysstring, may be null
Pooled hosting: branch the commit was pushed topreviewAlwaysboolean
Pooled hosting: a preview at its own URL rather than productionhostingSummaryAlwaysobject, may be null
Pooled hosting: what the bundle contains; null until readhostingSummary.kindAlwaysone of static, hybrid, fallback
static: files only; hybrid: some routes need the server; fallback: all dohostingSummary.nextVersionAlwaysstring, may be null
Next.js version of the build; null if unknownhostingSummary.filesAlwaysnumber
Number of files served without the serverhostingSummary.nodeRoutesAlwaysarray of object
Routes the app’s server answershostingSummary.nodeRoutes[].pathAlwaysstring
RoutehostingSummary.nodeRoutes[].reasonAlwaysstring
Why it needs the servercreatedAtAlwaysstring
When it was startedliveAtAlwaysstring, may be null
When it went live; null if it never did
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:DeployApp 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 deployments create idcurl -X POST "https://console.platform-development.deutschecloud.app/deploy/api/apps/id/deployments" \
-H "Authorization: EWS-ACCESS-KEY $ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{}'Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_deploy_deployments_create.