pydo.apps.create()

Generated on 8 May 2026 from pydo version v0.34.0

Copy page as Markdown View page as Markdown

Usage 

client.apps.create(
    body={
        "spec": {...},
        "project_id": "your_project_id",
    },
)
Returns JSONRaises HttpResponseError

Description

Create a new app by submitting an app specification. For documentation on app specifications (AppSpec objects), please refer to the product documentation.

Parameters

spec object required

The desired configuration of an application.

Show child properties
name string required

Example: web-app-01

The name of the app. Must be unique across all apps in the same account.

Min length: 2

Max length: 32

region string optional

The slug form of the geographical origin of the app. Default: nearest available

One of: atl, nyc, sfo, tor, ams, fra, lon, blr, sgp, syd

disable_edge_cache boolean optional

If set to true, the app will not be cached at the edge (CDN). Enable this option if you want to manage CDN configuration yourself—whether by using an external CDN provider or by handling static content and caching within your app. This setting is also recommended for apps that require real-time data or serve dynamic content, such as those using Server-Sent Events (SSE) over GET, or hosting an MCP (Model Context Protocol) Server that utilizes SSE.
Note: This feature is not available for static site components.
For more information, see Disable CDN Cache.

Default: False

disable_email_obfuscation boolean optional

If set to true, email addresses in the app will not be obfuscated. This is
useful for apps that require email addresses to be visible (in the HTML markup).

Default: False

enhanced_threat_control_enabled boolean optional

If set to true, suspicious requests will go through additional security checks to help mitigate layer 7 DDoS attacks.

Default: False

domains array of objects optional

A set of hostnames where the application will be available.

Show child properties
domain string required

Example: app.example.com

The hostname for the domain

Min length: 4

Max length: 253

type string optional

- DEFAULT: The default .ondigitalocean.app domain assigned to this app
- PRIMARY: The primary domain for this app that is displayed as the default in the control panel, used in bindable environment variables, and any other places that reference an app's live URL. Only one domain may be set as primary.
- ALIAS: A non-primary domain

One of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS

Default: UNSPECIFIED

wildcard boolean optional

Example: True

Indicates whether the domain includes all sub-domains, in addition to the given domain

zone string optional

Example: example.com

Optional. If the domain uses DigitalOcean DNS and you would like App
Platform to automatically manage it for you, set this to the name of the
domain on your account.

For example, If the domain you are adding is app.domain.com, the zone
could be domain.com.

minimum_tls_version string optional

The minimum version of TLS a client application can use to access resources for the domain. Must be one of the following values wrapped within quotations: "1.2" or "1.3".

One of: 1.2, 1.3

Min length: 3

Max length: 3

services array of objects optional

Workloads which expose publicly-accessible HTTP services.

Show child properties
name string required

Example: api

The name. Must be unique across all components within the same app.

Min length: 2

Max length: 32

git object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

repo_clone_url string optional

Example: https://github.com/digitalocean/sample-golang.git

The clone URL of the repo. Example: https://github.com/digitalocean/sample-golang.git

github object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

deploy_on_push boolean optional

Example: True

Whether to automatically deploy new commits made to the repo

repo string optional

Example: digitalocean/sample-golang

The name of the repo in the format owner/repo. Example: digitalocean/sample-golang

gitlab object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

deploy_on_push boolean optional

Example: True

Whether to automatically deploy new commits made to the repo

repo string optional

Example: digitalocean/sample-golang

The name of the repo in the format owner/repo. Example: digitalocean/sample-golang

bitbucket object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

deploy_on_push boolean optional

Example: True

Whether to automatically deploy new commits made to the repo

repo string optional

Example: digitalocean/sample-golang

The name of the repo in the format owner/repo. Example: digitalocean/sample-golang

image object optional
Show child properties
registry string optional

Example: registry.hub.docker.com

The registry name. Must be left empty for the DOCR registry type.

registry_type string optional

- DOCKER_HUB: The DockerHub container registry type.
- DOCR: The DigitalOcean container registry type.
- GHCR: The Github container registry type.

One of: DOCKER_HUB, DOCR, GHCR

registry_credentials string optional

Example: my-dockerhub-username:dckr_pat_the_access_token

The credentials to be able to pull the image. The value will be encrypted on first submission. On following submissions, the encrypted value should be used.
- "$username:$access_token" for registries of type DOCKER_HUB.
- "$username:$access_token" for registries of type GHCR.

repository string optional

Example: origin/master

The repository name.

tag string optional

Example: latest

The repository tag. Defaults to latest if not provided and no digest is provided. Cannot be specified if digest is provided.

Default: latest

digest string optional

Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

The image digest. Cannot be specified if tag is provided.

deploy_on_push object optional

Additional nested properties not shown. Refer to the full API spec for details.

dockerfile_path string optional

Example: path/to/Dockerfile

The path to the Dockerfile relative to the root of the repo. If set, it will be used to build this component. Otherwise, App Platform will attempt to build it using buildpacks.

build_command string optional

Example: npm run build

An optional build command to run while building this component from source.

run_command string optional

Example: bin/api

An optional run command to override the component's default.

source_dir string optional

Example: path/to/dir

An optional path to the working directory to use for the build. For Dockerfile builds, this will be used as the build context. Must be relative to the root of the repo.

envs array of objects optional

A list of environment variables made available to the component.

Show child properties
key string required

Example: BASE_URL

The variable name

scope string optional

- RUN_TIME: Made available only at run-time
- BUILD_TIME: Made available only at build-time
- RUN_AND_BUILD_TIME: Made available at both build and run-time

One of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME

Default: RUN_AND_BUILD_TIME

type string optional

- GENERAL: A plain-text environment variable
- SECRET: A secret encrypted environment variable

One of: GENERAL, SECRET

Default: GENERAL

value string optional

Example: http://example.com

The value. If the type is SECRET, the value will be encrypted on first submission. On following submissions, the encrypted value should be used.

environment_slug string optional

Example: node-js

An environment slug describing the type of this app. For a full list, please refer to the product documentation.

