deploy.apps.createCreate an app
builder "image" needs imageRef; "compose" needs composeSource, composeService and composePort.
Request syntax
POST /deploy/api/apps
{
"name": "string",
"slug": "string",
"hosting": "enum",
"memoryMb": "number",
"idleSeconds": "number",
"database": "enum",
"gitRepositoryId": "string",
"branch": "string",
"deployOnPush": "boolean",
"rootDir": "string",
"builder": "enum",
"buildCommand": "string",
"startCommand": "string",
"imageRef": "string",
"ecrRepositoryId": "string",
"composeSource": "enum",
"composeFile": "string",
"composePath": "string",
"composeService": "string",
"composePort": "number",
"port": "number",
"instanceType": "string",
"replicas": "number",
"releaseCommand": "string",
"releaseService": "string",
"releaseTimeoutSec": "number",
"healthCheck": "object",
"composeHealthChecks": "map of string",
"tags": "map of string"
}Request body
nameRequiredstring
Display name of the app
Constraints: 1-64 chars
slugOptionalstring
Short name used in the app’s default hostname; must be unique in the organization; derived from name when omitted
Constraints: 1-63 chars, /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/
hostingOptionalenum
machine (default): the app runs on its own machines; pooled: a Next.js app on shared hosts that scales to zero, deployed from bundles your CI uploads
One of:
machine,pooledmemoryMbOptionalnumber
Pooled hosting: memory reserved for the app’s server while it runs, in MB; default 768
Constraints: integer, 256-2048
idleSecondsOptionalnumber
Pooled hosting: seconds without a request after which the app’s server is stopped; default 300
Constraints: integer, 60-3600
databaseOptionalenum
Pooled hosting only: postgres gives the app a Postgres database on its pool host (needs deploy:ManageHostDatabase); none (default) gives it none. An app on its own machines is refused with 400 and binds a managed Postgres instead
One of:
none,postgresgitRepositoryIdOptionalstring
Git repository the app builds from; required for every builder except image and compose. The app starts with that repository’s tags
branchOptionalstring
Branch the app deploys from; omitted, the repository’s default branch (main for pooled hosting)
Constraints: 1-255 chars
deployOnPushOptionalboolean
Deploy each commit pushed to the branch, as the person who pushed it; default true when gitRepositoryId is set (always false for pooled hosting)
rootDirOptionalstring
Directory in the repository the app is built from; default the repository root (.)
Constraints: 1-255 chars, /^[A-Za-z0-9._/-]+$/
builderOptionalenum
How the app is built: railpack (default) detects the stack, dockerfile uses the repository’s Dockerfile, image runs imageRef, compose runs a compose file
One of:
railpack,dockerfile,forgejo_actions,image,composebuildCommandOptionalstring
Replaces the build command the builder would detect
Constraints: max 1024 chars
startCommandOptionalstring
Replaces the command the builder would start the app with
Constraints: max 1024 chars
imageRefOptionalstring
Container image the app runs (host/repository:tag or @sha256 digest); required when builder is image. A short Docker Hub name is stored with docker.io/ in front
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})?$/
ecrRepositoryIdOptionalstring
Repository of this organization’s registry the image comes from, so the machines get a pull credential for it; for an inline compose file it is found from the file when omitted
composeSourceOptionalenum
Compose apps: inline takes the file text from composeFile, git reads composePath from the connected repository
One of:
inline,gitcomposeFileOptionalstring
Compose apps with composeSource inline: the compose file text, checked when saved
Constraints: max 131072 chars
composePathOptionalstring
Compose apps with composeSource git: path of the compose file in the repository
Constraints: 1-255 chars, /^[A-Za-z0-9._/-]+$/
composeServiceOptionalstring
Compose apps: the service published on the app’s domains; required
Constraints: 1-63 chars
composePortOptionalnumber
Compose apps: the container port of composeService that receives traffic; required
Constraints: integer, 1-65535
portOptionalnumber
Port the app listens on in its container; default 3000
Constraints: integer, 1-65535
instanceTypeOptionalstring
Machine size of each machine, an instance type, e.g. performance-2 (the provider’s own names are still accepted, deprecated); default the region’s default size
Constraints: 1-32 chars
replicasOptionalnumber
Number of machines; default 1. More than one puts a load balancer in front
Constraints: integer, 1-10
releaseCommandOptionalstring
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.
releaseServiceOptionalstring
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.
releaseTimeoutSecOptionalnumber
Seconds the release command may run before the deployment fails; a new app gets 600
Constraints: integer, 10-3600
healthCheckOptionalobject
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.
composeHealthChecksOptionalmap of string
Compose apps: health checks for services other than the published one, keyed by service name
Constraints: key=<json>
May be null.
tagsOptionalmap of string
Tags for the app, added to those inherited from the repository
Constraints: key=value
Response
201 with `data`: the new app (id, slug, every setting with its defaults filled in, the compose file, status) and its defaultUrl. Nothing is deployed yet.
A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.
Fields of data
idAlwaysstring
App idorgIdAlwaysstring
Organization the app belongs tonameAlwaysstring
Display nameslugAlwaysstring
Short name used in the default hostname, unique in the organizationenvironmentIdAlwaysstring, may be null
Secrets environment the app runs in, which decides which secret a name resolves to; null: shared secrets onlygitRepositoryIdAlwaysstring, may be null
Git repository the app builds from; null for an app that runs an imagebranchAlwaysstring, may be null
Branch the app deploys from; null means the repository’s default branchdeployOnPushAlwaysboolean
Whether each commit pushed to the branch is deployedrootDirAlwaysstring
Directory in the repository the app is built fromimageRefAlwaysstring, may be null
Container image the app runs, for builder image; null otherwisecomposeSourceAlwaysone of inline, git, may be null
Compose apps: where the compose file comes from; null for other builderscomposePathAlwaysstring, may be null
Compose apps with composeSource git: path of the compose file in the repositorycomposeServiceAlwaysstring, may be null
Compose apps: the service published on the app’s domainscomposePortAlwaysnumber, may be null
Compose apps: the container port of composeService that receives traffichostingAlwaysone of machine, pooled
machine: its own machines; pooled: a Next.js app on shared hostsmemoryMbAlwaysnumber
Pooled hosting: memory reserved for the app’s server while it runs, in MBidleSecondsAlwaysnumber
Pooled hosting: seconds without a request after which the server is stoppedpoolHostIdAlwaysstring, may be null
Pooled hosting: the shared host the app is placed on; null until placeddataSavedAtAlwaysstring, may be null
Pooled hosting: when the app’s data directory was last saved; null if neverdataBytesAlwaysnumber, may be null
Pooled hosting: size of the last saved data directory, in bytesbuilderAlwaysone of railpack, dockerfile, forgejo_actions, image, compose, nextjs
How the app is built; nextjs for pooled hostingbuildCommandAlwaysstring, may be null
Build command replacing the detected one; null: the detected onestartCommandAlwaysstring, may be null
Start command replacing the detected one; null: the detected oneportAlwaysnumber
Port the app listens on in its containerreleaseCommandAlwaysstring, may be null
Command run once per deployment before traffic moves; null: nonereleaseServiceAlwaysstring, may be null
Compose apps: service the release command runs in; null: the published servicereleaseTimeoutSecAlwaysnumber
Seconds the release command may runhealthCheckAlwaysobject, may be null
HTTP check a new container must pass; null means GET / below 500healthCheck.pathAlwaysstring
Path requested with GET on the containerhealthCheck.portWhen presentnumber
Container port probed; absent means the app’s (or published service’s) porthealthCheck.expectedStatusWhen presentnumber
The one HTTP status that counts as healthy; absent means any status below 500healthCheck.timeoutSecWhen presentnumber
Seconds a new container has to start answeringcomposeHealthChecksAlwaysmap, may be null
Compose apps: health checks of other services, by service name; null: nonecomposeHealthChecks.<key>.pathAlwaysstring
Path requested with GET on the containercomposeHealthChecks.<key>.portWhen presentnumber
Container port probed; absent means the app’s (or published service’s) portcomposeHealthChecks.<key>.expectedStatusWhen presentnumber
The one HTTP status that counts as healthy; absent means any status below 500composeHealthChecks.<key>.timeoutSecWhen presentnumber
Seconds a new container has to start answeringinstanceTypeAlwaysstring
Machine size of each machine (pooled for pooled hosting), e.g. performance-2replicasAlwaysnumber
Number of machineslocationsAlwaysarray of string
Locations the machines are spread over in order; empty: the region’s own locationhetznerLoadBalancerIdAlwaysnumber, may be null
The app’s load balancer, when it has more than one machine or location; else nullloadBalancerIpv4Alwaysstring, may be null
Public address of the app’s load balancer; null without oneecrRepositoryIdAlwaysstring, may be null
Repository of the organization’s registry the app pulls from; null: noneserviceAccountIamUserIdAlwaysstring, may be null
The app’s own identity its machines sign in with; null until provisionedgenerationAlwaysnumber
Counter raised with every new desired deployment; machines roll when it changesactiveDeploymentIdAlwaysstring, may be null
The deployment live now; null before the first onestatusAlwaysone of created, provisioning, active, suspended, error, deleting
created, provisioning, active, suspended, error or deletingreconcileErrorAlwaysstring, may be null
Why the last provisioning or teardown step failed; null when nothing failedtlsReportAlwaysobject, may be null
Certificate state a machine last reported, hostname by hostname; null: none yettlsReport.atAlwaysstring
When a machine reportedtlsReport.entriesAlwaysarray of object
One entry per hostname the machine servestlsReport.entries[].hostAlwaysstring
HostnametlsReport.entries[].okAlwaysboolean
Whether a certificate is served for ittlsReport.entries[].errorWhen presentstring
Why not, as the TLS handshake said itenvChangedAtAlwaysstring, may be null
When the environment or a binding last changed; null if nevercreatedAtAlwaysstring
When the app was createdupdatedAtAlwaysstring
When the app was last changedcomposeFileAlwaysstring, may be null
Compose apps with composeSource inline: the compose file text; null otherwisedefaultUrlAlwaysstring
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:CreateApp 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 create --name examplecurl -X POST "https://console.platform-development.deutschecloud.app/deploy/api/apps" \
-H "Authorization: EWS-ACCESS-KEY $ACCESS_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"example"}'Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_deploy_apps_create.