deploy.apps.create

Create an app

POST /deploy/api/appsIAM deploy:CreateAppChanges state

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

  • nameRequired

    string

    Display name of the app

    Constraints: 1-64 chars

  • slugOptional

    string

    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])?$/

  • hostingOptional

    enum

    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, pooled

  • memoryMbOptional

    number

    Pooled hosting: memory reserved for the app’s server while it runs, in MB; default 768

    Constraints: integer, 256-2048

  • idleSecondsOptional

    number

    Pooled hosting: seconds without a request after which the app’s server is stopped; default 300

    Constraints: integer, 60-3600

  • databaseOptional

    enum

    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, postgres

  • gitRepositoryIdOptional

    string

    Git repository the app builds from; required for every builder except image and compose. The app starts with that repository’s tags

  • branchOptional

    string

    Branch the app deploys from; omitted, the repository’s default branch (main for pooled hosting)

    Constraints: 1-255 chars

  • deployOnPushOptional

    boolean

    Deploy each commit pushed to the branch, as the person who pushed it; default true when gitRepositoryId is set (always false for pooled hosting)

  • rootDirOptional

    string

    Directory in the repository the app is built from; default the repository root (.)

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

  • builderOptional

    enum

    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, compose

  • buildCommandOptional

    string

    Replaces the build command the builder would detect

    Constraints: max 1024 chars

  • startCommandOptional

    string

    Replaces the command the builder would start the app with

    Constraints: max 1024 chars

  • imageRefOptional

    string

    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})?$/

  • ecrRepositoryIdOptional

    string

    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

  • composeSourceOptional

    enum

    Compose apps: inline takes the file text from composeFile, git reads composePath from the connected repository

    One of: inline, git

  • composeFileOptional

    string

    Compose apps with composeSource inline: the compose file text, checked when saved

    Constraints: max 131072 chars

  • composePathOptional

    string

    Compose apps with composeSource git: 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; required

    Constraints: 1-63 chars

  • composePortOptional

    number

    Compose apps: the container port of composeService that receives traffic; required

    Constraints: integer, 1-65535

  • portOptional

    number

    Port the app listens on in its container; default 3000

    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); default the region’s default size

    Constraints: 1-32 chars

  • replicasOptional

    number

    Number of machines; default 1. More than one puts a load balancer in front

    Constraints: integer, 1-10

  • 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.

  • tagsOptional

    map 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

  • 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: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 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.