log_destinations array of objects optional

A list of configured log forwarding destinations.

Show child properties
name string required

Example: my_log_destination

Min length: 2

Max length: 42

papertrail object optional

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.

datadog object optional

DataDog configuration.

Additional nested properties not shown. Refer to the full API spec for details.

logtail object optional

Logtail configuration.

Additional nested properties not shown. Refer to the full API spec for details.

open_search object optional

OpenSearch configuration.

Additional nested properties not shown. Refer to the full API spec for details.

instance_count integer optional

Example: 2

The amount of instances that this component should be scaled to. Default: 1. Must not be set if autoscaling is used.

Min: 1

Default: 1

instance_size_slug object optional

Example: apps-s-1vcpu-0.5gb

The instance size to use for this component. Default: apps-s-1vcpu-0.5gb

autoscaling object optional
Show child properties
min_instance_count integer optional

Example: 2

The minimum amount of instances for this component.

Min: 1

max_instance_count integer optional

Example: 3

The maximum amount of instances for this component. Maximum 250. Consider using a larger instance size if your application requires more than 250 instances.

Min: 1

Max: 250

metrics object optional

Additional nested properties not shown. Refer to the full API spec for details.

cors object optional
Show child properties
allow_origins array of objects optional

Example: [{'exact': 'https://www.example.com'}, {'regex': '^.*example.com'}]

The set of allowed CORS origins.

Additional nested properties not shown. Refer to the full API spec for details.

allow_methods array of strings optional

Example: ['GET', 'OPTIONS', 'POST', 'PUT', 'PATCH', 'DELETE']

The set of allowed HTTP methods. This configures the Access-Control-Allow-Methods header.

allow_headers array of strings optional

Example: ['Content-Type', 'X-Custom-Header']

The set of allowed HTTP request headers. This configures the Access-Control-Allow-Headers header.

expose_headers array of strings optional

Example: ['Content-Encoding', 'X-Custom-Header']

The set of HTTP response headers that browsers are allowed to access. This configures the Access-Control-Expose-Headers header.

max_age string optional

Example: 5h30m

An optional duration specifying how long browsers can cache the results of a preflight request. This configures the Access-Control-Max-Age header.

allow_credentials boolean optional

Example: False

Whether browsers should expose the response to the client-side JavaScript code when the request’s credentials mode is include. This configures the Access-Control-Allow-Credentials header.

health_check object optional
Show child properties
failure_threshold integer optional

Example: 2

The number of failed health checks before considered unhealthy.

port integer optional

Example: 80

The port on which the health check will be performed. If not set, the health check will be performed on the component's http_port.

Min: 1

Max: 65535

http_path string optional

Example: /health

The route path used for the HTTP health check ping. If not set, the HTTP health check will be disabled and a TCP health check used instead.

initial_delay_seconds integer optional

Example: 30

The number of seconds to wait before beginning health checks.

period_seconds integer optional

Example: 60

The number of seconds to wait between health checks.

success_threshold integer optional

Example: 3

The number of successful health checks before considered healthy.

timeout_seconds integer optional

Example: 45

The number of seconds after which the check times out.

liveness_health_check object optional
Show child properties
failure_threshold integer optional

Example: 18

The number of failed health checks before considered unhealthy.

Min: 1

Max: 50

port integer optional

Example: 80

The port on which the health check will be performed.

Min: 1

Max: 65535

http_path string optional

Example: /health

The route path used for the HTTP health check ping. If not set, the HTTP health check will be disabled and a TCP health check used instead.

initial_delay_seconds integer optional

Example: 30

The number of seconds to wait before beginning health checks.

Min: 0

Max: 3600

period_seconds integer optional

Example: 10

The number of seconds to wait between health checks.

Min: 1

Max: 300

success_threshold integer optional

Example: 1

The number of successful health checks before considered healthy.

Min: 1

Max: 1

timeout_seconds integer optional

Example: 1

The number of seconds after which the check times out.

Min: 1

Max: 120

protocol string optional

The protocol which the service uses to serve traffic on the http_port.

- HTTP: The app is serving the HTTP protocol. Default.
- HTTP2: The app is serving the HTTP/2 protocol. Currently, this needs to be implemented in the service by serving HTTP/2 cleartext (h2c).

One of: HTTP, HTTP2

http_port integer optional

Example: 3000

The internal port on which this service's run command will listen. Default: 8080
If there is not an environment variable with the name PORT, one will be automatically added with its value set to the value of this field.

Min: 1

Max: 65535

internal_ports array of integers optional

Example: [80, 443]

The ports on which this service will listen for internal traffic.

routes array of objects optional deprecated

(Deprecated - Use Ingress Rules instead). A list of HTTP routes that should be routed to this component.

Show child properties
path string optional

Example: /api

(Deprecated - Use Ingress Rules instead). An HTTP path prefix. Paths must start with / and must be unique across all components within an app.

preserve_path_prefix boolean optional

Example: True

An optional flag to preserve the path that is forwarded to the backend service. By default, the HTTP request path will be trimmed from the left when forwarded to the component. For example, a component with path=/api will have requests to /api/list trimmed to /list. If this value is true, the path will remain /api/list.

termination object optional
Show child properties
drain_seconds integer optional

Example: 15

The number of seconds to wait between selecting a container instance for termination and issuing the TERM signal. Selecting a container instance for termination begins an asynchronous drain of new requests on upstream load-balancers. (Default 15)

Min: 1

Max: 110

grace_period_seconds integer optional

Example: 120

The number of seconds to wait between sending a TERM signal to a container and issuing a KILL which causes immediate shutdown. (Default 120)

Min: 1

Max: 600

static_sites array of objects optional

Content which can be rendered to static web assets.

Show child properties
name string required

Example: api

The name. Must be unique across all components within the same app.

Min length: 2

Max length: 32

git object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

repo_clone_url string optional

Example: https://github.com/digitalocean/sample-golang.git

The clone URL of the repo. Example: https://github.com/digitalocean/sample-golang.git

github object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

deploy_on_push boolean optional

Example: True

Whether to automatically deploy new commits made to the repo

repo string optional

Example: digitalocean/sample-golang

The name of the repo in the format owner/repo. Example: digitalocean/sample-golang

gitlab object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

deploy_on_push boolean optional

Example: True

Whether to automatically deploy new commits made to the repo

repo string optional

Example: digitalocean/sample-golang

The name of the repo in the format owner/repo. Example: digitalocean/sample-golang

bitbucket object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

deploy_on_push boolean optional

Example: True

Whether to automatically deploy new commits made to the repo

repo string optional

Example: digitalocean/sample-golang

The name of the repo in the format owner/repo. Example: digitalocean/sample-golang

image object optional
Show child properties
registry string optional

Example: registry.hub.docker.com

The registry name. Must be left empty for the DOCR registry type.

registry_type string optional

- DOCKER_HUB: The DockerHub container registry type.
- DOCR: The DigitalOcean container registry type.
- GHCR: The Github container registry type.

One of: DOCKER_HUB, DOCR, GHCR

registry_credentials string optional

Example: my-dockerhub-username:dckr_pat_the_access_token

The credentials to be able to pull the image. The value will be encrypted on first submission. On following submissions, the encrypted value should be used.
- "$username:$access_token" for registries of type DOCKER_HUB.
- "$username:$access_token" for registries of type GHCR.

repository string optional

Example: origin/master

The repository name.

tag string optional

Example: latest

The repository tag. Defaults to latest if not provided and no digest is provided. Cannot be specified if digest is provided.

Default: latest

digest string optional

Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

The image digest. Cannot be specified if tag is provided.

deploy_on_push object optional

Additional nested properties not shown. Refer to the full API spec for details.

dockerfile_path string optional

Example: path/to/Dockerfile

The path to the Dockerfile relative to the root of the repo. If set, it will be used to build this component. Otherwise, App Platform will attempt to build it using buildpacks.

build_command string optional

Example: npm run build

An optional build command to run while building this component from source.

run_command string optional

Example: bin/api

An optional run command to override the component's default.

source_dir string optional

Example: path/to/dir

An optional path to the working directory to use for the build. For Dockerfile builds, this will be used as the build context. Must be relative to the root of the repo.

envs array of objects optional

A list of environment variables made available to the component.

Show child properties
key string required

Example: BASE_URL

The variable name

scope string optional

- RUN_TIME: Made available only at run-time
- BUILD_TIME: Made available only at build-time
- RUN_AND_BUILD_TIME: Made available at both build and run-time

One of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME

Default: RUN_AND_BUILD_TIME

type string optional

- GENERAL: A plain-text environment variable
- SECRET: A secret encrypted environment variable

One of: GENERAL, SECRET

Default: GENERAL

value string optional

Example: http://example.com

The value. If the type is SECRET, the value will be encrypted on first submission. On following submissions, the encrypted value should be used.

environment_slug string optional

Example: node-js

An environment slug describing the type of this app. For a full list, please refer to the product documentation.

log_destinations array of objects optional

A list of configured log forwarding destinations.

Show child properties
name string required

Example: my_log_destination

Min length: 2

Max length: 42

papertrail object optional

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.

datadog object optional

DataDog configuration.

Additional nested properties not shown. Refer to the full API spec for details.

logtail object optional

Logtail configuration.

Additional nested properties not shown. Refer to the full API spec for details.

open_search object optional

OpenSearch configuration.

Additional nested properties not shown. Refer to the full API spec for details.

index_document string optional

Example: main.html

The name of the index document to use when serving this static site. Default: index.html

Default: index.html

error_document string optional

Example: error.html

The name of the error document to use when serving this static site. Default: 404.html. If no such file exists within the built assets, App Platform will supply one.

Default: 404.html

catchall_document string optional

Example: index.html

The name of the document to use as the fallback for any requests to documents that are not found when serving this static site. Only 1 of catchall_document or error_document can be set.

output_dir string optional

Example: dist/

An optional path to where the built assets will be located, relative to the build context. If not set, App Platform will automatically scan for these directory names: _static, dist, public, build.

cors object optional
Show child properties
allow_origins array of objects optional

Example: [{'exact': 'https://www.example.com'}, {'regex': '^.*example.com'}]

The set of allowed CORS origins.

Additional nested properties not shown. Refer to the full API spec for details.

allow_methods array of strings optional

Example: ['GET', 'OPTIONS', 'POST', 'PUT', 'PATCH', 'DELETE']

The set of allowed HTTP methods. This configures the Access-Control-Allow-Methods header.

allow_headers array of strings optional

Example: ['Content-Type', 'X-Custom-Header']

The set of allowed HTTP request headers. This configures the Access-Control-Allow-Headers header.

expose_headers array of strings optional

Example: ['Content-Encoding', 'X-Custom-Header']

The set of HTTP response headers that browsers are allowed to access. This configures the Access-Control-Expose-Headers header.

max_age string optional

Example: 5h30m

An optional duration specifying how long browsers can cache the results of a preflight request. This configures the Access-Control-Max-Age header.

allow_credentials boolean optional

Example: False

Whether browsers should expose the response to the client-side JavaScript code when the request’s credentials mode is include. This configures the Access-Control-Allow-Credentials header.

routes array of objects optional deprecated

(Deprecated - Use Ingress Rules instead). A list of HTTP routes that should be routed to this component.

Show child properties
path string optional

Example: /api

(Deprecated - Use Ingress Rules instead). An HTTP path prefix. Paths must start with / and must be unique across all components within an app.

preserve_path_prefix boolean optional

Example: True

An optional flag to preserve the path that is forwarded to the backend service. By default, the HTTP request path will be trimmed from the left when forwarded to the component. For example, a component with path=/api will have requests to /api/list trimmed to /list. If this value is true, the path will remain /api/list.

jobs array of objects optional

Pre and post deployment workloads which do not expose publicly-accessible HTTP routes.

Show child properties
name string required

Example: api

The name. Must be unique across all components within the same app.

Min length: 2

Max length: 32

git object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

repo_clone_url string optional

Example: https://github.com/digitalocean/sample-golang.git

The clone URL of the repo. Example: https://github.com/digitalocean/sample-golang.git

github object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

deploy_on_push boolean optional

Example: True

Whether to automatically deploy new commits made to the repo

repo string optional

Example: digitalocean/sample-golang

The name of the repo in the format owner/repo. Example: digitalocean/sample-golang

gitlab object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

deploy_on_push boolean optional

Example: True

Whether to automatically deploy new commits made to the repo

repo string optional

Example: digitalocean/sample-golang

The name of the repo in the format owner/repo. Example: digitalocean/sample-golang

bitbucket object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

deploy_on_push boolean optional

Example: True

Whether to automatically deploy new commits made to the repo

repo string optional

Example: digitalocean/sample-golang

The name of the repo in the format owner/repo. Example: digitalocean/sample-golang

image object optional
Show child properties
registry string optional

Example: registry.hub.docker.com

The registry name. Must be left empty for the DOCR registry type.

registry_type string optional

- DOCKER_HUB: The DockerHub container registry type.
- DOCR: The DigitalOcean container registry type.
- GHCR: The Github container registry type.

One of: DOCKER_HUB, DOCR, GHCR

registry_credentials string optional

Example: my-dockerhub-username:dckr_pat_the_access_token

The credentials to be able to pull the image. The value will be encrypted on first submission. On following submissions, the encrypted value should be used.
- "$username:$access_token" for registries of type DOCKER_HUB.
- "$username:$access_token" for registries of type GHCR.

repository string optional

Example: origin/master

The repository name.

tag string optional

Example: latest

The repository tag. Defaults to latest if not provided and no digest is provided. Cannot be specified if digest is provided.

Default: latest

digest string optional

Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

The image digest. Cannot be specified if tag is provided.

deploy_on_push object optional

Additional nested properties not shown. Refer to the full API spec for details.

dockerfile_path string optional

Example: path/to/Dockerfile

The path to the Dockerfile relative to the root of the repo. If set, it will be used to build this component. Otherwise, App Platform will attempt to build it using buildpacks.

build_command string optional

Example: npm run build

An optional build command to run while building this component from source.

run_command string optional

Example: bin/api

An optional run command to override the component's default.

source_dir string optional

Example: path/to/dir

An optional path to the working directory to use for the build. For Dockerfile builds, this will be used as the build context. Must be relative to the root of the repo.

envs array of objects optional

A list of environment variables made available to the component.

Show child properties
key string required

Example: BASE_URL

The variable name

scope string optional

- RUN_TIME: Made available only at run-time
- BUILD_TIME: Made available only at build-time
- RUN_AND_BUILD_TIME: Made available at both build and run-time

One of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME

Default: RUN_AND_BUILD_TIME

type string optional

- GENERAL: A plain-text environment variable
- SECRET: A secret encrypted environment variable

One of: GENERAL, SECRET

Default: GENERAL

value string optional

Example: http://example.com

The value. If the type is SECRET, the value will be encrypted on first submission. On following submissions, the encrypted value should be used.

environment_slug string optional

Example: node-js

An environment slug describing the type of this app. For a full list, please refer to the product documentation.

log_destinations array of objects optional

A list of configured log forwarding destinations.

Show child properties
name string required

Example: my_log_destination

Min length: 2

Max length: 42

papertrail object optional

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.

datadog object optional

DataDog configuration.

Additional nested properties not shown. Refer to the full API spec for details.

logtail object optional

Logtail configuration.

Additional nested properties not shown. Refer to the full API spec for details.

open_search object optional

OpenSearch configuration.

Additional nested properties not shown. Refer to the full API spec for details.

instance_count integer optional

Example: 2

The amount of instances that this component should be scaled to. Default: 1. Must not be set if autoscaling is used.

Min: 1

Default: 1

instance_size_slug object optional

Example: apps-s-1vcpu-0.5gb

The instance size to use for this component. Default: apps-s-1vcpu-0.5gb

kind string optional

- UNSPECIFIED: Default job type, will auto-complete to POST_DEPLOY kind.
- PRE_DEPLOY: Indicates a job that runs before an app deployment.
- POST_DEPLOY: Indicates a job that runs after an app deployment.
- FAILED_DEPLOY: Indicates a job that runs after a component fails to deploy.

One of: UNSPECIFIED, PRE_DEPLOY, POST_DEPLOY, FAILED_DEPLOY

Default: UNSPECIFIED

termination object optional
Show child properties
grace_period_seconds integer optional

Example: 120

The number of seconds to wait between sending a TERM signal to a container and issuing a KILL which causes immediate shutdown. (Default 120)

Min: 1

Max: 600

workers array of objects optional

Workloads which do not expose publicly-accessible HTTP services.

Show child properties
name string required

Example: api

The name. Must be unique across all components within the same app.

Min length: 2

Max length: 32

git object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

repo_clone_url string optional

Example: https://github.com/digitalocean/sample-golang.git

The clone URL of the repo. Example: https://github.com/digitalocean/sample-golang.git

github object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

deploy_on_push boolean optional

Example: True

Whether to automatically deploy new commits made to the repo

repo string optional

Example: digitalocean/sample-golang

The name of the repo in the format owner/repo. Example: digitalocean/sample-golang

gitlab object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

deploy_on_push boolean optional

Example: True

Whether to automatically deploy new commits made to the repo

repo string optional

Example: digitalocean/sample-golang

The name of the repo in the format owner/repo. Example: digitalocean/sample-golang

bitbucket object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

deploy_on_push boolean optional

Example: True

Whether to automatically deploy new commits made to the repo

repo string optional

Example: digitalocean/sample-golang

The name of the repo in the format owner/repo. Example: digitalocean/sample-golang

image object optional
Show child properties
registry string optional

Example: registry.hub.docker.com

The registry name. Must be left empty for the DOCR registry type.

registry_type string optional

- DOCKER_HUB: The DockerHub container registry type.
- DOCR: The DigitalOcean container registry type.
- GHCR: The Github container registry type.

One of: DOCKER_HUB, DOCR, GHCR

registry_credentials string optional

Example: my-dockerhub-username:dckr_pat_the_access_token

The credentials to be able to pull the image. The value will be encrypted on first submission. On following submissions, the encrypted value should be used.
- "$username:$access_token" for registries of type DOCKER_HUB.
- "$username:$access_token" for registries of type GHCR.

repository string optional

Example: origin/master

The repository name.

tag string optional

Example: latest

The repository tag. Defaults to latest if not provided and no digest is provided. Cannot be specified if digest is provided.

Default: latest

digest string optional

Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

The image digest. Cannot be specified if tag is provided.

deploy_on_push object optional

Additional nested properties not shown. Refer to the full API spec for details.

dockerfile_path string optional

Example: path/to/Dockerfile

The path to the Dockerfile relative to the root of the repo. If set, it will be used to build this component. Otherwise, App Platform will attempt to build it using buildpacks.

build_command string optional

Example: npm run build

An optional build command to run while building this component from source.

run_command string optional

Example: bin/api

An optional run command to override the component's default.

source_dir string optional

Example: path/to/dir

An optional path to the working directory to use for the build. For Dockerfile builds, this will be used as the build context. Must be relative to the root of the repo.

envs array of objects optional

A list of environment variables made available to the component.

Show child properties
key string required

Example: BASE_URL

The variable name

scope string optional

- RUN_TIME: Made available only at run-time
- BUILD_TIME: Made available only at build-time
- RUN_AND_BUILD_TIME: Made available at both build and run-time

One of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME

Default: RUN_AND_BUILD_TIME

type string optional

- GENERAL: A plain-text environment variable
- SECRET: A secret encrypted environment variable

One of: GENERAL, SECRET

Default: GENERAL

value string optional

Example: http://example.com

The value. If the type is SECRET, the value will be encrypted on first submission. On following submissions, the encrypted value should be used.

environment_slug string optional

Example: node-js

An environment slug describing the type of this app. For a full list, please refer to the product documentation.

log_destinations array of objects optional

A list of configured log forwarding destinations.

Show child properties
name string required

Example: my_log_destination

Min length: 2

Max length: 42

papertrail object optional

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.

datadog object optional

DataDog configuration.

Additional nested properties not shown. Refer to the full API spec for details.

logtail object optional

Logtail configuration.

Additional nested properties not shown. Refer to the full API spec for details.

open_search object optional

OpenSearch configuration.

Additional nested properties not shown. Refer to the full API spec for details.

instance_count integer optional

Example: 2

The amount of instances that this component should be scaled to. Default: 1. Must not be set if autoscaling is used.

Min: 1

Default: 1

instance_size_slug object optional

Example: apps-s-1vcpu-0.5gb

The instance size to use for this component. Default: apps-s-1vcpu-0.5gb

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Show child properties
min_instance_count integer optional

Example: 2

The minimum amount of instances for this component.

Min: 1

max_instance_count integer optional

Example: 3

The maximum amount of instances for this component. Maximum 250. Consider using a larger instance size if your application requires more than 250 instances.

Min: 1

Max: 250

metrics object optional

The metrics that the component is scaled on.

Additional nested properties not shown. Refer to the full API spec for details.

termination object optional
Show child properties
grace_period_seconds integer optional

Example: 120

The number of seconds to wait between sending a TERM signal to a container and issuing a KILL which causes immediate shutdown. (Default 120)

Min: 1

Max: 600

liveness_health_check object optional
Show child properties
failure_threshold integer optional

Example: 18

The number of failed health checks before considered unhealthy.

Min: 1

Max: 50

port integer optional

Example: 80

The port on which the health check will be performed.

Min: 1

Max: 65535

http_path string optional

Example: /health

The route path used for the HTTP health check ping. If not set, the HTTP health check will be disabled and a TCP health check used instead.

initial_delay_seconds integer optional

Example: 30

The number of seconds to wait before beginning health checks.

Min: 0

Max: 3600

period_seconds integer optional

Example: 10

The number of seconds to wait between health checks.

Min: 1

Max: 300

success_threshold integer optional

Example: 1

The number of successful health checks before considered healthy.

Min: 1

Max: 1

timeout_seconds integer optional

Example: 1

The number of seconds after which the check times out.

Min: 1

Max: 120

functions array of objects optional

Workloads which expose publicly-accessible HTTP services via Functions Components.

Show child properties
cors object optional
Show child properties
allow_origins array of objects optional

Example: [{'exact': 'https://www.example.com'}, {'regex': '^.*example.com'}]

The set of allowed CORS origins.

Additional nested properties not shown. Refer to the full API spec for details.

allow_methods array of strings optional

Example: ['GET', 'OPTIONS', 'POST', 'PUT', 'PATCH', 'DELETE']

The set of allowed HTTP methods. This configures the Access-Control-Allow-Methods header.

allow_headers array of strings optional

Example: ['Content-Type', 'X-Custom-Header']

The set of allowed HTTP request headers. This configures the Access-Control-Allow-Headers header.

expose_headers array of strings optional

Example: ['Content-Encoding', 'X-Custom-Header']

The set of HTTP response headers that browsers are allowed to access. This configures the Access-Control-Expose-Headers header.

max_age string optional

Example: 5h30m

An optional duration specifying how long browsers can cache the results of a preflight request. This configures the Access-Control-Max-Age header.

allow_credentials boolean optional

Example: False

Whether browsers should expose the response to the client-side JavaScript code when the request’s credentials mode is include. This configures the Access-Control-Allow-Credentials header.

routes array of objects optional deprecated

(Deprecated - Use Ingress Rules instead). A list of HTTP routes that should be routed to this component.

Show child properties
path string optional

Example: /api

(Deprecated - Use Ingress Rules instead). An HTTP path prefix. Paths must start with / and must be unique across all components within an app.

preserve_path_prefix boolean optional

Example: True

An optional flag to preserve the path that is forwarded to the backend service. By default, the HTTP request path will be trimmed from the left when forwarded to the component. For example, a component with path=/api will have requests to /api/list trimmed to /list. If this value is true, the path will remain /api/list.

name string required

Example: api

The name. Must be unique across all components within the same app.

Min length: 2

Max length: 32

source_dir string optional

Example: path/to/dir

An optional path to the working directory to use for the build. For Dockerfile builds, this will be used as the build context. Must be relative to the root of the repo.

alerts array of objects optional
Show child properties
rule string optional

One of: UNSPECIFIED_RULE, CPU_UTILIZATION, MEM_UTILIZATION, RESTART_COUNT, DEPLOYMENT_FAILED, DEPLOYMENT_LIVE, DOMAIN_FAILED, DOMAIN_LIVE, AUTOSCALE_FAILED, AUTOSCALE_SUCCEEDED, FUNCTIONS_ACTIVATION_COUNT, FUNCTIONS_AVERAGE_DURATION_MS, FUNCTIONS_ERROR_RATE_PER_MINUTE, FUNCTIONS_AVERAGE_WAIT_TIME_MS, FUNCTIONS_ERROR_COUNT, FUNCTIONS_GB_RATE_PER_SECOND, REQUESTS_PER_SECOND, REQUEST_DURATION_P95_MS

Default: UNSPECIFIED_RULE

disabled boolean optional

Example: False

Is the alert disabled?

operator string optional

One of: UNSPECIFIED_OPERATOR, GREATER_THAN, LESS_THAN

Default: UNSPECIFIED_OPERATOR

value number optional

Example: 2.32

Threshold value for alert

window string optional

One of: UNSPECIFIED_WINDOW, FIVE_MINUTES, TEN_MINUTES, THIRTY_MINUTES, ONE_HOUR

Default: UNSPECIFIED_WINDOW

envs array of objects optional

A list of environment variables made available to the component.

Show child properties
key string required

Example: BASE_URL

The variable name

scope string optional

- RUN_TIME: Made available only at run-time
- BUILD_TIME: Made available only at build-time
- RUN_AND_BUILD_TIME: Made available at both build and run-time

One of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME

Default: RUN_AND_BUILD_TIME

type string optional

- GENERAL: A plain-text environment variable
- SECRET: A secret encrypted environment variable

One of: GENERAL, SECRET

Default: GENERAL

value string optional

Example: http://example.com

The value. If the type is SECRET, the value will be encrypted on first submission. On following submissions, the encrypted value should be used.

git object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

repo_clone_url string optional

Example: https://github.com/digitalocean/sample-golang.git

The clone URL of the repo. Example: https://github.com/digitalocean/sample-golang.git

github object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

deploy_on_push boolean optional

Example: True

Whether to automatically deploy new commits made to the repo

repo string optional

Example: digitalocean/sample-golang

The name of the repo in the format owner/repo. Example: digitalocean/sample-golang

gitlab object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

deploy_on_push boolean optional

Example: True

Whether to automatically deploy new commits made to the repo

repo string optional

Example: digitalocean/sample-golang

The name of the repo in the format owner/repo. Example: digitalocean/sample-golang

bitbucket object optional
Show child properties
branch string optional

Example: main

The name of the branch to use

deploy_on_push boolean optional

Example: True

Whether to automatically deploy new commits made to the repo

repo string optional

Example: digitalocean/sample-golang

The name of the repo in the format owner/repo. Example: digitalocean/sample-golang

log_destinations array of objects optional

A list of configured log forwarding destinations.

Show child properties
name string required

Example: my_log_destination

Min length: 2

Max length: 42

papertrail object optional

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.

datadog object optional

DataDog configuration.

Additional nested properties not shown. Refer to the full API spec for details.

logtail object optional

Logtail configuration.

Additional nested properties not shown. Refer to the full API spec for details.

open_search object optional

OpenSearch configuration.

Additional nested properties not shown. Refer to the full API spec for details.

databases array of objects optional

Database instances which can provide persistence to workloads within the
application.

Show child properties
cluster_name string optional

Example: cluster_name

The name of the underlying DigitalOcean DBaaS cluster. This is required for production databases. For dev databases, if cluster_name is not set, a new cluster will be provisioned.

db_name string optional

Example: my_db

The name of the MySQL or PostgreSQL database to configure.

db_user string optional

Example: superuser

The name of the MySQL or PostgreSQL user to configure.

engine string optional

- MYSQL: MySQL
- PG: PostgreSQL
- REDIS: Caching
- MONGODB: MongoDB
- KAFKA: Kafka
- OPENSEARCH: OpenSearch
- VALKEY: ValKey

One of: UNSET, MYSQL, PG, REDIS, MONGODB, KAFKA, OPENSEARCH, VALKEY

Default: UNSET

name string required

Example: prod-db

The database's name. The name must be unique across all components within the same app and cannot use capital letters.

Min length: 2

Max length: 32

production boolean optional

Example: True

Whether this is a production or dev database.

version string optional

Example: 12

The version of the database engine

ingress object optional

Specification for app ingress configurations.

Show child properties
rules array of objects optional

Rules for configuring HTTP ingress for component routes, CORS, rewrites, and redirects.

Show child properties
match object optional

The match configuration for the rule.

Additional nested properties not shown. Refer to the full API spec for details.

cors object optional

Additional nested properties not shown. Refer to the full API spec for details.

component object optional

The component to route to. Only one of component or redirect may be set.

Additional nested properties not shown. Refer to the full API spec for details.

redirect object optional

The redirect configuration for the rule. Only one of component or redirect may be set.

Additional nested properties not shown. Refer to the full API spec for details.

egress object optional

Specification for app egress configurations.

Show child properties
type string optional

One of: AUTOASSIGN, DEDICATED_IP

Default: AUTOASSIGN

maintenance object optional

Specification to configure maintenance settings for the app, such as maintenance mode and archiving the app.

Show child properties
enabled boolean optional

Example: True

Indicates whether maintenance mode should be enabled for the app.

archive boolean optional

Example: True

Indicates whether the app should be archived. Setting this to true implies that enabled is set to true.

offline_page_url string optional

Example: https://example.com/offline.html

A custom offline page to display when maintenance mode is enabled or the app is archived.

vpc object optional read-only
Show child properties
id string optional

Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac

egress_ips array of objects optional
Show child properties
ip string optional

Example: 10.0.0.1

project_id string optional

The ID of the project the app should be assigned to. If omitted, it will be assigned to your default project.


Requires project:update scope.

Request Sample

Show Request Sample 
import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))

create_resp = client.apps.create(
    {
        "spec": {
            "name": "web-app",
            "region": "nyc",
            "services": [
                {
                    "name": "api",
                    "github": {},
                    "run_command": "bin/api",
                    "environment_slug": "node-js",
                    "instance_count": 2,
                    "instance_size_slug": "apps-s-1vcpu-0.5gb",
                    "routes": [],
                }
            ],
        }
    }
)

Response Example

Show Response Example 
{
  "app": {
    "id": "c2a93513-8d9b-4223-9d61-5e7272c81cf5",
    "owner_uuid": "a4e16f25-cdd1-4483-b246-d77f283c9209",
    "spec": {
      "name": "sample-golang",
      "disable_edge_cache": true,
      "enhanced_threat_control_enabled": true,
      "services": [
        {
          "name": "web",
          "github": {
            "repo": "ChiefMateStarbuck/sample-golang",
            "branch": "main"
          },
          "run_command": "bin/sample-golang",
          "environment_slug": "go",
          "instance_size_slug": "apps-s-1vcpu-0.5gb",
          "instance_count": 1,
          "http_port": 8080,
          "routes": [
            {
              "path": "/"
            }
          ]
        }
      ],
      "region": "ams",
      "domains": [
        {
          "domain": "sample-golang.example.com",
          "zone": "example.com",
          "minimum_tls_version": "1.3"
        }
      ],
      "vpc": {
        "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac",
        "egress_ips": [
          {
            "ip": "10.0.0.1"
          }
        ]
      }
    },
    "default_ingress": "https://sample-golang-zyhgn.ondigitalocean.app",
    "created_at": "2021-02-10T16:45:14Z",
    "updated_at": "2021-02-10T17:06:56Z",
    "active_deployment": {
      "id": "991dfa59-6a23-459f-86d6-67dfa2c6f1e3",
      "spec": {
        "name": "sample-golang",
        "services": [
          {
            "name": "web",
            "github": {
              "repo": "ChiefMateStarbuck/sample-golang",
              "branch": "main"
            },
            "run_command": "bin/sample-golang",
            "environment_slug": "go",
            "instance_size_slug": "apps-s-1vcpu-0.5gb",
            "instance_count": 1,
            "http_port": 8080,
            "routes": [
              {
                "path": "/"
              }
            ]
          }
        ],
        "region": "ams",
        "domains": [
          {
            "domain": "sample-golang.example.com",
            "zone": "example.com",
            "minimum_tls_version": "1.3"
          }
        ],
        "vpc": {
          "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac",
          "egress_ips": [
            {
              "ip": "10.0.0.1"
            }
          ]
        }
      },
      "services": [
        {
          "name": "web",
          "source_commit_hash": "db6936cb46047c576962962eed81ad52c21f35d7"
        }
      ],
      "phase_last_updated_at": "2021-02-10T17:06:53Z",
      "created_at": "2021-02-10T17:05:30Z",
      "updated_at": "2021-02-10T17:06:53Z",
      "cause": "manual",
      "progress": {
        "success_steps": 6,
        "total_steps": 6,
        "steps": [
          {
            "name": "build",
            "status": "SUCCESS",
            "steps": [
              {
                "name": "initialize",
                "status": "SUCCESS",
                "started_at": "2021-02-10T17:05:35.572347485Z",
                "ended_at": "2021-02-10T17:05:36.093995229Z"
              },
              {
                "name": "components",
                "status": "SUCCESS",
                "steps": [
                  {
                    "name": "web",
                    "status": "SUCCESS",
                    "component_name": "web",
                    "message_base": "Building service"
                  }
                ],
                "started_at": "2021-02-10T17:05:36.094015928Z",
                "ended_at": "2021-02-10T17:06:19.461737040Z"
              }
            ],
            "started_at": "2021-02-10T17:05:35.572287990Z",
            "ended_at": "2021-02-10T17:06:19.807834070Z"
          },
          {
            "name": "deploy",
            "status": "SUCCESS",
            "steps": [
              {
                "name": "initialize",
                "status": "SUCCESS",
                "started_at": "2021-02-10T17:06:25.143957508Z",
                "ended_at": "2021-02-10T17:06:26.120343872Z"
              },
              {
                "name": "components",
                "status": "SUCCESS",
                "steps": [
                  {
                    "name": "web",
                    "status": "SUCCESS",
                    "steps": [
                      {
                        "name": "deploy",
                        "status": "SUCCESS",
                        "component_name": "web",
                        "message_base": "Deploying service"
                      },
                      {
                        "name": "wait",
                        "status": "SUCCESS",
                        "component_name": "web",
                        "message_base": "Waiting for service"
                      }
                    ],
                    "component_name": "web"
                  }
                ],
                "started_at": "2021-02-10T17:06:26.120385561Z",
                "ended_at": "2021-02-10T17:06:50.029695913Z"
              },
              {
                "name": "finalize",
                "status": "SUCCESS",
                "started_at": "2021-02-10T17:06:50.348459495Z",
                "ended_at": "2021-02-10T17:06:53.404065961Z"
              }
            ],
            "started_at": "2021-02-10T17:06:25.143932418Z",
            "ended_at": "2021-02-10T17:06:53.404104185Z"
          }
        ]
      },
      "phase": "ACTIVE",
      "tier_slug": "basic"
    },
    "last_deployment_created_at": "2021-02-10T17:05:30Z",
    "live_url": "https://sample-golang-zyhgn.ondigitalocean.app",
    "pending_deployment": {
      "id": "3aa4d20e-5527-4c00-b496-601fbd22520a",
      "spec": {
        "name": "sample-php",
        "services": [
          {
            "name": "sample-php",
            "git": {
              "repo_clone_url": "https://github.com/digitalocean/sample-php.git",
              "branch": "main"
            },
            "run_command": "heroku-php-apache2",
            "environment_slug": "php",
            "instance_size_slug": "apps-s-1vcpu-0.5gb",
            "instance_count": 1,
            "http_port": 8080,
            "routes": [
              {
                "path": "/"
              }
            ]
          }
        ],
        "region": "fra",
        "domains": [
          {
            "domain": "sample-php.example.com",
            "type": "PRIMARY",
            "zone": "example.com",
            "minimum_tls_version": "1.3"
          }
        ],
        "vpc": {
          "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac",
          "egress_ips": [
            {
              "ip": "10.0.0.1"
            }
          ]
        }
      }
    },
    "region": {
      "slug": "ams",
      "label": "Amsterdam",
      "flag": "netherlands",
      "continent": "Europe",
      "data_centers": [
        "ams3"
      ]
    },
    "tier_slug": "basic",
    "live_url_base": "https://sample-golang-zyhgn.ondigitalocean.app",
    "live_domain": "sample-golang-zyhgn.ondigitalocean.app",
    "project_id": "88b72d1a-b78a-4d9f-9090-b53c4399073f",
    "domains": [
      {
        "id": "e206c64e-a1a3-11ed-9e6e-9b7b6dc9a52b",
        "phase": "CONFIGURING",
        "spec": {
          "domain": "sample-golang.example.com",
          "type": "PRIMARY",
          "zone": "example.com",
          "minimum_tls_version": "1.3"
        },
        "rotate_validation_records": false,
        "certificate_expires_at": "2024-01-29T23:59:59Z",
        "progress": {
          "steps": [
            {
              "ended_at": "0001-01-01T00:00:00Z",
              "name": "default-ingress-ready",
              "started_at": "2023-01-30T22:15:45.021896292Z",
              "status": "SUCCESS"
            },
            {
              "ended_at": "0001-01-01T00:00:00Z",
              "name": "ensure-zone",
              "started_at": "2023-01-30T22:15:45.022017004Z",
              "status": "SUCCESS"
            },
            {
              "ended_at": "2023-01-30T15:42:28.50752065Z",
              "name": "ensure-ns-records",
              "started_at": "2023-01-30T22:15:45.025567874Z",
              "status": "SUCCESS"
            },
            {
              "ended_at": "0001-01-01T00:00:00Z",
              "name": "verify-nameservers",
              "started_at": "2023-01-30T22:15:45.033591906Z",
              "status": "SUCCESS"
            },
            {
              "ended_at": "0001-01-01T00:00:00Z",
              "name": "ensure-record",
              "started_at": "2023-01-30T22:15:45.156750604Z",
              "status": "SUCCESS"
            },
            {
              "ended_at": "2023-01-30T15:43:30.258626422Z",
              "name": "ensure-alias-record",
              "started_at": "2023-01-30T22:15:45.165933869Z",
              "status": "SUCCESS"
            },
            {
              "ended_at": "2023-01-30T15:43:30.258808279Z",
              "name": "ensure-wildcard-record",
              "started_at": "2023-01-30T22:15:45.166093422Z",
              "status": "SUCCESS"
            },
            {
              "ended_at": "0001-01-01T00:00:00Z",
              "name": "verify-cname",
              "started_at": "2023-01-30T22:15:45.166205559Z",
              "status": "SUCCESS"
            },
            {
              "ended_at": "2023-01-30T15:43:30.475903785Z",
              "name": "ensure-ssl-txt-record-saved",
              "started_at": "2023-01-30T22:15:45.295237186Z",
              "status": "SUCCESS"
            },
            {
              "ended_at": "2023-01-30T15:43:30.476017236Z",
              "name": "ensure-ssl-txt-record",
              "started_at": "2023-01-30T22:15:45.295315291Z",
              "status": "SUCCESS"
            },
            {
              "ended_at": "2023-01-30T15:43:30.476094058Z",
              "name": "ensure-renewal-email",
              "started_at": "2023-01-30T22:15:45.295374087Z",
              "status": "SUCCESS"
            },
            {
              "ended_at": "0001-01-01T00:00:00Z",
              "name": "ensure-CA-authorization",
              "started_at": "2023-01-30T22:15:45.295428101Z",
              "status": "SUCCESS"
            },
            {
              "ended_at": "0001-01-01T00:00:00Z",
              "name": "ensure-certificate",
              "started_at": "2023-01-30T22:15:45.978756406Z",
              "status": "RUNNING"
            },
            {
              "ended_at": "0001-01-01T00:00:00",
              "name": "create-deployment",
              "started_at": "0001-01-01T00:00:00Z",
              "status": "PENDING"
            },
            {
              "ended_at": "0001-01-01T00:00:00",
              "name": "configuration-alert",
              "started_at": "0001-01-01T00:00:00",
              "status": "PENDING"
            }
          ]
        }
      }
    ],
    "dedicated_ips": [
      {
        "ip": "192.168.1.1",
        "id": "c24d8f48-3bc4-49f5-8ca0-58e8164427ac",
        "status": "ASSIGNED"
      },
      {
        "ip": "192.168.1.2",
        "id": "4768fb15-2837-4dda-9be5-3951df4bc3d0",
        "status": "ASSIGNED"
      }
    ],
    "vpc": {
      "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac",
      "egress_ips": [
        {
          "ip": "10.0.0.1"
        }
      ]
    }
  }
}

More Information

See /v2/apps in the API reference for additional detail on responses, headers, parameters, and more.

We can't find any results for your search.

Try using different keywords or simplifying your search terms.