App Platform API Reference

Validated on 16 Jun 2022 • Last edited on 23 Mar 2026

View full API reference

App Platform is a Platform-as-a-Service (PaaS) offering from DigitalOcean that allows developers to publish code directly to DigitalOcean servers without worrying about the underlying infrastructure.

Most API operations are centered around a few core object types. Following are the definitions of these types. These definitions will be omitted from the operation-specific documentation.

For documentation on app specifications (AppSpec objects), please refer to the product documentation).

Base URL https://api.digitalocean.com

Endpoints

GET List All Apps POST Create a New App POST Retrieve Multiple Apps' Daily Bandwidth Metrics POST Propose an App Spec GET List App Regions GET List Instance Sizes GET Retrieve an Instance Size GET List all app alerts POST Update destinations for alerts GET Retrieve Exec URL GET Retrieve Active Deployment Logs GET List App Deployments POST Create an App Deployment GET Retrieve an App Deployment POST Cancel a Deployment GET Retrieve Exec URL for Deployment GET Retrieve Deployment Logs GET Retrieve Aggregate Deployment Logs GET List App Events GET Get an Event POST Cancel an Event GET Retrieve Event Logs GET Retrieve App Health GET Retrieve App Instances GET List Job Invocations GET Get Job Invocations POST Cancel Job Invocation GET Retrieve Job Invocation Logs GET Retrieve Active Deployment Aggregate Logs GET Retrieve App Daily Bandwidth Metrics POST Restart an App POST Rollback App POST Commit App Rollback POST Revert App Rollback POST Validate App Rollback GET Retrieve an Existing App PUT Update an App DELETE Delete an App

GET List All Apps

/v2/apps
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

List all apps on your account. Information about the current active deployment as well as any in progress ones will also be included for each app.

Query Parameters

page integer >= 1 optional
Example: 1

Which 'page' of paginated results to return.

Default: 1
per_page integer 1 – 200 optional
Example: 2

Number of items returned per page

Default: 20
with_projects boolean optional
Example: true

Whether the project_id of listed apps should be fetched and included.

Request: /v2/apps
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps"
import os
from pydo import Client

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

get_resp = client.apps.list()

Responses

200

A JSON object with a apps key. This is list of object apps.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
apps array of object optional
Show child properties
active_deployment object optional
Show child properties
cause string optional
Example: commit 9a4df0b pushed to github/digitalocean/sample-golang
cloned_from string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a
created_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
functions array of object optional
Show child properties
name string optional
Example: my-functions-component
namespace string optional
Example: ap-b2a93513-8d9b-4223-9d61-5e7272c81c32

The namespace where the functions are deployed.

source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405

The commit hash of the repository that was used to build this functions component.

id string optional
Example: b6bdf840-2854-4f87-a36c-5f231c617c84
jobs array of object optional
Show child properties
name string optional
Example: migrate-db
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
phase string (enum) optional
Example: ACTIVE
phase_last_updated_at string (date-time) optional
Example: 0001-01-01T00:00:00Z
progress object optional
Show child properties
error_steps integer (int32) optional
Example: 3
pending_steps integer (int32) optional
Example: 2
running_steps integer (int32) optional
Example: 2
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
success_steps integer (int32) optional
Example: 4
summary_steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
total_steps integer (int32) optional
Example: 5
services array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
spec object optional

The desired configuration of an application.

Show child properties
databases array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

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

domains array of object optional

A set of hostnames where the application will be available.

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

Specification for app egress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
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.

functions array of object optional

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

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

Specification for app ingress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

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

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

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Additional nested properties not shown. Refer to the full API spec for details.
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
workers array of object optional
Show child properties
name string optional
Example: queue-runner
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
created_at string (date-time) optional read-only
Example: 2020-11-19T20:27:18Z
dedicated_ips array of object optional read-only
Show child properties
id string optional
Example: 9e7bc2ac-205a-45d6-919c-e1ac5e73f962
ip string optional
Example: 192.168.1.1
status string, one of: UNKNOWN, ASSIGNING, ASSIGNED, REMOVED optional read-only
Example: ASSIGNED
default_ingress string optional read-only
Example: digitalocean.com
domains array of object optional read-only
Show child properties
certificate_expires_at string (date-time) optional read-only
Example: 2024-01-29T23:59:59Z
id string optional
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf
phase string, one of: UNKNOWN, PENDING, CONFIGURING, ACTIVE, ERROR optional
Example: ACTIVE
progress object optional
Show child properties
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
rotate_validation_records boolean optional read-only
spec object optional
Show child properties
domain string required
Example: app.example.com

The hostname for the domain

minimum_tls_version string, one of: 1.2, 1.3 optional
Example: 1.3

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

type string, one of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS optional
Example: DEFAULT
  • 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
wildcard boolean optional
Example: true

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

zone string (hostname) 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.

validations array of object optional
Show child properties
txt_name string optional read-only
Example: _acme-challenge.app.example.com
txt_value string optional read-only
Example: lXLOcN6cPv0nproViNcUHcahD9TrIPlNgdwesj0pYpk
id string optional read-only
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf
in_progress_deployment object optional
Show child properties
cause string optional
Example: commit 9a4df0b pushed to github/digitalocean/sample-golang
cloned_from string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a
created_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
functions array of object optional
Show child properties
name string optional
Example: my-functions-component
namespace string optional
Example: ap-b2a93513-8d9b-4223-9d61-5e7272c81c32

The namespace where the functions are deployed.

source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405

The commit hash of the repository that was used to build this functions component.

id string optional
Example: b6bdf840-2854-4f87-a36c-5f231c617c84
jobs array of object optional
Show child properties
name string optional
Example: migrate-db
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
phase string (enum) optional
Example: ACTIVE
phase_last_updated_at string (date-time) optional
Example: 0001-01-01T00:00:00Z
progress object optional
Show child properties
error_steps integer (int32) optional
Example: 3
pending_steps integer (int32) optional
Example: 2
running_steps integer (int32) optional
Example: 2
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
success_steps integer (int32) optional
Example: 4
summary_steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
total_steps integer (int32) optional
Example: 5
services array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
spec object optional

The desired configuration of an application.

Show child properties
databases array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

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

domains array of object optional

A set of hostnames where the application will be available.

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

Specification for app egress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
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.

functions array of object optional

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

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

Specification for app ingress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

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

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

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Additional nested properties not shown. Refer to the full API spec for details.
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
workers array of object optional
Show child properties
name string optional
Example: queue-runner
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
last_deployment_created_at string (date-time) optional read-only
Example: 2020-11-19T20:27:18Z
live_domain string optional read-only
Example: live_domain
live_url string optional read-only
Example: google.com
live_url_base string optional read-only
Example: digitalocean.com
owner_uuid string optional read-only
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf
pending_deployment object optional
pinned_deployment object optional
project_id string optional read-only
Example: 88b72d1a-b78a-4d9f-9090-b53c4399073f

Requires project:read scope.

region object optional
Show child properties
continent string optional read-only
Example: europe
data_centers array of string optional read-only
Example: ["ams"]
default boolean optional read-only
Example: true

Whether or not the region is presented as the default.

disabled boolean optional read-only
Example: true
flag string optional read-only
Example: ams
label string optional read-only
Example: ams
reason string optional read-only
Example: to crowded
slug string optional read-only
Example: basic
spec object required

The desired configuration of an application.

Show child properties
databases array of object 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 (enum) optional
Example: PG
  • MYSQL: MySQL
  • PG: PostgreSQL
  • REDIS: Caching
  • MONGODB: MongoDB
  • KAFKA: Kafka
  • OPENSEARCH: OpenSearch
  • VALKEY: ValKey
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.

production boolean optional
Example: true

Whether this is a production or dev database.

version string optional
Example: 12

The version of the database engine

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.

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

domains array of object 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

minimum_tls_version string, one of: 1.2, 1.3 optional
Example: 1.3

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

type string, one of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS optional
Example: DEFAULT
  • 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
wildcard boolean optional
Example: true

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

zone string (hostname) 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.

egress object optional

Specification for app egress configurations.

Show child properties
type string, one of: AUTOASSIGN, DEDICATED_IP optional
Example: AUTOASSIGN
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.

functions array of object optional

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

Show child properties
alerts array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
cors object optional
envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: api

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

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

ingress object optional

Specification for app ingress configurations.

Show child properties
rules array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

kind string, one of: UNSPECIFIED, PRE_DEPLOY, POST_DEPLOY, FAILED_DEPLOY optional
Example: PRE_DEPLOY
  • 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.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
maintenance object optional

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

Show child properties
archive boolean optional
Example: true

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

enabled boolean optional
Example: true

Indicates whether maintenance mode should be enabled for the app.

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.

name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

cors object optional
health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
http_port integer (int64) 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.

internal_ports array of integer (int64) optional
Example: [80,443]

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

Additional nested properties not shown. Refer to the full API spec for details.
liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
protocol string, one of: HTTP, HTTP2 optional
Example: HTTP

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).
routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

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.

cors object optional
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.

index_document string optional
Example: main.html

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

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.

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Show child properties
egress_ips array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
id string optional
Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional read-only
Example: 2020-12-01T00:42:16Z
vpc object optional read-only
Show child properties
egress_ips array of object optional
Show child properties
ip string optional
Example: 10.0.0.1
id string optional
Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac
links object optional
Show child properties
pages anyOf optional
One of:
Forward Links
last string optional
Example: https://api.digitalocean.com/v2/images?page=2

URI of the last page of the results.

next string optional
Example: https://api.digitalocean.com/v2/images?page=2

URI of the next page of the results.

Backward Links
first string optional
Example: https://api.digitalocean.com/v2/images?page=1

URI of the first page of the results.

prev string optional
Example: https://api.digitalocean.com/v2/images?page=1

URI of the previous page of the results.

meta object required
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "apps": [
    {
      "active_deployment": {
        "created_at": "2020-12-01T00:40:05Z",
        "id": "3aa4d20e-5527-4c00-b496-601fbd22520a",
        "phase_last_updated_at": "2020-12-01T00:42:12Z",
        "services": [
          {
            "name": "sample-php",
            "source_commit_hash": "54d4a727f457231062439895000d45437c7bb405"
          }
        ],
        "spec": {
          "domains": [
            {
              "domain": "sample-php.example.com",
              "minimum_tls_version": "1.3",
              "type": "PRIMARY",
              "zone": "example.com"
            }
          ],
          "name": "sample-php",
          "region": "fra",
          "services": [
            {
              "environment_slug": "php",
              "git": {
                "branch": "main",
                "repo_clone_url": "https://github.com/digitalocean/sample-php.git"
              },
              "http_port": 8080,
              "instance_count": 1,
              "instance_size_slug": "apps-s-1vcpu-0.5gb",
              "name": "sample-php",
              "routes": [
                {
                  "path": "/"
                }
              ],
              "run_command": "heroku-php-apache2"
            }
          ],
          "vpc": {
            "egress_ips": [
              {
                "ip": "10.0.0.1"
              }
            ],
            "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac"
          }
        },
        "updated_at": "2020-12-01T00:42:12Z"
      },
      "cause": "app spec updated",
      "created_at": "2020-11-19T20:27:18Z",
      "dedicated_ips": [
        {
          "id": "c24d8f48-3bc4-49f5-8ca0-58e8164427ac",
          "ip": "192.168.1.1",
          "status": "ASSIGNED"
        },
        {
          "id": "4768fb15-2837-4dda-9be5-3951df4bc3d0",
          "ip": "192.168.1.2",
          "status": "ASSIGNED"
        }
      ],
      "default_ingress": "https://sample-php-iaj87.ondigitalocean.app",
      "domains": [
        {
          "certificate_expires_at": "2024-01-29T23:59:59Z",
          "id": "0831f444-a1a7-11ed-828c-ef59494480b5",
          "phase": "ACTIVE",
          "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": "SUCCESS"
              },
              {
                "ended_at": "2023-01-30T15:43:52.570612857Z",
                "name": "create-deployment",
                "started_at": "0001-01-01T00:00:00Z",
                "status": "SUCCESS"
              },
              {
                "ended_at": "2023-01-30T15:43:31.333582377Z",
                "name": "configuration-alert",
                "started_at": "2023-01-30T22:15:46.278987808Z",
                "status": "SUCCESS"
              }
            ]
          },
          "rotate_validation_records": false,
          "spec": {
            "domain": "sample-php.example.com",
            "minimum_tls_version": "1.3",
            "type": "PRIMARY",
            "zone": "example.com"
          }
        }
      ],
      "id": "4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf",
      "last_deployment_created_at": "2020-12-01T00:40:05Z",
      "live_domain": "sample-php.example.com",
      "live_url": "https://sample-php.example.com",
      "live_url_base": "https://sample-php.example.com",
      "owner_uuid": "ff36cbc6fd350fe12577f5123133bb5ba01a2419",
      "pending_deployment": {
        "created_at": "2020-12-01T00:40:05Z",
        "id": "3aa4d20e-5527-4c00-b496-601fbd22520a",
        "phase_last_updated_at": "2020-12-01T00:42:12Z",
        "services": [
          {
            "name": "sample-php",
            "source_commit_hash": "54d4a727f457231062439895000d45437c7bb405"
          }
        ],
        "spec": {
          "domains": [
            {
              "domain": "sample-php.example.com",
              "minimum_tls_version": "1.3",
              "type": "PRIMARY",
              "zone": "example.com"
            }
          ],
          "name": "sample-php",
          "region": "fra",
          "services": [
            {
              "environment_slug": "php",
              "git": {
                "branch": "main",
                "repo_clone_url": "https://github.com/digitalocean/sample-php.git"
              },
              "http_port": 8080,
              "instance_count": 1,
              "instance_size_slug": "apps-s-1vcpu-0.5gb",
              "name": "sample-php",
              "routes": [
                {
                  "path": "/"
                }
              ],
              "run_command": "heroku-php-apache2"
            }
          ],
          "vpc": {
            "egress_ips": [
              {
                "ip": "10.0.0.1"
              }
            ],
            "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac"
          }
        },
        "updated_at": "2020-12-01T00:42:12Z"
      },
      "progress": {
        "phase": "ACTIVE",
        "steps": [
          {
            "ended_at": "2020-12-01T00:41:26.653989756Z",
            "name": "build",
            "started_at": "2020-12-01T00:40:11.979257919Z",
            "status": "SUCCESS",
            "steps": [
              {
                "ended_at": "2020-12-01T00:40:12.470972033Z",
                "name": "initialize",
                "started_at": "2020-12-01T00:40:11.979305214Z",
                "status": "SUCCESS"
              },
              {
                "ended_at": "2020-12-01T00:41:26.180360487Z",
                "name": "components",
                "started_at": "2020-12-01T00:40:12.470996857Z",
                "status": "SUCCESS",
                "steps": [
                  {
                    "component_name": "sample-php",
                    "ended_at": "0001-01-01T00:00:00Z",
                    "message_base": "Building service",
                    "name": "sample-php",
                    "started_at": "0001-01-01T00:00:00Z",
                    "status": "SUCCESS"
                  }
                ]
              }
            ]
          }
        ],
        "success_steps": 6,
        "tier_slug": "basic",
        "total_steps": 6
      },
      "region": {
        "continent": "Europe",
        "data_centers": [
          "fra1"
        ],
        "flag": "germany",
        "label": "Frankfurt",
        "slug": "fra"
      },
      "spec": {
        "domains": [
          {
            "domain": "sample-php.example.com",
            "minimum_tls_version": "1.3",
            "type": "PRIMARY",
            "zone": "example.com"
          }
        ],
        "name": "sample-php",
        "services": [
          {
            "environment_slug": "php",
            "git": {
              "branch": "main",
              "repo_clone_url": "https://github.com/digitalocean/sample-php.git"
            },
            "http_port": 8080,
            "instance_count": 1,
            "instance_size_slug": "apps-s-1vcpu-0.5gb",
            "name": "sample-php",
            "routes": [
              {
                "path": "/"
              }
            ],
            "run_command": "heroku-php-apache2"
          }
        ],
        "vpc": {
          "egress_ips": [
            {
              "ip": "10.0.0.1"
            }
          ],
          "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac"
        }
      },
      "tier_slug": "basic",
      "updated_at": "2020-12-01T00:42:16Z",
      "vpc": {
        "egress_ips": [
          {
            "ip": "10.0.0.1"
          }
        ],
        "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac"
      }
    }
  ],
  "links": {
    "pages": {}
  },
  "meta": {
    "total": 1
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Create a New App

/v2/apps
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:create

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

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

Header Parameters

Accept string, one of: application/json, application/yaml optional
Example: application/json

The content-type that should be used by the response. By default, the response will be application/json. application/yaml is also supported.

Content-Type string, one of: application/json, application/yaml optional
Example: application/json

The content-type used for the request. By default, the requests are assumed to use application/json. application/yaml is also supported.

Request Body: application/json

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.

spec object required

The desired configuration of an application.

Show child properties
databases array of object 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 (enum) optional
Example: PG
  • MYSQL: MySQL
  • PG: PostgreSQL
  • REDIS: Caching
  • MONGODB: MongoDB
  • KAFKA: Kafka
  • OPENSEARCH: OpenSearch
  • VALKEY: ValKey
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.

production boolean optional
Example: true

Whether this is a production or dev database.

version string optional
Example: 12

The version of the database engine

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.

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

domains array of object 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

minimum_tls_version string, one of: 1.2, 1.3 optional
Example: 1.3

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

type string, one of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS optional
Example: DEFAULT
  • 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
wildcard boolean optional
Example: true

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

zone string (hostname) 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.

egress object optional

Specification for app egress configurations.

Show child properties
type string, one of: AUTOASSIGN, DEDICATED_IP optional
Example: AUTOASSIGN
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.

functions array of object optional

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

Show child properties
alerts array of object optional
Show child properties
disabled boolean optional
Example: false

Is the alert disabled?

operator string, one of: UNSPECIFIED_OPERATOR, GREATER_THAN, LESS_THAN optional
Example: GREATER_THAN
rule string (enum) optional
Example: CPU_UTILIZATION
value number (float) optional
Example: 2.32

Threshold value for alert

window string, one of: UNSPECIFIED_WINDOW, FIVE_MINUTES, TEN_MINUTES, THIRTY_MINUTES, ONE_HOUR optional
Example: FIVE_MINUTES
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

cors object optional
envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: api

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

routes array of object 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.

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.

ingress object optional

Specification for app ingress configurations.

Show child properties
rules array of object optional

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

Show child properties
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.
cors object optional
Additional nested properties not shown. Refer to the full API spec for details.
match object optional

The match configuration for the rule.

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.
jobs array of object optional

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

Show child properties
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

build_command string optional
Example: npm run build

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

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.

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.

envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

image object optional
Show child properties
deploy_on_push object optional
Additional nested properties not shown. Refer to the full API spec for details.
digest string optional
Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

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

registry string optional
Example: registry.hub.docker.com

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

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.
registry_type string, one of: DOCKER_HUB, DOCR, GHCR optional
Example: DOCR
  • DOCKER_HUB: The DockerHub container registry type.
  • DOCR: The DigitalOcean container registry type.
  • GHCR: The Github container registry type.
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.

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Show child properties
max_instance_count integer (uint32) optional
Example: 3

The maximum amount of instances for this component. Must be more than min_instance_count.

metrics object optional

The metrics that the component is scaled on.

Additional nested properties not shown. Refer to the full API spec for details.
min_instance_count integer (uint32) optional
Example: 2

The minimum amount of instances for this component. Must be less than max_instance_count.

instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

kind string, one of: UNSPECIFIED, PRE_DEPLOY, POST_DEPLOY, FAILED_DEPLOY optional
Example: PRE_DEPLOY
  • 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.
termination object optional
Show child properties
grace_period_seconds integer (int32) 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)

maintenance object optional

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

Show child properties
archive boolean optional
Example: true

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

enabled boolean optional
Example: true

Indicates whether maintenance mode should be enabled for the app.

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.

name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Show child properties
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

build_command string optional
Example: npm run build

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

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.

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.

envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

image object optional
Show child properties
deploy_on_push object optional
Additional nested properties not shown. Refer to the full API spec for details.
digest string optional
Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

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

registry string optional
Example: registry.hub.docker.com

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

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.
registry_type string, one of: DOCKER_HUB, DOCR, GHCR optional
Example: DOCR
  • DOCKER_HUB: The DockerHub container registry type.
  • DOCR: The DigitalOcean container registry type.
  • GHCR: The Github container registry type.
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.

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Show child properties
max_instance_count integer (uint32) optional
Example: 3

The maximum amount of instances for this component. Must be more than min_instance_count.

metrics object optional

The metrics that the component is scaled on.

Additional nested properties not shown. Refer to the full API spec for details.
min_instance_count integer (uint32) optional
Example: 2

The minimum amount of instances for this component. Must be less than max_instance_count.

instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

cors object optional
health_check object optional
Show child properties
failure_threshold integer (int32) optional
Example: 2

The number of failed health checks before considered unhealthy.

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 (int32) optional
Example: 30

The number of seconds to wait before beginning health checks.

period_seconds integer (int32) optional
Example: 60

The number of seconds to wait between health checks.

port integer (int64) 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.

success_threshold integer (int32) optional
Example: 3

The number of successful health checks before considered healthy.

timeout_seconds integer (int32) optional
Example: 45

The number of seconds after which the check times out.

http_port integer (int64) 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.

internal_ports array of integer (int64) optional
Example: [80,443]

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

liveness_health_check object optional
Show child properties
failure_threshold integer (int32) optional
Example: 18

The number of failed health checks before considered unhealthy.

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 (int32) optional
Example: 30

The number of seconds to wait before beginning health checks.

period_seconds integer (int32) optional
Example: 10

The number of seconds to wait between health checks.

port integer (int64) optional
Example: 80

The port on which the health check will be performed.

success_threshold integer (int32) optional
Example: 1

The number of successful health checks before considered healthy.

timeout_seconds integer (int32) optional
Example: 1

The number of seconds after which the check times out.

protocol string, one of: HTTP, HTTP2 optional
Example: HTTP

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).
routes array of object 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 (int32) 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)

grace_period_seconds integer (int32) 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)

static_sites array of object optional

Content which can be rendered to static web assets.

Show child properties
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

build_command string optional
Example: npm run build

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

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.

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.

envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

image object optional
Show child properties
deploy_on_push object optional
Additional nested properties not shown. Refer to the full API spec for details.
digest string optional
Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

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

registry string optional
Example: registry.hub.docker.com

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

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.
registry_type string, one of: DOCKER_HUB, DOCR, GHCR optional
Example: DOCR
  • DOCKER_HUB: The DockerHub container registry type.
  • DOCR: The DigitalOcean container registry type.
  • GHCR: The Github container registry type.
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.

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

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.

cors object optional
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.

index_document string optional
Example: main.html

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

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.

routes array of object 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.

vpc object optional read-only
Show child properties
egress_ips array of object optional
Show child properties
ip string optional
Example: 10.0.0.1
id string optional
Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Show child properties
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

build_command string optional
Example: npm run build

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

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.

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.

envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

image object optional
Show child properties
deploy_on_push object optional
Additional nested properties not shown. Refer to the full API spec for details.
digest string optional
Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

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

registry string optional
Example: registry.hub.docker.com

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

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.
registry_type string, one of: DOCKER_HUB, DOCR, GHCR optional
Example: DOCR
  • DOCKER_HUB: The DockerHub container registry type.
  • DOCR: The DigitalOcean container registry type.
  • GHCR: The Github container registry type.
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.

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Show child properties
max_instance_count integer (uint32) optional
Example: 3

The maximum amount of instances for this component. Must be more than min_instance_count.

metrics object optional

The metrics that the component is scaled on.

Additional nested properties not shown. Refer to the full API spec for details.
min_instance_count integer (uint32) optional
Example: 2

The minimum amount of instances for this component. Must be less than max_instance_count.

instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

liveness_health_check object optional
Show child properties
failure_threshold integer (int32) optional
Example: 18

The number of failed health checks before considered unhealthy.

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 (int32) optional
Example: 30

The number of seconds to wait before beginning health checks.

period_seconds integer (int32) optional
Example: 10

The number of seconds to wait between health checks.

port integer (int64) optional
Example: 80

The port on which the health check will be performed.

success_threshold integer (int32) optional
Example: 1

The number of successful health checks before considered healthy.

timeout_seconds integer (int32) optional
Example: 1

The number of seconds after which the check times out.

termination object optional
Show child properties
grace_period_seconds integer (int32) 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)

Request: /v2/apps
Content type application/json 
{
  "spec": {
    "disable_edge_cache": true,
    "disable_email_obfuscation": false,
    "egress": {
      "type": "DEDICATED_IP"
    },
    "enhanced_threat_control_enabled": true,
    "name": "web-app",
    "region": "nyc",
    "services": [
      {
        "environment_slug": "node-js",
        "github": {
          "branch": "main",
          "deploy_on_push": true,
          "repo": "digitalocean/sample-golang"
        },
        "instance_count": 2,
        "instance_size_slug": "apps-s-1vcpu-0.5gb",
        "name": "api",
        "routes": [
          {
            "path": "/api"
          }
        ],
        "run_command": "bin/api"
      }
    ],
    "vpc": {
      "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac"
    }
  }
}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps"
  -d '{"spec":{"name":"web-app","region":"nyc", \
  "services":[{"name":"api","github":{"branch":"main",\
  "deploy_on_push":true,"repo":"digitalocean/sample-golang"}, \
  "run_command":"bin/api","environment_slug":"node-js", \
  "instance_count":2,"instance_size_slug":"apps-s-1vcpu-0.5gb", \
  "routes":[{"path":"/api"}]}]}}'
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": [],
                }
            ],
        }
    }
)

Responses

200

A JSON or YAML of a spec object.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
app object optional

An application's configuration and status.

Show child properties
active_deployment object optional
Show child properties
cause string optional
Example: commit 9a4df0b pushed to github/digitalocean/sample-golang
cloned_from string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a
created_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
functions array of object optional
Show child properties
name string optional
Example: my-functions-component
namespace string optional
Example: ap-b2a93513-8d9b-4223-9d61-5e7272c81c32

The namespace where the functions are deployed.

source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405

The commit hash of the repository that was used to build this functions component.

id string optional
Example: b6bdf840-2854-4f87-a36c-5f231c617c84
jobs array of object optional
Show child properties
name string optional
Example: migrate-db
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
phase string (enum) optional
Example: ACTIVE
phase_last_updated_at string (date-time) optional
Example: 0001-01-01T00:00:00Z
progress object optional
Show child properties
error_steps integer (int32) optional
Example: 3
pending_steps integer (int32) optional
Example: 2
running_steps integer (int32) optional
Example: 2
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
success_steps integer (int32) optional
Example: 4
summary_steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
total_steps integer (int32) optional
Example: 5
services array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
spec object optional

The desired configuration of an application.

Show child properties
databases array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

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

domains array of object optional

A set of hostnames where the application will be available.

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

Specification for app egress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
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.

functions array of object optional

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

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

Specification for app ingress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

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

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

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Additional nested properties not shown. Refer to the full API spec for details.
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
workers array of object optional
Show child properties
name string optional
Example: queue-runner
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
created_at string (date-time) optional read-only
Example: 2020-11-19T20:27:18Z
dedicated_ips array of object optional read-only
Show child properties
id string optional
Example: 9e7bc2ac-205a-45d6-919c-e1ac5e73f962
ip string optional
Example: 192.168.1.1
status string, one of: UNKNOWN, ASSIGNING, ASSIGNED, REMOVED optional read-only
Example: ASSIGNED
default_ingress string optional read-only
Example: digitalocean.com
domains array of object optional read-only
Show child properties
certificate_expires_at string (date-time) optional read-only
Example: 2024-01-29T23:59:59Z
id string optional
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf
phase string, one of: UNKNOWN, PENDING, CONFIGURING, ACTIVE, ERROR optional
Example: ACTIVE
progress object optional
Show child properties
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
rotate_validation_records boolean optional read-only
spec object optional
Show child properties
domain string required
Example: app.example.com

The hostname for the domain

minimum_tls_version string, one of: 1.2, 1.3 optional
Example: 1.3

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

type string, one of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS optional
Example: DEFAULT
  • 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
wildcard boolean optional
Example: true

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

zone string (hostname) 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.

validations array of object optional
Show child properties
txt_name string optional read-only
Example: _acme-challenge.app.example.com
txt_value string optional read-only
Example: lXLOcN6cPv0nproViNcUHcahD9TrIPlNgdwesj0pYpk
id string optional read-only
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf
in_progress_deployment object optional
Show child properties
cause string optional
Example: commit 9a4df0b pushed to github/digitalocean/sample-golang
cloned_from string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a
created_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
functions array of object optional
Show child properties
name string optional
Example: my-functions-component
namespace string optional
Example: ap-b2a93513-8d9b-4223-9d61-5e7272c81c32

The namespace where the functions are deployed.

source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405

The commit hash of the repository that was used to build this functions component.

id string optional
Example: b6bdf840-2854-4f87-a36c-5f231c617c84
jobs array of object optional
Show child properties
name string optional
Example: migrate-db
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
phase string (enum) optional
Example: ACTIVE
phase_last_updated_at string (date-time) optional
Example: 0001-01-01T00:00:00Z
progress object optional
Show child properties
error_steps integer (int32) optional
Example: 3
pending_steps integer (int32) optional
Example: 2
running_steps integer (int32) optional
Example: 2
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
success_steps integer (int32) optional
Example: 4
summary_steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
total_steps integer (int32) optional
Example: 5
services array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
spec object optional

The desired configuration of an application.

Show child properties
databases array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

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

domains array of object optional

A set of hostnames where the application will be available.

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

Specification for app egress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
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.

functions array of object optional

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

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

Specification for app ingress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

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

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

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Additional nested properties not shown. Refer to the full API spec for details.
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
workers array of object optional
Show child properties
name string optional
Example: queue-runner
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
last_deployment_created_at string (date-time) optional read-only
Example: 2020-11-19T20:27:18Z
live_domain string optional read-only
Example: live_domain
live_url string optional read-only
Example: google.com
live_url_base string optional read-only
Example: digitalocean.com
owner_uuid string optional read-only
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf
pending_deployment object optional
pinned_deployment object optional
project_id string optional read-only
Example: 88b72d1a-b78a-4d9f-9090-b53c4399073f

Requires project:read scope.

region object optional
Show child properties
continent string optional read-only
Example: europe
data_centers array of string optional read-only
Example: ["ams"]
default boolean optional read-only
Example: true

Whether or not the region is presented as the default.

disabled boolean optional read-only
Example: true
flag string optional read-only
Example: ams
label string optional read-only
Example: ams
reason string optional read-only
Example: to crowded
slug string optional read-only
Example: basic
spec object required

The desired configuration of an application.

Show child properties
databases array of object 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 (enum) optional
Example: PG
  • MYSQL: MySQL
  • PG: PostgreSQL
  • REDIS: Caching
  • MONGODB: MongoDB
  • KAFKA: Kafka
  • OPENSEARCH: OpenSearch
  • VALKEY: ValKey
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.

production boolean optional
Example: true

Whether this is a production or dev database.

version string optional
Example: 12

The version of the database engine

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.

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

domains array of object 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

minimum_tls_version string, one of: 1.2, 1.3 optional
Example: 1.3

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

type string, one of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS optional
Example: DEFAULT
  • 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
wildcard boolean optional
Example: true

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

zone string (hostname) 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.

egress object optional

Specification for app egress configurations.

Show child properties
type string, one of: AUTOASSIGN, DEDICATED_IP optional
Example: AUTOASSIGN
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.

functions array of object optional

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

Show child properties
alerts array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
cors object optional
envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: api

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

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

ingress object optional

Specification for app ingress configurations.

Show child properties
rules array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

kind string, one of: UNSPECIFIED, PRE_DEPLOY, POST_DEPLOY, FAILED_DEPLOY optional
Example: PRE_DEPLOY
  • 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.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
maintenance object optional

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

Show child properties
archive boolean optional
Example: true

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

enabled boolean optional
Example: true

Indicates whether maintenance mode should be enabled for the app.

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.

name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

cors object optional
health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
http_port integer (int64) 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.

internal_ports array of integer (int64) optional
Example: [80,443]

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

Additional nested properties not shown. Refer to the full API spec for details.
liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
protocol string, one of: HTTP, HTTP2 optional
Example: HTTP

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).
routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

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.

cors object optional
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.

index_document string optional
Example: main.html

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

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.

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Show child properties
egress_ips array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
id string optional
Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional read-only
Example: 2020-12-01T00:42:16Z
vpc object optional read-only
Show child properties
egress_ips array of object optional
Show child properties
ip string optional
Example: 10.0.0.1
id string optional
Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "app": {
    "active_deployment": {
      "cause": "manual",
      "created_at": "2021-02-10T17:05:30Z",
      "id": "991dfa59-6a23-459f-86d6-67dfa2c6f1e3",
      "phase": "ACTIVE",
      "phase_last_updated_at": "2021-02-10T17:06:53Z",
      "progress": {
        "steps": [
          {
            "ended_at": "2021-02-10T17:06:19.807834070Z",
            "name": "build",
            "started_at": "2021-02-10T17:05:35.572287990Z",
            "status": "SUCCESS",
            "steps": [
              {
                "ended_at": "2021-02-10T17:05:36.093995229Z",
                "name": "initialize",
                "started_at": "2021-02-10T17:05:35.572347485Z",
                "status": "SUCCESS"
              },
              {
                "ended_at": "2021-02-10T17:06:19.461737040Z",
                "name": "components",
                "started_at": "2021-02-10T17:05:36.094015928Z",
                "status": "SUCCESS",
                "steps": [
                  {
                    "component_name": "web",
                    "message_base": "Building service",
                    "name": "web",
                    "status": "SUCCESS"
                  }
                ]
              }
            ]
          },
          {
            "ended_at": "2021-02-10T17:06:53.404104185Z",
            "name": "deploy",
            "started_at": "2021-02-10T17:06:25.143932418Z",
            "status": "SUCCESS",
            "steps": [
              {
                "ended_at": "2021-02-10T17:06:26.120343872Z",
                "name": "initialize",
                "started_at": "2021-02-10T17:06:25.143957508Z",
                "status": "SUCCESS"
              },
              {
                "ended_at": "2021-02-10T17:06:50.029695913Z",
                "name": "components",
                "started_at": "2021-02-10T17:06:26.120385561Z",
                "status": "SUCCESS",
                "steps": [
                  {
                    "component_name": "web",
                    "name": "web",
                    "status": "SUCCESS",
                    "steps": [
                      {
                        "component_name": "web",
                        "message_base": "Deploying service",
                        "name": "deploy",
                        "status": "SUCCESS"
                      },
                      {
                        "component_name": "web",
                        "message_base": "Waiting for service",
                        "name": "wait",
                        "status": "SUCCESS"
                      }
                    ]
                  }
                ]
              },
              {
                "ended_at": "2021-02-10T17:06:53.404065961Z",
                "name": "finalize",
                "started_at": "2021-02-10T17:06:50.348459495Z",
                "status": "SUCCESS"
              }
            ]
          }
        ],
        "success_steps": 6,
        "total_steps": 6
      },
      "services": [
        {
          "name": "web",
          "source_commit_hash": "db6936cb46047c576962962eed81ad52c21f35d7"
        }
      ],
      "spec": {
        "domains": [
          {
            "domain": "sample-golang.example.com",
            "minimum_tls_version": "1.3",
            "zone": "example.com"
          }
        ],
        "name": "sample-golang",
        "region": "ams",
        "services": [
          {
            "environment_slug": "go",
            "github": {
              "branch": "main",
              "repo": "ChiefMateStarbuck/sample-golang"
            },
            "http_port": 8080,
            "instance_count": 1,
            "instance_size_slug": "apps-s-1vcpu-0.5gb",
            "name": "web",
            "routes": [
              {
                "path": "/"
              }
            ],
            "run_command": "bin/sample-golang"
          }
        ],
        "vpc": {
          "egress_ips": [
            {
              "ip": "10.0.0.1"
            }
          ],
          "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac"
        }
      },
      "tier_slug": "basic",
      "updated_at": "2021-02-10T17:06:53Z"
    },
    "created_at": "2021-02-10T16:45:14Z",
    "dedicated_ips": [
      {
        "id": "c24d8f48-3bc4-49f5-8ca0-58e8164427ac",
        "ip": "192.168.1.1",
        "status": "ASSIGNED"
      },
      {
        "id": "4768fb15-2837-4dda-9be5-3951df4bc3d0",
        "ip": "192.168.1.2",
        "status": "ASSIGNED"
      }
    ],
    "default_ingress": "https://sample-golang-zyhgn.ondigitalocean.app",
    "domains": [
      {
        "certificate_expires_at": "2024-01-29T23:59:59Z",
        "id": "e206c64e-a1a3-11ed-9e6e-9b7b6dc9a52b",
        "phase": "CONFIGURING",
        "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"
            }
          ]
        },
        "rotate_validation_records": false,
        "spec": {
          "domain": "sample-golang.example.com",
          "minimum_tls_version": "1.3",
          "type": "PRIMARY",
          "zone": "example.com"
        }
      }
    ],
    "id": "c2a93513-8d9b-4223-9d61-5e7272c81cf5",
    "last_deployment_created_at": "2021-02-10T17:05:30Z",
    "live_domain": "sample-golang-zyhgn.ondigitalocean.app",
    "live_url": "https://sample-golang-zyhgn.ondigitalocean.app",
    "live_url_base": "https://sample-golang-zyhgn.ondigitalocean.app",
    "owner_uuid": "a4e16f25-cdd1-4483-b246-d77f283c9209",
    "pending_deployment": {
      "id": "3aa4d20e-5527-4c00-b496-601fbd22520a",
      "spec": {
        "domains": [
          {
            "domain": "sample-php.example.com",
            "minimum_tls_version": "1.3",
            "type": "PRIMARY",
            "zone": "example.com"
          }
        ],
        "name": "sample-php",
        "region": "fra",
        "services": [
          {
            "environment_slug": "php",
            "git": {
              "branch": "main",
              "repo_clone_url": "https://github.com/digitalocean/sample-php.git"
            },
            "http_port": 8080,
            "instance_count": 1,
            "instance_size_slug": "apps-s-1vcpu-0.5gb",
            "name": "sample-php",
            "routes": [
              {
                "path": "/"
              }
            ],
            "run_command": "heroku-php-apache2"
          }
        ],
        "vpc": {
          "egress_ips": [
            {
              "ip": "10.0.0.1"
            }
          ],
          "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac"
        }
      }
    },
    "project_id": "88b72d1a-b78a-4d9f-9090-b53c4399073f",
    "region": {
      "continent": "Europe",
      "data_centers": [
        "ams3"
      ],
      "flag": "netherlands",
      "label": "Amsterdam",
      "slug": "ams"
    },
    "spec": {
      "disable_edge_cache": true,
      "domains": [
        {
          "domain": "sample-golang.example.com",
          "minimum_tls_version": "1.3",
          "zone": "example.com"
        }
      ],
      "enhanced_threat_control_enabled": true,
      "name": "sample-golang",
      "region": "ams",
      "services": [
        {
          "environment_slug": "go",
          "github": {
            "branch": "main",
            "repo": "ChiefMateStarbuck/sample-golang"
          },
          "http_port": 8080,
          "instance_count": 1,
          "instance_size_slug": "apps-s-1vcpu-0.5gb",
          "name": "web",
          "routes": [
            {
              "path": "/"
            }
          ],
          "run_command": "bin/sample-golang"
        }
      ],
      "vpc": {
        "egress_ips": [
          {
            "ip": "10.0.0.1"
          }
        ],
        "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac"
      }
    },
    "tier_slug": "basic",
    "updated_at": "2021-02-10T17:06:56Z",
    "vpc": {
      "egress_ips": [
        {
          "ip": "10.0.0.1"
        }
      ],
      "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac"
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Retrieve Multiple Apps' Daily Bandwidth Metrics

/v2/apps/metrics/bandwidth_daily
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Retrieve daily bandwidth usage metrics for multiple apps.

Request Body: application/json

app_ids array of string required
Example: ["4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf","c2a93513-8d9b-4223-9d61-5e7272c81cf5"]

A list of app IDs to query bandwidth metrics for.

date string (date-time) optional
Example: 2023-01-17T00:00:00Z

Optional day to query. Only the date component of the timestamp will be considered. Default: yesterday.

Request: /v2/apps/metrics/bandwidth_daily
Content type application/json 
{
  "app_ids": [
    "4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf",
    "c2a93513-8d9b-4223-9d61-5e7272c81cf5"
  ],
  "date": "2023-01-17T00:00:00Z"
}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/metrics/bandwidth_daily" \
  -d '{ "app_ids": ["4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf"] }'
import os
from pydo import Client

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

req = {
    "app_ids": [
        "4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf",
        "c2a93513-8d9b-4223-9d61-5e7272c81cf5",
    ],
    "date": "2023-01-17T00:00:00Z",
}

get_resp = client.apps.list_metrics_bandwidth_daily(body=req)

Responses

200

A JSON object with a app_bandwidth_usage key
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
app_bandwidth_usage array of object optional

A list of bandwidth usage details by app.

Show child properties
app_id string optional
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The ID of the app.

bandwidth_bytes string (uint64) optional
Example: 513668

The used bandwidth amount in bytes.

date string (date-time) optional
Example: 2023-01-17T00:00:00Z

The date for the metrics data.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "app_bandwidth_usage": [
    {
      "app_id": "4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf",
      "bandwidth_bytes": "513668"
    },
    {
      "app_id": "c2a93513-8d9b-4223-9d61-5e7272c81cf5",
      "bandwidth_bytes": "254847"
    }
  ],
  "date": "2023-01-17T00:00:00Z"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Propose an App Spec

/v2/apps/propose
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

To propose and validate a spec for a new or existing app, send a POST request to the /v2/apps/propose endpoint. The request returns some information about the proposed app, including app cost and upgrade cost. If an existing app ID is specified, the app spec is treated as a proposed update to the existing app.

Request Body: application/json

app_id string optional
Example: b6bdf840-2854-4f87-a36c-5f231c617c84

An optional ID of an existing app. If set, the spec will be treated as a proposed update to the specified app. The existing app is not modified using this method.

spec object required

The desired configuration of an application.

Show child properties
databases array of object 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 (enum) optional
Example: PG
  • MYSQL: MySQL
  • PG: PostgreSQL
  • REDIS: Caching
  • MONGODB: MongoDB
  • KAFKA: Kafka
  • OPENSEARCH: OpenSearch
  • VALKEY: ValKey
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.

production boolean optional
Example: true

Whether this is a production or dev database.

version string optional
Example: 12

The version of the database engine

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.

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

domains array of object 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

minimum_tls_version string, one of: 1.2, 1.3 optional
Example: 1.3

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

type string, one of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS optional
Example: DEFAULT
  • 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
wildcard boolean optional
Example: true

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

zone string (hostname) 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.

egress object optional

Specification for app egress configurations.

Show child properties
type string, one of: AUTOASSIGN, DEDICATED_IP optional
Example: AUTOASSIGN
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.

functions array of object optional

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

Show child properties
alerts array of object optional
Show child properties
disabled boolean optional
Example: false

Is the alert disabled?

operator string, one of: UNSPECIFIED_OPERATOR, GREATER_THAN, LESS_THAN optional
Example: GREATER_THAN
rule string (enum) optional
Example: CPU_UTILIZATION
value number (float) optional
Example: 2.32

Threshold value for alert

window string, one of: UNSPECIFIED_WINDOW, FIVE_MINUTES, TEN_MINUTES, THIRTY_MINUTES, ONE_HOUR optional
Example: FIVE_MINUTES
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

cors object optional
envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: api

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

routes array of object 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.

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.

ingress object optional

Specification for app ingress configurations.

Show child properties
rules array of object optional

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

Show child properties
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.
cors object optional
Additional nested properties not shown. Refer to the full API spec for details.
match object optional

The match configuration for the rule.

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.
jobs array of object optional

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

Show child properties
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

build_command string optional
Example: npm run build

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

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.

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.

envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

image object optional
Show child properties
deploy_on_push object optional
Additional nested properties not shown. Refer to the full API spec for details.
digest string optional
Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

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

registry string optional
Example: registry.hub.docker.com

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

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.
registry_type string, one of: DOCKER_HUB, DOCR, GHCR optional
Example: DOCR
  • DOCKER_HUB: The DockerHub container registry type.
  • DOCR: The DigitalOcean container registry type.
  • GHCR: The Github container registry type.
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.

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Show child properties
max_instance_count integer (uint32) optional
Example: 3

The maximum amount of instances for this component. Must be more than min_instance_count.

metrics object optional

The metrics that the component is scaled on.

Additional nested properties not shown. Refer to the full API spec for details.
min_instance_count integer (uint32) optional
Example: 2

The minimum amount of instances for this component. Must be less than max_instance_count.

instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

kind string, one of: UNSPECIFIED, PRE_DEPLOY, POST_DEPLOY, FAILED_DEPLOY optional
Example: PRE_DEPLOY
  • 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.
termination object optional
Show child properties
grace_period_seconds integer (int32) 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)

maintenance object optional

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

Show child properties
archive boolean optional
Example: true

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

enabled boolean optional
Example: true

Indicates whether maintenance mode should be enabled for the app.

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.

name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Show child properties
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

build_command string optional
Example: npm run build

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

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.

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.

envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

image object optional
Show child properties
deploy_on_push object optional
Additional nested properties not shown. Refer to the full API spec for details.
digest string optional
Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

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

registry string optional
Example: registry.hub.docker.com

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

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.
registry_type string, one of: DOCKER_HUB, DOCR, GHCR optional
Example: DOCR
  • DOCKER_HUB: The DockerHub container registry type.
  • DOCR: The DigitalOcean container registry type.
  • GHCR: The Github container registry type.
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.

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Show child properties
max_instance_count integer (uint32) optional
Example: 3

The maximum amount of instances for this component. Must be more than min_instance_count.

metrics object optional

The metrics that the component is scaled on.

Additional nested properties not shown. Refer to the full API spec for details.
min_instance_count integer (uint32) optional
Example: 2

The minimum amount of instances for this component. Must be less than max_instance_count.

instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

cors object optional
health_check object optional
Show child properties
failure_threshold integer (int32) optional
Example: 2

The number of failed health checks before considered unhealthy.

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 (int32) optional
Example: 30

The number of seconds to wait before beginning health checks.

period_seconds integer (int32) optional
Example: 60

The number of seconds to wait between health checks.

port integer (int64) 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.

success_threshold integer (int32) optional
Example: 3

The number of successful health checks before considered healthy.

timeout_seconds integer (int32) optional
Example: 45

The number of seconds after which the check times out.

http_port integer (int64) 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.

internal_ports array of integer (int64) optional
Example: [80,443]

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

liveness_health_check object optional
Show child properties
failure_threshold integer (int32) optional
Example: 18

The number of failed health checks before considered unhealthy.

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 (int32) optional
Example: 30

The number of seconds to wait before beginning health checks.

period_seconds integer (int32) optional
Example: 10

The number of seconds to wait between health checks.

port integer (int64) optional
Example: 80

The port on which the health check will be performed.

success_threshold integer (int32) optional
Example: 1

The number of successful health checks before considered healthy.

timeout_seconds integer (int32) optional
Example: 1

The number of seconds after which the check times out.

protocol string, one of: HTTP, HTTP2 optional
Example: HTTP

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).
routes array of object 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 (int32) 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)

grace_period_seconds integer (int32) 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)

static_sites array of object optional

Content which can be rendered to static web assets.

Show child properties
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

build_command string optional
Example: npm run build

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

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.

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.

envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

image object optional
Show child properties
deploy_on_push object optional
Additional nested properties not shown. Refer to the full API spec for details.
digest string optional
Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

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

registry string optional
Example: registry.hub.docker.com

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

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.
registry_type string, one of: DOCKER_HUB, DOCR, GHCR optional
Example: DOCR
  • DOCKER_HUB: The DockerHub container registry type.
  • DOCR: The DigitalOcean container registry type.
  • GHCR: The Github container registry type.
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.

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

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.

cors object optional
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.

index_document string optional
Example: main.html

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

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.

routes array of object 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.

vpc object optional read-only
Show child properties
egress_ips array of object optional
Show child properties
ip string optional
Example: 10.0.0.1
id string optional
Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Show child properties
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

build_command string optional
Example: npm run build

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

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.

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.

envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

image object optional
Show child properties
deploy_on_push object optional
Additional nested properties not shown. Refer to the full API spec for details.
digest string optional
Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

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

registry string optional
Example: registry.hub.docker.com

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

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.
registry_type string, one of: DOCKER_HUB, DOCR, GHCR optional
Example: DOCR
  • DOCKER_HUB: The DockerHub container registry type.
  • DOCR: The DigitalOcean container registry type.
  • GHCR: The Github container registry type.
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.

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Show child properties
max_instance_count integer (uint32) optional
Example: 3

The maximum amount of instances for this component. Must be more than min_instance_count.

metrics object optional

The metrics that the component is scaled on.

Additional nested properties not shown. Refer to the full API spec for details.
min_instance_count integer (uint32) optional
Example: 2

The minimum amount of instances for this component. Must be less than max_instance_count.

instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

liveness_health_check object optional
Show child properties
failure_threshold integer (int32) optional
Example: 18

The number of failed health checks before considered unhealthy.

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 (int32) optional
Example: 30

The number of seconds to wait before beginning health checks.

period_seconds integer (int32) optional
Example: 10

The number of seconds to wait between health checks.

port integer (int64) optional
Example: 80

The port on which the health check will be performed.

success_threshold integer (int32) optional
Example: 1

The number of successful health checks before considered healthy.

timeout_seconds integer (int32) optional
Example: 1

The number of seconds after which the check times out.

termination object optional
Show child properties
grace_period_seconds integer (int32) 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)

Request: /v2/apps/propose
Content type application/json 
{
  "app_id": "b6bdf840-2854-4f87-a36c-5f231c617c84",
  "spec": {
    "name": "web-app",
    "region": "nyc",
    "services": [
      {
        "environment_slug": "node-js",
        "github": {
          "branch": "main",
          "deploy_on_push": true,
          "repo": "digitalocean/sample-golang"
        },
        "instance_count": 2,
        "instance_size_slug": "apps-s-1vcpu-0.5gb",
        "name": "api",
        "routes": [
          {
            "path": "/api"
          }
        ],
        "run_command": "bin/api"
      }
    ]
  }
}
curl -X POST \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "app_id": "b6bdf840-2854-4f87-a36c-5f231c617c84",
  "spec": {
    "name": "web-app",
    "region": "nyc",
    "services": [
      {
        "environment_slug": "node-js",
        "github": {
          "branch": "main",
          "deploy_on_push": true,
          "repo": "digitalocean/sample-golang"
        },
        "instance_count": 2,
        "instance_size_slug": "apps-s-1vcpu-0.5gb",
        "name": "api",
        "routes": [
          {
            "path": "/api"
          }
        ],
        "run_command": "bin/api"
      }
    ]
  }
}' \
  "https://api.digitalocean.com/v2/apps/propose"

Responses

200

A JSON object.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
app_cost integer (int32) optional
Example: 5

The monthly cost of the proposed app in USD.

app_is_static boolean optional
Example: true

Indicates whether the app is a static app.

app_name_available boolean optional
Example: true

Indicates whether the app name is available.

app_name_suggestion string optional
Example: newName

The suggested name if the proposed app name is unavailable.

app_tier_downgrade_cost integer (int32) optional Deprecated
Example: 17

The monthly cost of the proposed app in USD using the previous pricing plan tier. For example, if you propose an app that uses the Professional tier, the app_tier_downgrade_cost field displays the monthly cost of the app if it were to use the Basic tier. If the proposed app already uses the lest expensive tier, the field is empty.

existing_static_apps string optional
Example: 2

The maximum number of free static apps the account can have. We will charge you for any additional static apps.

spec object optional

The desired configuration of an application.

Show child properties
databases array of object 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 (enum) optional
Example: PG
  • MYSQL: MySQL
  • PG: PostgreSQL
  • REDIS: Caching
  • MONGODB: MongoDB
  • KAFKA: Kafka
  • OPENSEARCH: OpenSearch
  • VALKEY: ValKey
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.

production boolean optional
Example: true

Whether this is a production or dev database.

version string optional
Example: 12

The version of the database engine

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.

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

domains array of object 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

minimum_tls_version string, one of: 1.2, 1.3 optional
Example: 1.3

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

type string, one of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS optional
Example: DEFAULT
  • 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
wildcard boolean optional
Example: true

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

zone string (hostname) 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.

egress object optional

Specification for app egress configurations.

Show child properties
type string, one of: AUTOASSIGN, DEDICATED_IP optional
Example: AUTOASSIGN
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.

functions array of object optional

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

Show child properties
alerts array of object optional
Show child properties
disabled boolean optional
Example: false

Is the alert disabled?

operator string, one of: UNSPECIFIED_OPERATOR, GREATER_THAN, LESS_THAN optional
Example: GREATER_THAN
rule string (enum) optional
Example: CPU_UTILIZATION
value number (float) optional
Example: 2.32

Threshold value for alert

window string, one of: UNSPECIFIED_WINDOW, FIVE_MINUTES, TEN_MINUTES, THIRTY_MINUTES, ONE_HOUR optional
Example: FIVE_MINUTES
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

cors object optional
envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: api

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

routes array of object 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.

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.

ingress object optional

Specification for app ingress configurations.

Show child properties
rules array of object optional

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

Show child properties
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.
cors object optional
Additional nested properties not shown. Refer to the full API spec for details.
match object optional

The match configuration for the rule.

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.
jobs array of object optional

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

Show child properties
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

build_command string optional
Example: npm run build

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

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.

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.

envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

image object optional
Show child properties
deploy_on_push object optional
Additional nested properties not shown. Refer to the full API spec for details.
digest string optional
Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

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

registry string optional
Example: registry.hub.docker.com

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

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.
registry_type string, one of: DOCKER_HUB, DOCR, GHCR optional
Example: DOCR
  • DOCKER_HUB: The DockerHub container registry type.
  • DOCR: The DigitalOcean container registry type.
  • GHCR: The Github container registry type.
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.

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Show child properties
max_instance_count integer (uint32) optional
Example: 3

The maximum amount of instances for this component. Must be more than min_instance_count.

metrics object optional

The metrics that the component is scaled on.

Additional nested properties not shown. Refer to the full API spec for details.
min_instance_count integer (uint32) optional
Example: 2

The minimum amount of instances for this component. Must be less than max_instance_count.

instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

kind string, one of: UNSPECIFIED, PRE_DEPLOY, POST_DEPLOY, FAILED_DEPLOY optional
Example: PRE_DEPLOY
  • 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.
termination object optional
Show child properties
grace_period_seconds integer (int32) 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)

maintenance object optional

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

Show child properties
archive boolean optional
Example: true

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

enabled boolean optional
Example: true

Indicates whether maintenance mode should be enabled for the app.

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.

name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Show child properties
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

build_command string optional
Example: npm run build

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

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.

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.

envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

image object optional
Show child properties
deploy_on_push object optional
Additional nested properties not shown. Refer to the full API spec for details.
digest string optional
Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

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

registry string optional
Example: registry.hub.docker.com

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

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.
registry_type string, one of: DOCKER_HUB, DOCR, GHCR optional
Example: DOCR
  • DOCKER_HUB: The DockerHub container registry type.
  • DOCR: The DigitalOcean container registry type.
  • GHCR: The Github container registry type.
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.

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Show child properties
max_instance_count integer (uint32) optional
Example: 3

The maximum amount of instances for this component. Must be more than min_instance_count.

metrics object optional

The metrics that the component is scaled on.

Additional nested properties not shown. Refer to the full API spec for details.
min_instance_count integer (uint32) optional
Example: 2

The minimum amount of instances for this component. Must be less than max_instance_count.

instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

cors object optional
health_check object optional
Show child properties
failure_threshold integer (int32) optional
Example: 2

The number of failed health checks before considered unhealthy.

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 (int32) optional
Example: 30

The number of seconds to wait before beginning health checks.

period_seconds integer (int32) optional
Example: 60

The number of seconds to wait between health checks.

port integer (int64) 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.

success_threshold integer (int32) optional
Example: 3

The number of successful health checks before considered healthy.

timeout_seconds integer (int32) optional
Example: 45

The number of seconds after which the check times out.

http_port integer (int64) 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.

internal_ports array of integer (int64) optional
Example: [80,443]

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

liveness_health_check object optional
Show child properties
failure_threshold integer (int32) optional
Example: 18

The number of failed health checks before considered unhealthy.

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 (int32) optional
Example: 30

The number of seconds to wait before beginning health checks.

period_seconds integer (int32) optional
Example: 10

The number of seconds to wait between health checks.

port integer (int64) optional
Example: 80

The port on which the health check will be performed.

success_threshold integer (int32) optional
Example: 1

The number of successful health checks before considered healthy.

timeout_seconds integer (int32) optional
Example: 1

The number of seconds after which the check times out.

protocol string, one of: HTTP, HTTP2 optional
Example: HTTP

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).
routes array of object 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 (int32) 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)

grace_period_seconds integer (int32) 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)

static_sites array of object optional

Content which can be rendered to static web assets.

Show child properties
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

build_command string optional
Example: npm run build

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

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.

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.

envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

image object optional
Show child properties
deploy_on_push object optional
Additional nested properties not shown. Refer to the full API spec for details.
digest string optional
Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

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

registry string optional
Example: registry.hub.docker.com

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

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.
registry_type string, one of: DOCKER_HUB, DOCR, GHCR optional
Example: DOCR
  • DOCKER_HUB: The DockerHub container registry type.
  • DOCR: The DigitalOcean container registry type.
  • GHCR: The Github container registry type.
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.

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

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.

cors object optional
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.

index_document string optional
Example: main.html

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

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.

routes array of object 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.

vpc object optional read-only
Show child properties
egress_ips array of object optional
Show child properties
ip string optional
Example: 10.0.0.1
id string optional
Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Show child properties
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

build_command string optional
Example: npm run build

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

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.

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.

envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

image object optional
Show child properties
deploy_on_push object optional
Additional nested properties not shown. Refer to the full API spec for details.
digest string optional
Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

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

registry string optional
Example: registry.hub.docker.com

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

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.
registry_type string, one of: DOCKER_HUB, DOCR, GHCR optional
Example: DOCR
  • DOCKER_HUB: The DockerHub container registry type.
  • DOCR: The DigitalOcean container registry type.
  • GHCR: The Github container registry type.
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.

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Show child properties
max_instance_count integer (uint32) optional
Example: 3

The maximum amount of instances for this component. Must be more than min_instance_count.

metrics object optional

The metrics that the component is scaled on.

Additional nested properties not shown. Refer to the full API spec for details.
min_instance_count integer (uint32) optional
Example: 2

The minimum amount of instances for this component. Must be less than max_instance_count.

instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

liveness_health_check object optional
Show child properties
failure_threshold integer (int32) optional
Example: 18

The number of failed health checks before considered unhealthy.

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 (int32) optional
Example: 30

The number of seconds to wait before beginning health checks.

period_seconds integer (int32) optional
Example: 10

The number of seconds to wait between health checks.

port integer (int64) optional
Example: 80

The port on which the health check will be performed.

success_threshold integer (int32) optional
Example: 1

The number of successful health checks before considered healthy.

timeout_seconds integer (int32) optional
Example: 1

The number of seconds after which the check times out.

termination object optional
Show child properties
grace_period_seconds integer (int32) 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)

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "app_cost": 5,
  "app_name_available": true,
  "existing_static_apps": "2",
  "max_free_static_apps": "3",
  "spec": {
    "name": "sample-golang",
    "region": "ams",
    "services": [
      {
        "environment_slug": "go",
        "github": {
          "branch": "branch",
          "repo": "digitalocean/sample-golang"
        },
        "http_port": 8080,
        "instance_count": 1,
        "instance_size_slug": "apps-s-1vcpu-0.5gb",
        "name": "web",
        "routes": [
          {
            "path": "/"
          }
        ],
        "run_command": "bin/sample-golang"
      }
    ]
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List App Regions

/v2/apps/regions
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

List all regions supported by App Platform.

Request: /v2/apps/regions
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/regions"
import os
from pydo import Client

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

get_resp = client.apps.list_regions()

Responses

200

A JSON object with key regions
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
regions array of object optional
Show child properties
continent string optional read-only
Example: europe
data_centers array of string optional read-only
Example: ["ams"]
default boolean optional read-only
Example: true

Whether or not the region is presented as the default.

disabled boolean optional read-only
Example: true
flag string optional read-only
Example: ams
label string optional read-only
Example: ams
reason string optional read-only
Example: to crowded
slug string optional read-only
Example: basic
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "regions": [
    {
      "continent": "Europe",
      "data_centers": [
        "ams3"
      ],
      "flag": "netherlands",
      "label": "Amsterdam",
      "slug": "ams"
    },
    {
      "continent": "North America",
      "data_centers": [
        "nyc1",
        "nyc3"
      ],
      "default": true,
      "flag": "usa",
      "label": "New York",
      "slug": "nyc"
    },
    {
      "continent": "Europe",
      "data_centers": [
        "fra1"
      ],
      "flag": "germany",
      "label": "Frankfurt",
      "slug": "fra"
    },
    {
      "continent": "North America",
      "data_centers": [
        "sfo3"
      ],
      "flag": "usa",
      "label": "San Francisco",
      "slug": "sfo"
    },
    {
      "continent": "Asia",
      "data_centers": [
        "sgp1"
      ],
      "flag": "singapore",
      "label": "Singapore",
      "slug": "sgp"
    },
    {
      "continent": "Asia",
      "data_centers": [
        "blr1"
      ],
      "flag": "india",
      "label": "Bangalore",
      "slug": "blr"
    },
    {
      "continent": "North America",
      "data_centers": [
        "tor1"
      ],
      "flag": "canada",
      "label": "Toronto",
      "slug": "tor"
    },
    {
      "continent": "Europe",
      "data_centers": [
        "lon1"
      ],
      "flag": "uk",
      "label": "London",
      "slug": "lon"
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List Instance Sizes

/v2/apps/tiers/instance_sizes
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

List all instance sizes for service, worker, and job components.

Request: /v2/apps/tiers/instance_sizes
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/tiers/instance_sizes"
import os
from pydo import Client

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

get_resp = client.apps.list_instance_sizes()

Responses

200

A JSON with key instance_sizes
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
discount_percent number (float) optional
Example: 2.32
instance_sizes array of object optional
Show child properties
bandwidth_allowance_gib string (int64) optional
Example: 1
cpu_type string, one of: UNSPECIFIED, SHARED, DEDICATED optional
Example: SHARED
cpus string (int64) optional
Example: 3
deprecation_intent boolean optional
Example: true
memory_bytes string (int64) optional
Example: 1048
name string optional
Example: name
scalable boolean optional
Example: false
single_instance_only boolean optional
Example: true
slug string optional
Example: apps-s-1vcpu-1gb
tier_downgrade_to string optional Deprecated
Example: basic
tier_slug string optional
Example: basic
tier_upgrade_to string optional Deprecated
Example: basic
usd_per_month string optional
Example: 23
usd_per_second string optional
Example: 0.00000001232
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "instance_sizes": [
    {
      "bandwidth_allowance_gib": "50",
      "cpu_type": "SHARED",
      "cpus": "1",
      "memory_bytes": "536870912",
      "name": "Shared 1VCPU 0.5GB",
      "single_instance_only": true,
      "slug": "apps-s-1vcpu-0.5gb",
      "tier_slug": "basic",
      "usd_per_month": "5.00",
      "usd_per_second": "0.000002066799"
    },
    {
      "bandwidth_allowance_gib": "100",
      "cpu_type": "SHARED",
      "cpus": "1",
      "memory_bytes": "1073741824",
      "name": "Shared 1VCPU 1GB Fixed",
      "single_instance_only": true,
      "slug": "apps-s-1vcpu-1gb-fixed",
      "tier_slug": "basic",
      "usd_per_month": "10.00",
      "usd_per_second": "0.000004133598"
    },
    {
      "bandwidth_allowance_gib": "150",
      "cpu_type": "SHARED",
      "cpus": "1",
      "memory_bytes": "1073741824",
      "name": "Shared 1VCPU 1GB",
      "slug": "apps-s-1vcpu-1gb",
      "tier_slug": "professional",
      "usd_per_month": "12.00",
      "usd_per_second": "0.000004960317"
    },
    {
      "bandwidth_allowance_gib": "200",
      "cpu_type": "SHARED",
      "cpus": "1",
      "memory_bytes": "2147483648",
      "name": "Shared 1VCPU 2GB",
      "slug": "apps-s-1vcpu-2gb",
      "tier_slug": "professional",
      "usd_per_month": "25.00",
      "usd_per_second": "0.000010333995"
    },
    {
      "bandwidth_allowance_gib": "250",
      "cpu_type": "SHARED",
      "cpus": "2",
      "memory_bytes": "4294967296",
      "name": "Shared 2VCPU 4GB",
      "slug": "apps-s-2vcpu-4gb",
      "tier_slug": "professional",
      "usd_per_month": "50.00",
      "usd_per_second": "0.000020667989"
    },
    {
      "bandwidth_allowance_gib": "100",
      "cpu_type": "DEDICATED",
      "cpus": "1",
      "memory_bytes": "536870912",
      "name": "Dedicated 1VCPU 0.5GB",
      "scalable": true,
      "slug": "apps-d-1vcpu-0.5gb",
      "tier_slug": "professional",
      "usd_per_month": "29.00",
      "usd_per_second": "0.000011987434"
    },
    {
      "bandwidth_allowance_gib": "200",
      "cpu_type": "DEDICATED",
      "cpus": "1",
      "memory_bytes": "1073741824",
      "name": "Dedicated 1VCPU 1GB",
      "scalable": true,
      "slug": "apps-d-1vcpu-1gb",
      "tier_slug": "professional",
      "usd_per_month": "34.00",
      "usd_per_second": "0.000014054233"
    },
    {
      "bandwidth_allowance_gib": "300",
      "cpu_type": "DEDICATED",
      "cpus": "1",
      "memory_bytes": "2147483648",
      "name": "Dedicated 1VCPU 2GB",
      "scalable": true,
      "slug": "apps-d-1vcpu-2gb",
      "tier_slug": "professional",
      "usd_per_month": "39.00",
      "usd_per_second": "0.000016121032"
    },
    {
      "bandwidth_allowance_gib": "400",
      "cpu_type": "DEDICATED",
      "cpus": "1",
      "memory_bytes": "4294967296",
      "name": "Dedicated 1VCPU 4GB",
      "scalable": true,
      "slug": "apps-d-1vcpu-4gb",
      "tier_slug": "professional",
      "usd_per_month": "49.00",
      "usd_per_second": "0.000020254630"
    },
    {
      "bandwidth_allowance_gib": "500",
      "cpu_type": "DEDICATED",
      "cpus": "2",
      "memory_bytes": "4294967296",
      "name": "Dedicated 2VCPU 4GB",
      "scalable": true,
      "slug": "apps-d-2vcpu-4gb",
      "tier_slug": "professional",
      "usd_per_month": "78.00",
      "usd_per_second": "0.000032242063"
    },
    {
      "bandwidth_allowance_gib": "600",
      "cpu_type": "DEDICATED",
      "cpus": "2",
      "memory_bytes": "8589934592",
      "name": "Dedicated 2VCPU 8GB",
      "scalable": true,
      "slug": "apps-d-2vcpu-8gb",
      "tier_slug": "professional",
      "usd_per_month": "98.00",
      "usd_per_second": "0.000040509259"
    },
    {
      "bandwidth_allowance_gib": "700",
      "cpu_type": "DEDICATED",
      "cpus": "4",
      "memory_bytes": "8589934592",
      "name": "Dedicated 4VCPU 8GB",
      "scalable": true,
      "slug": "apps-d-4vcpu-8gb",
      "tier_slug": "professional",
      "usd_per_month": "156.00",
      "usd_per_second": "0.000064484127"
    },
    {
      "bandwidth_allowance_gib": "800",
      "cpu_type": "DEDICATED",
      "cpus": "4",
      "memory_bytes": "17179869184",
      "name": "Dedicated 4VCPU 16GB",
      "scalable": true,
      "slug": "apps-d-4vcpu-16gb",
      "tier_slug": "professional",
      "usd_per_month": "196.00",
      "usd_per_second": "0.000081018519"
    },
    {
      "bandwidth_allowance_gib": "900",
      "cpu_type": "DEDICATED",
      "cpus": "8",
      "memory_bytes": "34359738368",
      "name": "Dedicated 8VCPU 32GB",
      "scalable": true,
      "slug": "apps-d-8vcpu-32gb",
      "tier_slug": "professional",
      "usd_per_month": "392.00",
      "usd_per_second": "0.000162037037"
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve an Instance Size

/v2/apps/tiers/instance_sizes/{slug}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Retrieve information about a specific instance size for service, worker, and job components.

Path Parameters

slug string required
Example: apps-s-1vcpu-0.5gb

The slug of the instance size

Request: /v2/apps/tiers/instance_sizes/{slug}
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/tiers/instance_sizes/{slug}"
import os
from pydo import Client

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

get_resp = client.apps.get_instance_size(slug="apps-s-1vcpu-0.5gb")

Responses

200

A JSON with key instance_size
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
instance_size object optional
Show child properties
bandwidth_allowance_gib string (int64) optional
Example: 1
cpu_type string, one of: UNSPECIFIED, SHARED, DEDICATED optional
Example: SHARED
cpus string (int64) optional
Example: 3
deprecation_intent boolean optional
Example: true
memory_bytes string (int64) optional
Example: 1048
name string optional
Example: name
scalable boolean optional
Example: false
single_instance_only boolean optional
Example: true
slug string optional
Example: apps-s-1vcpu-1gb
tier_downgrade_to string optional Deprecated
Example: basic
tier_slug string optional
Example: basic
tier_upgrade_to string optional Deprecated
Example: basic
usd_per_month string optional
Example: 23
usd_per_second string optional
Example: 0.00000001232
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "instance_size": {
    "bandwidth_allowance_gib": "50",
    "cpu_type": "SHARED",
    "cpus": "1",
    "memory_bytes": "536870912",
    "name": "Shared 1VCPU 0.5GB",
    "single_instance_only": true,
    "slug": "apps-s-1vcpu-0.5gb",
    "tier_slug": "basic",
    "usd_per_month": "5.00",
    "usd_per_second": "0.000002066799"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List all app alerts

/v2/apps/{app_id}/alerts
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

List alerts associated to the app and any components. This includes configuration information about the alerts including emails, slack webhooks, and triggering events or conditions.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

Request: /v2/apps/{app_id}/alerts
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/alerts"
import os
from pydo import Client

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

get_resp = client.apps.list_alerts(app_id="4f6c71e2")

Responses

200

A JSON object with a alerts key. This is list of object alerts.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
alerts array of object optional
Show child properties
component_name string optional
Example: backend
emails array of string optional
Example: ["[email protected]"]
id string optional read-only
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf
phase string, one of: UNKNOWN, PENDING, CONFIGURING, ACTIVE, ERROR optional
Example: ACTIVE
progress object optional
Show child properties
steps array of object optional
Show child properties
ended_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
name string optional
Example: example_step
reason object optional
Additional nested properties not shown. Refer to the full API spec for details.
started_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
status string, one of: UNKNOWN, PENDING, RUNNING, ERROR, SUCCESS optional
Example: SUCCESS
slack_webhooks array of object optional
Show child properties
channel string optional
Example: Channel Name
url string optional
Example: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
spec object optional
Show child properties
disabled boolean optional
Example: false

Is the alert disabled?

operator string, one of: UNSPECIFIED_OPERATOR, GREATER_THAN, LESS_THAN optional
Example: GREATER_THAN
rule string (enum) optional
Example: CPU_UTILIZATION
value number (float) optional
Example: 2.32

Threshold value for alert

window string, one of: UNSPECIFIED_WINDOW, FIVE_MINUTES, TEN_MINUTES, THIRTY_MINUTES, ONE_HOUR optional
Example: FIVE_MINUTES
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "alerts": [
    {
      "emails": [
        "[email protected]"
      ],
      "id": "e552e1f9-c1b0-4e6d-8777-ad6f27767306",
      "phase": "ACTIVE",
      "progress": {
        "steps": [
          {
            "ended_at": "2020-07-28T18:00:00Z",
            "name": "alert-configure-insight-alert",
            "started_at": "2020-07-28T18:00:00Z",
            "status": "SUCCESS"
          }
        ]
      },
      "spec": {
        "rule": "DEPLOYMENT_FAILED"
      }
    },
    {
      "emails": [
        "[email protected]"
      ],
      "id": "b58cc9d4-0702-4ffd-ab45-4c2a8d979527",
      "phase": "ACTIVE",
      "progress": {
        "steps": [
          {
            "ended_at": "2020-07-28T18:00:00Z",
            "name": "alert-configure-insight-alert",
            "started_at": "2020-07-28T18:00:00Z",
            "status": "SUCCESS"
          }
        ]
      },
      "spec": {
        "operator": "GREATER_THAN",
        "rule": "CPU_UTILIZATION",
        "value": 85,
        "window": "FIVE_MINUTES"
      }
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Update destinations for alerts

/v2/apps/{app_id}/alerts/{alert_id}/destinations
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Updates the emails and slack webhook destinations for app alerts. Emails must be associated to a user with access to the app.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

alert_id string required
Example: 5a624ab5-dd58-4b39-b7dd-8b7c36e8a91d

The alert ID

Request Body: application/json

emails array of string optional
Example: ["[email protected]"]
slack_webhooks array of object optional
Show child properties
channel string optional
Example: Channel Name
url string optional
Example: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
Request: /v2/apps/{app_id}/alerts/{alert_id}/destinations
Content type application/json 
{
  "emails": [
    "[email protected]"
  ],
  "slack_webhooks": [
    {
      "channel": "Channel Name",
      "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
    }
  ]
}
curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{id}/alerts/{alert_id}/destinations"
import os
from pydo import Client

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

req = {
    "emails": ["[email protected]"],
    "slack_webhooks": [
        {
            "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
            "channel": "Channel Name",
        }
    ],
}

post_resp = client.apps.assign_alert_destinations("12345", "24556", req)

Responses

200

A JSON object with an alert key. This is an object of type alert.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
alert object optional
Show child properties
component_name string optional
Example: backend
emails array of string optional
Example: ["[email protected]"]
id string optional read-only
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf
phase string, one of: UNKNOWN, PENDING, CONFIGURING, ACTIVE, ERROR optional
Example: ACTIVE
progress object optional
Show child properties
steps array of object optional
Show child properties
ended_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
name string optional
Example: example_step
reason object optional
Additional nested properties not shown. Refer to the full API spec for details.
started_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
status string, one of: UNKNOWN, PENDING, RUNNING, ERROR, SUCCESS optional
Example: SUCCESS
slack_webhooks array of object optional
Show child properties
channel string optional
Example: Channel Name
url string optional
Example: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
spec object optional
Show child properties
disabled boolean optional
Example: false

Is the alert disabled?

operator string, one of: UNSPECIFIED_OPERATOR, GREATER_THAN, LESS_THAN optional
Example: GREATER_THAN
rule string (enum) optional
Example: CPU_UTILIZATION
value number (float) optional
Example: 2.32

Threshold value for alert

window string, one of: UNSPECIFIED_WINDOW, FIVE_MINUTES, TEN_MINUTES, THIRTY_MINUTES, ONE_HOUR optional
Example: FIVE_MINUTES
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "alert": {
    "emails": [
      "[email protected]"
    ],
    "id": "e552e1f9-c1b0-4e6d-8777-ad6f27767306",
    "phase": "ACTIVE",
    "progress": {
      "steps": [
        {
          "ended_at": "2020-07-28T18:00:00Z",
          "name": "alert-configure-insight-alert",
          "started_at": "2020-07-28T18:00:00Z",
          "status": "SUCCESS"
        }
      ]
    },
    "spec": {
      "rule": "DEPLOYMENT_FAILED"
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve Exec URL

/v2/apps/{app_id}/components/{component_name}/exec
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:access_console

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Returns a websocket URL that allows sending/receiving console input and output to a component of the active deployment if one exists.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

component_name string required
Example: component

An optional component name. If set, logs will be limited to this component only.

Query Parameters

instance_name string optional
Example: go-app-d768568df-zz77d

The name of the actively running ephemeral compute instance

Request: /v2/apps/{app_id}/components/{component_name}/exec
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/components/{component_name}/exec"
import os
from pydo import Client

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

get_resp = client.apps.get_exec_active_deployment(app_id="a6adf840", component_name="component")

Responses

200

A JSON object with a websocket URL that allows sending/receiving console input and output.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
url string optional
Example: wss://exec/?token=xxx

A websocket URL that allows sending/receiving console input and receiving console output.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "url": "wss://exec/?token=xxx"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve Active Deployment Logs

/v2/apps/{app_id}/components/{component_name}/logs
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Retrieve the logs of the active deployment if one exists. The response will include links to either real-time logs of an in-progress or active deployment or archived logs of a past deployment. Note log_type=BUILD logs will return logs associated with the current active deployment (being served). To view build logs associated with in-progress build, the query must explicitly reference the deployment id.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

component_name string required
Example: component

An optional component name. If set, logs will be limited to this component only.

Query Parameters

follow boolean optional
Example: true

Whether the logs should follow live updates.

type string (enum) required
Example: BUILD

The type of logs to retrieve

  • BUILD: Build-time logs
  • DEPLOY: Deploy-time logs
  • RUN: Live run-time logs
  • RUN_RESTARTED: Logs of crashed/restarted instances during runtime
  • AUTOSCALE_EVENT: Logs of an autoscaling event (requires event_id)
Default: UNSPECIFIED
pod_connection_timeout string optional
Example: 3m

An optional time duration to wait if the underlying component instance is not immediately available. Default: 3m.

Request: /v2/apps/{app_id}/components/{component_name}/logs
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/components/{component_name}/logs"
import os
from pydo import Client

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

get_resp = client.apps.get_logs_active_deployment(app_id="a6adf840", component_name="component")

Responses

200

A JSON object with urls that point to archived logs
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
historic_urls array of string optional
live_url string optional
Example: ws://logs/build

A URL of the real-time live logs. This URL may use either the https:// or wss:// protocols and will keep pushing live logs as they become available.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "historic_logs": [
    "https://logs-example/archive/build.log"
  ],
  "live_url": "https://logs-example/build.log",
  "url": "https://logs/build.log"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List App Deployments

/v2/apps/{app_id}/deployments
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

List all deployments of an app.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

Query Parameters

page integer >= 1 optional
Example: 1

Which 'page' of paginated results to return.

Default: 1
per_page integer 1 – 200 optional
Example: 2

Number of items returned per page

Default: 20
deployment_types array of string (enum) optional
Example: ["MANUAL","AUTOSCALED"]

Optional. Filter deployments by deployment_type

  • MANUAL: manual deployment
  • DEPLOY_ON_PUSH: deployment triggered by a push to the app's repository
  • MAINTENANCE: deployment for maintenance purposes
  • MANUAL_ROLLBACK: manual revert to a previous deployment
  • AUTO_ROLLBACK: automatic revert to a previous deployment
  • UPDATE_DATABASE_TRUSTED_SOURCES: update database trusted sources
  • AUTOSCALED: deployment that has been autoscaled
Request: /v2/apps/{app_id}/deployments
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/deployments"
import os
from pydo import Client

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

get_resp = client.apps.list_deployments(app_id="4f6c71e2")

Responses

200

A JSON object with a deployments key. This will be a list of all app deployments
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
deployments array of object optional
Show child properties
cause string optional
Example: commit 9a4df0b pushed to github/digitalocean/sample-golang
cloned_from string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a
created_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
functions array of object optional
Show child properties
name string optional
Example: my-functions-component
namespace string optional
Example: ap-b2a93513-8d9b-4223-9d61-5e7272c81c32

The namespace where the functions are deployed.

source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405

The commit hash of the repository that was used to build this functions component.

id string optional
Example: b6bdf840-2854-4f87-a36c-5f231c617c84
jobs array of object optional
Show child properties
name string optional
Example: migrate-db
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
phase string (enum) optional
Example: ACTIVE
phase_last_updated_at string (date-time) optional
Example: 0001-01-01T00:00:00Z
progress object optional
Show child properties
error_steps integer (int32) optional
Example: 3
pending_steps integer (int32) optional
Example: 2
running_steps integer (int32) optional
Example: 2
steps array of object optional
Show child properties
component_name string optional
Example: component
ended_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
message_base string optional
Example: Building service

The base of a human-readable description of the step intended to be combined with the component name for presentation. For example:

message_base = "Building service" component_name = "api"

name string optional
Example: example_step
reason object optional
Additional nested properties not shown. Refer to the full API spec for details.
started_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
status string, one of: UNKNOWN, PENDING, RUNNING, ERROR, SUCCESS optional
Example: SUCCESS
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
success_steps integer (int32) optional
Example: 4
summary_steps array of object optional
Show child properties
component_name string optional
Example: component
ended_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
message_base string optional
Example: Building service

The base of a human-readable description of the step intended to be combined with the component name for presentation. For example:

message_base = "Building service" component_name = "api"

name string optional
Example: example_step
reason object optional
Additional nested properties not shown. Refer to the full API spec for details.
started_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
status string, one of: UNKNOWN, PENDING, RUNNING, ERROR, SUCCESS optional
Example: SUCCESS
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
total_steps integer (int32) optional
Example: 5
services array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
spec object optional

The desired configuration of an application.

Show child properties
databases array of object 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 (enum) optional
Example: PG
  • MYSQL: MySQL
  • PG: PostgreSQL
  • REDIS: Caching
  • MONGODB: MongoDB
  • KAFKA: Kafka
  • OPENSEARCH: OpenSearch
  • VALKEY: ValKey
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.

production boolean optional
Example: true

Whether this is a production or dev database.

version string optional
Example: 12

The version of the database engine

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.

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

domains array of object 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

minimum_tls_version string, one of: 1.2, 1.3 optional
Example: 1.3

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

type string, one of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS optional
Example: DEFAULT
  • 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
wildcard boolean optional
Example: true

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

zone string (hostname) 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.

egress object optional

Specification for app egress configurations.

Show child properties
type string, one of: AUTOASSIGN, DEDICATED_IP optional
Example: AUTOASSIGN
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.

functions array of object optional

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

Show child properties
alerts array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
cors object optional
envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: api

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

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

ingress object optional

Specification for app ingress configurations.

Show child properties
rules array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

kind string, one of: UNSPECIFIED, PRE_DEPLOY, POST_DEPLOY, FAILED_DEPLOY optional
Example: PRE_DEPLOY
  • 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.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
maintenance object optional

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

Show child properties
archive boolean optional
Example: true

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

enabled boolean optional
Example: true

Indicates whether maintenance mode should be enabled for the app.

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.

name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

cors object optional
health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
http_port integer (int64) 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.

internal_ports array of integer (int64) optional
Example: [80,443]

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

Additional nested properties not shown. Refer to the full API spec for details.
liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
protocol string, one of: HTTP, HTTP2 optional
Example: HTTP

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).
routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

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.

cors object optional
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.

index_document string optional
Example: main.html

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

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.

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Show child properties
egress_ips array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
id string optional
Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
workers array of object optional
Show child properties
name string optional
Example: queue-runner
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
links object optional
Show child properties
pages anyOf optional
One of:
Forward Links
last string optional
Example: https://api.digitalocean.com/v2/images?page=2

URI of the last page of the results.

next string optional
Example: https://api.digitalocean.com/v2/images?page=2

URI of the next page of the results.

Backward Links
first string optional
Example: https://api.digitalocean.com/v2/images?page=1

URI of the first page of the results.

prev string optional
Example: https://api.digitalocean.com/v2/images?page=1

URI of the previous page of the results.

meta object required
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "deployments": [
    {
      "cause": "commit 9a4df0b pushed to github/digitalocean/sample-golang",
      "created_at": "2020-07-28T18:00:00Z",
      "id": "b6bdf840-2854-4f87-a36c-5f231c617c84",
      "phase": "PENDING_BUILD",
      "phase_last_updated_at": "0001-01-01T00:00:00Z",
      "progress": {
        "pending_steps": 6,
        "steps": [
          {
            "name": "build",
            "status": "PENDING",
            "steps": [
              {
                "name": "initialize",
                "status": "PENDING"
              },
              {
                "name": "components",
                "status": "PENDING",
                "steps": [
                  {
                    "component_name": "web",
                    "message_base": "Building service",
                    "name": "web",
                    "status": "PENDING"
                  }
                ]
              }
            ]
          },
          {
            "name": "deploy",
            "status": "PENDING",
            "steps": [
              {
                "name": "initialize",
                "status": "PENDING"
              },
              {
                "name": "components",
                "status": "PENDING",
                "steps": [
                  {
                    "component_name": "web",
                    "name": "web",
                    "status": "PENDING",
                    "steps": [
                      {
                        "component_name": "web",
                        "message_base": "Deploying service",
                        "name": "deploy",
                        "status": "PENDING"
                      },
                      {
                        "component_name": "web",
                        "message_base": "Waiting for service",
                        "name": "wait",
                        "status": "PENDING"
                      }
                    ]
                  }
                ]
              },
              {
                "name": "finalize",
                "status": "PENDING"
              }
            ]
          }
        ],
        "total_steps": 6
      },
      "services": [
        {
          "name": "web",
          "source_commit_hash": "9a4df0b8e161e323bc3cdf1dc71878080fe144fa"
        }
      ],
      "spec": {
        "disable_edge_cache": true,
        "disable_email_obfuscation": true,
        "enhanced_threat_control_enabled": true,
        "name": "sample-golang",
        "region": "ams",
        "services": [
          {
            "environment_slug": "go",
            "github": {
              "branch": "branch",
              "repo": "digitalocean/sample-golang"
            },
            "instance_count": 2,
            "instance_size_slug": "apps-s-1vcpu-0.5gb",
            "name": "web",
            "routes": [
              {
                "path": "/"
              }
            ],
            "run_command": "bin/sample-golang"
          }
        ]
      },
      "tier_slug": "basic",
      "updated_at": "2020-07-28T18:00:00Z"
    }
  ],
  "links": {
    "pages": {}
  },
  "meta": {
    "total": 1
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Create an App Deployment

/v2/apps/{app_id}/deployments
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Creating an app deployment will pull the latest changes from your repository and schedule a new deployment for your app.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

Request Body: application/json

force_build boolean optional
Example: true
Request: /v2/apps/{app_id}/deployments
Content type application/json 
{
  "force_build": true
}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/deployments"
import os
from pydo import Client

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

create_resp = client.apps.create_deployment(app_id="b6bdf840", body={"force_build": True})

Responses

200

A JSON object with a deployment key.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
deployment object optional
Show child properties
cause string optional
Example: commit 9a4df0b pushed to github/digitalocean/sample-golang
cloned_from string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a
created_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
functions array of object optional
Show child properties
name string optional
Example: my-functions-component
namespace string optional
Example: ap-b2a93513-8d9b-4223-9d61-5e7272c81c32

The namespace where the functions are deployed.

source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405

The commit hash of the repository that was used to build this functions component.

id string optional
Example: b6bdf840-2854-4f87-a36c-5f231c617c84
jobs array of object optional
Show child properties
name string optional
Example: migrate-db
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
phase string (enum) optional
Example: ACTIVE
phase_last_updated_at string (date-time) optional
Example: 0001-01-01T00:00:00Z
progress object optional
Show child properties
error_steps integer (int32) optional
Example: 3
pending_steps integer (int32) optional
Example: 2
running_steps integer (int32) optional
Example: 2
steps array of object optional
Show child properties
component_name string optional
Example: component
ended_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
message_base string optional
Example: Building service

The base of a human-readable description of the step intended to be combined with the component name for presentation. For example:

message_base = "Building service" component_name = "api"

name string optional
Example: example_step
reason object optional
Additional nested properties not shown. Refer to the full API spec for details.
started_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
status string, one of: UNKNOWN, PENDING, RUNNING, ERROR, SUCCESS optional
Example: SUCCESS
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
success_steps integer (int32) optional
Example: 4
summary_steps array of object optional
Show child properties
component_name string optional
Example: component
ended_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
message_base string optional
Example: Building service

The base of a human-readable description of the step intended to be combined with the component name for presentation. For example:

message_base = "Building service" component_name = "api"

name string optional
Example: example_step
reason object optional
Additional nested properties not shown. Refer to the full API spec for details.
started_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
status string, one of: UNKNOWN, PENDING, RUNNING, ERROR, SUCCESS optional
Example: SUCCESS
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
total_steps integer (int32) optional
Example: 5
services array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
spec object optional

The desired configuration of an application.

Show child properties
databases array of object 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 (enum) optional
Example: PG
  • MYSQL: MySQL
  • PG: PostgreSQL
  • REDIS: Caching
  • MONGODB: MongoDB
  • KAFKA: Kafka
  • OPENSEARCH: OpenSearch
  • VALKEY: ValKey
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.

production boolean optional
Example: true

Whether this is a production or dev database.

version string optional
Example: 12

The version of the database engine

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.

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

domains array of object 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

minimum_tls_version string, one of: 1.2, 1.3 optional
Example: 1.3

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

type string, one of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS optional
Example: DEFAULT
  • 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
wildcard boolean optional
Example: true

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

zone string (hostname) 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.

egress object optional

Specification for app egress configurations.

Show child properties
type string, one of: AUTOASSIGN, DEDICATED_IP optional
Example: AUTOASSIGN
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.

functions array of object optional

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

Show child properties
alerts array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
cors object optional
envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: api

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

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

ingress object optional

Specification for app ingress configurations.

Show child properties
rules array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

kind string, one of: UNSPECIFIED, PRE_DEPLOY, POST_DEPLOY, FAILED_DEPLOY optional
Example: PRE_DEPLOY
  • 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.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
maintenance object optional

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

Show child properties
archive boolean optional
Example: true

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

enabled boolean optional
Example: true

Indicates whether maintenance mode should be enabled for the app.

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.

name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

cors object optional
health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
http_port integer (int64) 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.

internal_ports array of integer (int64) optional
Example: [80,443]

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

Additional nested properties not shown. Refer to the full API spec for details.
liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
protocol string, one of: HTTP, HTTP2 optional
Example: HTTP

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).
routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

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.

cors object optional
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.

index_document string optional
Example: main.html

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

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.

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Show child properties
egress_ips array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
id string optional
Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
workers array of object optional
Show child properties
name string optional
Example: queue-runner
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "deployment": {
    "cause": "commit 9a4df0b pushed to github/digitalocean/sample-golang",
    "created_at": "2020-07-28T18:00:00Z",
    "id": "b6bdf840-2854-4f87-a36c-5f231c617c84",
    "phase": "PENDING_BUILD",
    "phase_last_updated_at": "0001-01-01T00:00:00Z",
    "progress": {
      "pending_steps": 6,
      "steps": [
        {
          "name": "build",
          "status": "PENDING",
          "steps": [
            {
              "name": "initialize",
              "status": "PENDING"
            },
            {
              "name": "components",
              "status": "PENDING",
              "steps": [
                {
                  "component_name": "web",
                  "message_base": "Building service",
                  "name": "web",
                  "status": "PENDING"
                }
              ]
            }
          ]
        },
        {
          "name": "deploy",
          "status": "PENDING",
          "steps": [
            {
              "name": "initialize",
              "status": "PENDING"
            },
            {
              "name": "components",
              "status": "PENDING",
              "steps": [
                {
                  "component_name": "web",
                  "name": "web",
                  "status": "PENDING",
                  "steps": [
                    {
                      "component_name": "web",
                      "message_base": "Deploying service",
                      "name": "deploy",
                      "status": "PENDING"
                    },
                    {
                      "component_name": "web",
                      "message_base": "Waiting for service",
                      "name": "wait",
                      "status": "PENDING"
                    }
                  ]
                }
              ]
            },
            {
              "name": "finalize",
              "status": "PENDING"
            }
          ]
        }
      ],
      "total_steps": 6
    },
    "services": [
      {
        "name": "web",
        "source_commit_hash": "9a4df0b8e161e323bc3cdf1dc71878080fe144fa"
      }
    ],
    "spec": {
      "disable_edge_cache": true,
      "disable_email_obfuscation": true,
      "enhanced_threat_control_enabled": true,
      "name": "sample-golang",
      "region": "ams",
      "services": [
        {
          "environment_slug": "go",
          "github": {
            "branch": "branch",
            "repo": "digitalocean/sample-golang"
          },
          "instance_count": 2,
          "instance_size_slug": "apps-s-1vcpu-0.5gb",
          "name": "web",
          "routes": [
            {
              "path": "/"
            }
          ],
          "run_command": "bin/sample-golang"
        }
      ]
    },
    "tier_slug": "basic",
    "updated_at": "2020-07-28T18:00:00Z"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve an App Deployment

/v2/apps/{app_id}/deployments/{deployment_id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Retrieve information about an app deployment.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

deployment_id string required
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a

The deployment ID

Request: /v2/apps/{app_id}/deployments/{deployment_id}
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/deployments/{deployment_id}"
import os
from pydo import Client

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

get_resp = client.apps.get_deployment(app_id="a6adf840", deployment_id="b6bdf840")

Responses

200

A JSON of the requested deployment
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
deployment object optional
Show child properties
cause string optional
Example: commit 9a4df0b pushed to github/digitalocean/sample-golang
cloned_from string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a
created_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
functions array of object optional
Show child properties
name string optional
Example: my-functions-component
namespace string optional
Example: ap-b2a93513-8d9b-4223-9d61-5e7272c81c32

The namespace where the functions are deployed.

source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405

The commit hash of the repository that was used to build this functions component.

id string optional
Example: b6bdf840-2854-4f87-a36c-5f231c617c84
jobs array of object optional
Show child properties
name string optional
Example: migrate-db
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
phase string (enum) optional
Example: ACTIVE
phase_last_updated_at string (date-time) optional
Example: 0001-01-01T00:00:00Z
progress object optional
Show child properties
error_steps integer (int32) optional
Example: 3
pending_steps integer (int32) optional
Example: 2
running_steps integer (int32) optional
Example: 2
steps array of object optional
Show child properties
component_name string optional
Example: component
ended_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
message_base string optional
Example: Building service

The base of a human-readable description of the step intended to be combined with the component name for presentation. For example:

message_base = "Building service" component_name = "api"

name string optional
Example: example_step
reason object optional
Additional nested properties not shown. Refer to the full API spec for details.
started_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
status string, one of: UNKNOWN, PENDING, RUNNING, ERROR, SUCCESS optional
Example: SUCCESS
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
success_steps integer (int32) optional
Example: 4
summary_steps array of object optional
Show child properties
component_name string optional
Example: component
ended_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
message_base string optional
Example: Building service

The base of a human-readable description of the step intended to be combined with the component name for presentation. For example:

message_base = "Building service" component_name = "api"

name string optional
Example: example_step
reason object optional
Additional nested properties not shown. Refer to the full API spec for details.
started_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
status string, one of: UNKNOWN, PENDING, RUNNING, ERROR, SUCCESS optional
Example: SUCCESS
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
total_steps integer (int32) optional
Example: 5
services array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
spec object optional

The desired configuration of an application.

Show child properties
databases array of object 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 (enum) optional
Example: PG
  • MYSQL: MySQL
  • PG: PostgreSQL
  • REDIS: Caching
  • MONGODB: MongoDB
  • KAFKA: Kafka
  • OPENSEARCH: OpenSearch
  • VALKEY: ValKey
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.

production boolean optional
Example: true

Whether this is a production or dev database.

version string optional
Example: 12

The version of the database engine

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.

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

domains array of object 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

minimum_tls_version string, one of: 1.2, 1.3 optional
Example: 1.3

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

type string, one of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS optional
Example: DEFAULT
  • 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
wildcard boolean optional
Example: true

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

zone string (hostname) 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.

egress object optional

Specification for app egress configurations.

Show child properties
type string, one of: AUTOASSIGN, DEDICATED_IP optional
Example: AUTOASSIGN
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.

functions array of object optional

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

Show child properties
alerts array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
cors object optional
envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: api

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

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

ingress object optional

Specification for app ingress configurations.

Show child properties
rules array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

kind string, one of: UNSPECIFIED, PRE_DEPLOY, POST_DEPLOY, FAILED_DEPLOY optional
Example: PRE_DEPLOY
  • 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.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
maintenance object optional

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

Show child properties
archive boolean optional
Example: true

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

enabled boolean optional
Example: true

Indicates whether maintenance mode should be enabled for the app.

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.

name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

cors object optional
health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
http_port integer (int64) 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.

internal_ports array of integer (int64) optional
Example: [80,443]

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

Additional nested properties not shown. Refer to the full API spec for details.
liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
protocol string, one of: HTTP, HTTP2 optional
Example: HTTP

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).
routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

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.

cors object optional
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.

index_document string optional
Example: main.html

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

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.

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Show child properties
egress_ips array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
id string optional
Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
workers array of object optional
Show child properties
name string optional
Example: queue-runner
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "deployment": {
    "cause": "commit 9a4df0b pushed to github/digitalocean/sample-golang",
    "created_at": "2020-07-28T18:00:00Z",
    "id": "b6bdf840-2854-4f87-a36c-5f231c617c84",
    "phase": "PENDING_BUILD",
    "phase_last_updated_at": "0001-01-01T00:00:00Z",
    "progress": {
      "pending_steps": 6,
      "steps": [
        {
          "name": "build",
          "status": "PENDING",
          "steps": [
            {
              "name": "initialize",
              "status": "PENDING"
            },
            {
              "name": "components",
              "status": "PENDING",
              "steps": [
                {
                  "component_name": "web",
                  "message_base": "Building service",
                  "name": "web",
                  "status": "PENDING"
                }
              ]
            }
          ]
        },
        {
          "name": "deploy",
          "status": "PENDING",
          "steps": [
            {
              "name": "initialize",
              "status": "PENDING"
            },
            {
              "name": "components",
              "status": "PENDING",
              "steps": [
                {
                  "component_name": "web",
                  "name": "web",
                  "status": "PENDING",
                  "steps": [
                    {
                      "component_name": "web",
                      "message_base": "Deploying service",
                      "name": "deploy",
                      "status": "PENDING"
                    },
                    {
                      "component_name": "web",
                      "message_base": "Waiting for service",
                      "name": "wait",
                      "status": "PENDING"
                    }
                  ]
                }
              ]
            },
            {
              "name": "finalize",
              "status": "PENDING"
            }
          ]
        }
      ],
      "total_steps": 6
    },
    "services": [
      {
        "name": "web",
        "source_commit_hash": "9a4df0b8e161e323bc3cdf1dc71878080fe144fa"
      }
    ],
    "spec": {
      "disable_edge_cache": true,
      "disable_email_obfuscation": true,
      "enhanced_threat_control_enabled": true,
      "name": "sample-golang",
      "region": "ams",
      "services": [
        {
          "environment_slug": "go",
          "github": {
            "branch": "branch",
            "repo": "digitalocean/sample-golang"
          },
          "instance_count": 2,
          "instance_size_slug": "apps-s-1vcpu-0.5gb",
          "name": "web",
          "routes": [
            {
              "path": "/"
            }
          ],
          "run_command": "bin/sample-golang"
        }
      ]
    },
    "tier_slug": "basic",
    "updated_at": "2020-07-28T18:00:00Z"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Cancel a Deployment

/v2/apps/{app_id}/deployments/{deployment_id}/cancel
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Immediately cancel an in-progress deployment.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

deployment_id string required
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a

The deployment ID

Request: /v2/apps/{app_id}/deployments/{deployment_id}/cancel
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/deployments/{deployment_id}/cancel"
import os
from pydo import Client

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

cancel_resp = client.apps.cancel_deployment("12345", "24556")

Responses

200

A JSON the deployment that was just cancelled.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
deployment object optional
Show child properties
cause string optional
Example: commit 9a4df0b pushed to github/digitalocean/sample-golang
cloned_from string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a
created_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
functions array of object optional
Show child properties
name string optional
Example: my-functions-component
namespace string optional
Example: ap-b2a93513-8d9b-4223-9d61-5e7272c81c32

The namespace where the functions are deployed.

source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405

The commit hash of the repository that was used to build this functions component.

id string optional
Example: b6bdf840-2854-4f87-a36c-5f231c617c84
jobs array of object optional
Show child properties
name string optional
Example: migrate-db
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
phase string (enum) optional
Example: ACTIVE
phase_last_updated_at string (date-time) optional
Example: 0001-01-01T00:00:00Z
progress object optional
Show child properties
error_steps integer (int32) optional
Example: 3
pending_steps integer (int32) optional
Example: 2
running_steps integer (int32) optional
Example: 2
steps array of object optional
Show child properties
component_name string optional
Example: component
ended_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
message_base string optional
Example: Building service

The base of a human-readable description of the step intended to be combined with the component name for presentation. For example:

message_base = "Building service" component_name = "api"

name string optional
Example: example_step
reason object optional
Additional nested properties not shown. Refer to the full API spec for details.
started_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
status string, one of: UNKNOWN, PENDING, RUNNING, ERROR, SUCCESS optional
Example: SUCCESS
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
success_steps integer (int32) optional
Example: 4
summary_steps array of object optional
Show child properties
component_name string optional
Example: component
ended_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
message_base string optional
Example: Building service

The base of a human-readable description of the step intended to be combined with the component name for presentation. For example:

message_base = "Building service" component_name = "api"

name string optional
Example: example_step
reason object optional
Additional nested properties not shown. Refer to the full API spec for details.
started_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
status string, one of: UNKNOWN, PENDING, RUNNING, ERROR, SUCCESS optional
Example: SUCCESS
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
total_steps integer (int32) optional
Example: 5
services array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
spec object optional

The desired configuration of an application.

Show child properties
databases array of object 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 (enum) optional
Example: PG
  • MYSQL: MySQL
  • PG: PostgreSQL
  • REDIS: Caching
  • MONGODB: MongoDB
  • KAFKA: Kafka
  • OPENSEARCH: OpenSearch
  • VALKEY: ValKey
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.

production boolean optional
Example: true

Whether this is a production or dev database.

version string optional
Example: 12

The version of the database engine

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.

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

domains array of object 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

minimum_tls_version string, one of: 1.2, 1.3 optional
Example: 1.3

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

type string, one of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS optional
Example: DEFAULT
  • 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
wildcard boolean optional
Example: true

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

zone string (hostname) 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.

egress object optional

Specification for app egress configurations.

Show child properties
type string, one of: AUTOASSIGN, DEDICATED_IP optional
Example: AUTOASSIGN
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.

functions array of object optional

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

Show child properties
alerts array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
cors object optional
envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: api

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

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

ingress object optional

Specification for app ingress configurations.

Show child properties
rules array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

kind string, one of: UNSPECIFIED, PRE_DEPLOY, POST_DEPLOY, FAILED_DEPLOY optional
Example: PRE_DEPLOY
  • 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.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
maintenance object optional

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

Show child properties
archive boolean optional
Example: true

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

enabled boolean optional
Example: true

Indicates whether maintenance mode should be enabled for the app.

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.

name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

cors object optional
health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
http_port integer (int64) 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.

internal_ports array of integer (int64) optional
Example: [80,443]

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

Additional nested properties not shown. Refer to the full API spec for details.
liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
protocol string, one of: HTTP, HTTP2 optional
Example: HTTP

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).
routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

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.

cors object optional
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.

index_document string optional
Example: main.html

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

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.

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Show child properties
egress_ips array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
id string optional
Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
workers array of object optional
Show child properties
name string optional
Example: queue-runner
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "deployment": {
    "cause": "commit 9a4df0b pushed to github/digitalocean/sample-golang",
    "created_at": "2020-07-28T18:00:00Z",
    "id": "b6bdf840-2854-4f87-a36c-5f231c617c84",
    "phase": "PENDING_BUILD",
    "phase_last_updated_at": "0001-01-01T00:00:00Z",
    "progress": {
      "pending_steps": 6,
      "steps": [
        {
          "name": "build",
          "status": "PENDING",
          "steps": [
            {
              "name": "initialize",
              "status": "PENDING"
            },
            {
              "name": "components",
              "status": "PENDING",
              "steps": [
                {
                  "component_name": "web",
                  "message_base": "Building service",
                  "name": "web",
                  "status": "PENDING"
                }
              ]
            }
          ]
        },
        {
          "name": "deploy",
          "status": "PENDING",
          "steps": [
            {
              "name": "initialize",
              "status": "PENDING"
            },
            {
              "name": "components",
              "status": "PENDING",
              "steps": [
                {
                  "component_name": "web",
                  "name": "web",
                  "status": "PENDING",
                  "steps": [
                    {
                      "component_name": "web",
                      "message_base": "Deploying service",
                      "name": "deploy",
                      "status": "PENDING"
                    },
                    {
                      "component_name": "web",
                      "message_base": "Waiting for service",
                      "name": "wait",
                      "status": "PENDING"
                    }
                  ]
                }
              ]
            },
            {
              "name": "finalize",
              "status": "PENDING"
            }
          ]
        }
      ],
      "total_steps": 6
    },
    "services": [
      {
        "name": "web",
        "source_commit_hash": "9a4df0b8e161e323bc3cdf1dc71878080fe144fa"
      }
    ],
    "spec": {
      "disable_edge_cache": true,
      "disable_email_obfuscation": true,
      "enhanced_threat_control_enabled": true,
      "name": "sample-golang",
      "region": "ams",
      "services": [
        {
          "environment_slug": "go",
          "github": {
            "branch": "branch",
            "repo": "digitalocean/sample-golang"
          },
          "instance_count": 2,
          "instance_size_slug": "apps-s-1vcpu-0.5gb",
          "name": "web",
          "routes": [
            {
              "path": "/"
            }
          ],
          "run_command": "bin/sample-golang"
        }
      ]
    },
    "tier_slug": "basic",
    "updated_at": "2020-07-28T18:00:00Z"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve Exec URL for Deployment

/v2/apps/{app_id}/deployments/{deployment_id}/components/{component_name}/exec
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:access_console

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Returns a websocket URL that allows sending/receiving console input and output to a component of the specified deployment if one exists. Optionally, the instance_name parameter can be provided to retrieve the exec URL for a specific instance. Note that instances are ephemeral; therefore, we recommended to avoid making persistent changes or such scripting around them.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

deployment_id string required
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a

The deployment ID

component_name string required
Example: component

An optional component name. If set, logs will be limited to this component only.

Query Parameters

instance_name string optional
Example: go-app-d768568df-zz77d

The name of the actively running ephemeral compute instance

Request: /v2/apps/{app_id}/deployments/{deployment_id}/components/{component_name}/exec
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/deployments/{deployment_id}/components/{component_name}/exec"
import os
from pydo import Client

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

get_resp = client.apps.get_exec(app_id="4f6c71e2", deployment_id="3aa4d20e", component_name="component")

Responses

200

A JSON object with a websocket URL that allows sending/receiving console input and output.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
url string optional
Example: wss://exec/?token=xxx

A websocket URL that allows sending/receiving console input and receiving console output.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "url": "wss://exec/?token=xxx"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve Deployment Logs

/v2/apps/{app_id}/deployments/{deployment_id}/components/{component_name}/logs
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Retrieve the logs of a past, in-progress, or active deployment. The response will include links to either real-time logs of an in-progress or active deployment or archived logs of a past deployment.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

deployment_id string required
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a

The deployment ID

component_name string required
Example: component

An optional component name. If set, logs will be limited to this component only.

Query Parameters

follow boolean optional
Example: true

Whether the logs should follow live updates.

type string (enum) required
Example: BUILD

The type of logs to retrieve

  • BUILD: Build-time logs
  • DEPLOY: Deploy-time logs
  • RUN: Live run-time logs
  • RUN_RESTARTED: Logs of crashed/restarted instances during runtime
  • AUTOSCALE_EVENT: Logs of an autoscaling event (requires event_id)
Default: UNSPECIFIED
pod_connection_timeout string optional
Example: 3m

An optional time duration to wait if the underlying component instance is not immediately available. Default: 3m.

Request: /v2/apps/{app_id}/deployments/{deployment_id}/components/{component_name}/logs
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/deployments/{deployment_id}/components/{component_name}/logs"
import os
from pydo import Client

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

get_resp = client.apps.get_logs(app_id="4f6c71e2", deployment_id="3aa4d20e", component_name="component")

Responses

200

A JSON object with urls that point to archived logs
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
historic_urls array of string optional
live_url string optional
Example: ws://logs/build

A URL of the real-time live logs. This URL may use either the https:// or wss:// protocols and will keep pushing live logs as they become available.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "historic_logs": [
    "https://logs-example/archive/build.log"
  ],
  "live_url": "https://logs-example/build.log",
  "url": "https://logs/build.log"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve Aggregate Deployment Logs

/v2/apps/{app_id}/deployments/{deployment_id}/logs
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Retrieve the logs of a past, in-progress, or active deployment. If a component name is specified, the logs will be limited to only that component. The response will include links to either real-time logs of an in-progress or active deployment or archived logs of a past deployment.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

deployment_id string required
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a

The deployment ID

Query Parameters

follow boolean optional
Example: true

Whether the logs should follow live updates.

type string (enum) required
Example: BUILD

The type of logs to retrieve

  • BUILD: Build-time logs
  • DEPLOY: Deploy-time logs
  • RUN: Live run-time logs
  • RUN_RESTARTED: Logs of crashed/restarted instances during runtime
  • AUTOSCALE_EVENT: Logs of an autoscaling event (requires event_id)
Default: UNSPECIFIED
pod_connection_timeout string optional
Example: 3m

An optional time duration to wait if the underlying component instance is not immediately available. Default: 3m.

Request: /v2/apps/{app_id}/deployments/{deployment_id}/logs
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/deployments/{deployment_id}/logs"
import os
from pydo import Client

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

get_resp = client.apps.get_logs_aggregate(app_id="b6bdf840", deployment_id="a6adf840")

Responses

200

A JSON object with urls that point to archived logs
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
historic_urls array of string optional
live_url string optional
Example: ws://logs/build

A URL of the real-time live logs. This URL may use either the https:// or wss:// protocols and will keep pushing live logs as they become available.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "historic_logs": [
    "https://logs-example/archive/build.log"
  ],
  "live_url": "https://logs-example/build.log",
  "url": "https://logs/build.log"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List App Events

/v2/apps/{app_id}/events
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

List all events for an app, including deployments and autoscaling events.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

Query Parameters

page integer >= 1 optional
Example: 1

Which 'page' of paginated results to return.

Default: 1
per_page integer 1 – 200 optional
Example: 2

Number of items returned per page

Default: 20
event_types array of string, one of: UNKNOWN, DEPLOYMENT, AUTOSCALING optional
Example: ["DEPLOYMENT"]

Filter events by event type.

Request: /v2/apps/{app_id}/events
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/events"
import os
from pydo import Client

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

get_resp = client.apps.list_events(app_id="4f6c71e2")

Responses

200

A JSON with key events
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
events array of object optional
Show child properties
autoscaling object optional

Autoscaling event details. Only present for autoscaling events.

Show child properties
components object optional

Map of component names to their scale changes

Show child properties
(additional properties) object optional

Additional properties are allowed.

phase string (enum) optional
Example: SUCCEEDED

The current phase of the autoscaling event

created_at string (date-time) optional
Example: 2023-10-01T12:00:00Z
deployment object optional
Show child properties
cause string optional
Example: commit 9a4df0b pushed to github/digitalocean/sample-golang
cloned_from string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a
created_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
functions array of object optional
Show child properties
name string optional
Example: my-functions-component
namespace string optional
Example: ap-b2a93513-8d9b-4223-9d61-5e7272c81c32

The namespace where the functions are deployed.

source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405

The commit hash of the repository that was used to build this functions component.

id string optional
Example: b6bdf840-2854-4f87-a36c-5f231c617c84
jobs array of object optional
Show child properties
name string optional
Example: migrate-db
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
phase string (enum) optional
Example: ACTIVE
phase_last_updated_at string (date-time) optional
Example: 0001-01-01T00:00:00Z
progress object optional
Show child properties
error_steps integer (int32) optional
Example: 3
pending_steps integer (int32) optional
Example: 2
running_steps integer (int32) optional
Example: 2
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
success_steps integer (int32) optional
Example: 4
summary_steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
total_steps integer (int32) optional
Example: 5
services array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
spec object optional

The desired configuration of an application.

Show child properties
databases array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

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

domains array of object optional

A set of hostnames where the application will be available.

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

Specification for app egress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
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.

functions array of object optional

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

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

Specification for app ingress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

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

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

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Additional nested properties not shown. Refer to the full API spec for details.
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
workers array of object optional
Show child properties
name string optional
Example: queue-runner
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
deployment_id string optional
Example: c020763f-ddb7-4112-a0df-7f01c69fc00b

For deployment events, this is the same as the deployment's ID. For autoscaling events, this is the deployment that was autoscaled.

id string optional
Example: ba32b134-569c-4c0c-ba02-8ffdb0492ece
type string, one of: UNKNOWN, DEPLOYMENT, AUTOSCALING optional
Example: DEPLOYMENT

The type of event

links object optional
Show child properties
pages anyOf optional
One of:
Forward Links
last string optional
Example: https://api.digitalocean.com/v2/images?page=2

URI of the last page of the results.

next string optional
Example: https://api.digitalocean.com/v2/images?page=2

URI of the next page of the results.

Backward Links
first string optional
Example: https://api.digitalocean.com/v2/images?page=1

URI of the first page of the results.

prev string optional
Example: https://api.digitalocean.com/v2/images?page=1

URI of the previous page of the results.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "events": [
    {
      "created_at": "2023-10-01T12:00:00Z",
      "deployment_id": "c020763f-ddb7-4112-a0df-7f01c69fc00b",
      "id": "ba32b134-569c-4c0c-ba02-8ffdb0492ece",
      "type": "DEPLOYMENT"
    }
  ],
  "links": {
    "pages": {
      "pages": {
        "first": "https://api.digitalocean.com/v2/account/keys?page=1",
        "prev": "https://api.digitalocean.com/v2/account/keys?page=2"
      }
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Get an Event

/v2/apps/{app_id}/events/{event_id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Get a single event for an app.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

event_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The event ID

Request: /v2/apps/{app_id}/events/{event_id}
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/events/{event_id}"
import os
from pydo import Client

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

get_resp = client.apps.get_event(app_id="4f6c71e2", event_id="3aa4d20e")

Responses

200

A JSON with key event
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
event object optional
Show child properties
autoscaling object optional

Autoscaling event details. Only present for autoscaling events.

Show child properties
components object optional

Map of component names to their scale changes

Show child properties
(additional properties) object optional

Additional properties are allowed.

phase string (enum) optional
Example: SUCCEEDED

The current phase of the autoscaling event

created_at string (date-time) optional
Example: 2023-10-01T12:00:00Z
deployment object optional
Show child properties
cause string optional
Example: commit 9a4df0b pushed to github/digitalocean/sample-golang
cloned_from string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a
created_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
functions array of object optional
Show child properties
name string optional
Example: my-functions-component
namespace string optional
Example: ap-b2a93513-8d9b-4223-9d61-5e7272c81c32

The namespace where the functions are deployed.

source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405

The commit hash of the repository that was used to build this functions component.

id string optional
Example: b6bdf840-2854-4f87-a36c-5f231c617c84
jobs array of object optional
Show child properties
name string optional
Example: migrate-db
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
phase string (enum) optional
Example: ACTIVE
phase_last_updated_at string (date-time) optional
Example: 0001-01-01T00:00:00Z
progress object optional
Show child properties
error_steps integer (int32) optional
Example: 3
pending_steps integer (int32) optional
Example: 2
running_steps integer (int32) optional
Example: 2
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
success_steps integer (int32) optional
Example: 4
summary_steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
total_steps integer (int32) optional
Example: 5
services array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
spec object optional

The desired configuration of an application.

Show child properties
databases array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

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

domains array of object optional

A set of hostnames where the application will be available.

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

Specification for app egress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
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.

functions array of object optional

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

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

Specification for app ingress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

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

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

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Additional nested properties not shown. Refer to the full API spec for details.
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
workers array of object optional
Show child properties
name string optional
Example: queue-runner
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
deployment_id string optional
Example: c020763f-ddb7-4112-a0df-7f01c69fc00b

For deployment events, this is the same as the deployment's ID. For autoscaling events, this is the deployment that was autoscaled.

id string optional
Example: ba32b134-569c-4c0c-ba02-8ffdb0492ece
type string, one of: UNKNOWN, DEPLOYMENT, AUTOSCALING optional
Example: DEPLOYMENT

The type of event

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "event": {
    "autoscaling": {
      "phase": "SUCCEEDED"
    },
    "created_at": "2023-10-01T12:00:00Z",
    "deployment": {
      "cause": "commit 9a4df0b pushed to github/digitalocean/sample-golang",
      "cloned_from": "3aa4d20e-5527-4c00-b496-601fbd22520a",
      "created_at": "2020-07-28T18:00:00Z",
      "functions": [],
      "id": "b6bdf840-2854-4f87-a36c-5f231c617c84",
      "jobs": [],
      "phase": "ACTIVE",
      "phase_last_updated_at": "0001-01-01T00:00:00Z",
      "services": [],
      "static_sites": [],
      "tier_slug": "basic",
      "updated_at": "2020-07-28T18:00:00Z",
      "workers": []
    },
    "deployment_id": "c020763f-ddb7-4112-a0df-7f01c69fc00b",
    "id": "ba32b134-569c-4c0c-ba02-8ffdb0492ece",
    "type": "DEPLOYMENT"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Cancel an Event

/v2/apps/{app_id}/events/{event_id}/cancel
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Cancel an in-progress autoscaling event.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

event_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The event ID

Request: /v2/apps/{app_id}/events/{event_id}/cancel
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/events/{event_id}/cancel"
import os
from pydo import Client

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

get_resp = client.apps.cancel_event(app_id="4f6c71e2", event_id="3aa4d20e")

Responses

200

A JSON with key event
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
event object optional
Show child properties
autoscaling object optional

Autoscaling event details. Only present for autoscaling events.

Show child properties
components object optional

Map of component names to their scale changes

Show child properties
(additional properties) object optional

Additional properties are allowed.

phase string (enum) optional
Example: SUCCEEDED

The current phase of the autoscaling event

created_at string (date-time) optional
Example: 2023-10-01T12:00:00Z
deployment object optional
Show child properties
cause string optional
Example: commit 9a4df0b pushed to github/digitalocean/sample-golang
cloned_from string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a
created_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
functions array of object optional
Show child properties
name string optional
Example: my-functions-component
namespace string optional
Example: ap-b2a93513-8d9b-4223-9d61-5e7272c81c32

The namespace where the functions are deployed.

source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405

The commit hash of the repository that was used to build this functions component.

id string optional
Example: b6bdf840-2854-4f87-a36c-5f231c617c84
jobs array of object optional
Show child properties
name string optional
Example: migrate-db
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
phase string (enum) optional
Example: ACTIVE
phase_last_updated_at string (date-time) optional
Example: 0001-01-01T00:00:00Z
progress object optional
Show child properties
error_steps integer (int32) optional
Example: 3
pending_steps integer (int32) optional
Example: 2
running_steps integer (int32) optional
Example: 2
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
success_steps integer (int32) optional
Example: 4
summary_steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
total_steps integer (int32) optional
Example: 5
services array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
spec object optional

The desired configuration of an application.

Show child properties
databases array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

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

domains array of object optional

A set of hostnames where the application will be available.

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

Specification for app egress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
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.

functions array of object optional

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

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

Specification for app ingress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

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

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

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Additional nested properties not shown. Refer to the full API spec for details.
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
workers array of object optional
Show child properties
name string optional
Example: queue-runner
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
deployment_id string optional
Example: c020763f-ddb7-4112-a0df-7f01c69fc00b

For deployment events, this is the same as the deployment's ID. For autoscaling events, this is the deployment that was autoscaled.

id string optional
Example: ba32b134-569c-4c0c-ba02-8ffdb0492ece
type string, one of: UNKNOWN, DEPLOYMENT, AUTOSCALING optional
Example: DEPLOYMENT

The type of event

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "event": {
    "autoscaling": {
      "phase": "SUCCEEDED"
    },
    "created_at": "2023-10-01T12:00:00Z",
    "deployment": {
      "cause": "commit 9a4df0b pushed to github/digitalocean/sample-golang",
      "cloned_from": "3aa4d20e-5527-4c00-b496-601fbd22520a",
      "created_at": "2020-07-28T18:00:00Z",
      "functions": [],
      "id": "b6bdf840-2854-4f87-a36c-5f231c617c84",
      "jobs": [],
      "phase": "ACTIVE",
      "phase_last_updated_at": "0001-01-01T00:00:00Z",
      "services": [],
      "static_sites": [],
      "tier_slug": "basic",
      "updated_at": "2020-07-28T18:00:00Z",
      "workers": []
    },
    "deployment_id": "c020763f-ddb7-4112-a0df-7f01c69fc00b",
    "id": "ba32b134-569c-4c0c-ba02-8ffdb0492ece",
    "type": "DEPLOYMENT"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve Event Logs

/v2/apps/{app_id}/events/{event_id}/logs
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Retrieve the logs of an autoscaling event for an app.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

event_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The event ID

Query Parameters

follow boolean optional
Example: true

Whether the logs should follow live updates.

type string (enum) required
Example: BUILD

The type of logs to retrieve

  • BUILD: Build-time logs
  • DEPLOY: Deploy-time logs
  • RUN: Live run-time logs
  • RUN_RESTARTED: Logs of crashed/restarted instances during runtime
  • AUTOSCALE_EVENT: Logs of an autoscaling event (requires event_id)
Default: UNSPECIFIED
pod_connection_timeout string optional
Example: 3m

An optional time duration to wait if the underlying component instance is not immediately available. Default: 3m.

Request: /v2/apps/{app_id}/events/{event_id}/logs
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/events/{event_id}/logs?type=AUTOSCALE_EVENT"
import os
from pydo import Client

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

get_resp = client.apps.get_event_logs(app_id="4f6c71e2", event_id="3aa4d20e")

Responses

200

A JSON object with urls that point to archived logs
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
historic_urls array of string optional
live_url string optional
Example: ws://logs/build

A URL of the real-time live logs. This URL may use either the https:// or wss:// protocols and will keep pushing live logs as they become available.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "historic_logs": [
    "https://logs-example/archive/build.log"
  ],
  "live_url": "https://logs-example/build.log",
  "url": "https://logs/build.log"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve App Health

/v2/apps/{app_id}/health
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Retrieve information like health status, cpu and memory utilization of app components.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

Request: /v2/apps/{app_id}/health
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{id}/health"

Responses

200

A JSON with key app_health
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
app_health object optional
Show child properties
components array of object optional
Show child properties
cpu_usage_percent number (double) optional
Example: 30
memory_usage_percent number (double) optional
Example: 25
name string optional
Example: sample_app
replicas_desired integer (int64) optional
Example: 1
replicas_ready integer (int64) optional
Example: 1
state string, one of: UNKNOWN, HEALTHY, UNHEALTHY optional
Example: HEALTHY
functions_components array of object optional
Show child properties
functions_component_health_metrics array of object optional
Show child properties
metric_label string optional
Example: activations_count
metric_value number (double) optional
Example: 100
time_window string optional
Example: 1h
name string optional
Example: sample_function
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "components": [
    {
      "cpu_usage_percent": 5.555,
      "memory_usage_percent": 20.32,
      "name": "sample-expressjs",
      "replicas_desired": 1,
      "replicas_ready": 2,
      "state": "HEALTHY"
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve App Instances

/v2/apps/{app_id}/instances
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Retrieve the list of running instances for a given application, including instance names and component types. Please note that these instances are ephemeral and may change over time. It is recommended not to make persistent changes or develop scripts that rely on their persistence.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

Request: /v2/apps/{app_id}/instances
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{id}/instances"

Responses

200

A JSON with key instances
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
instances array of object optional
Show child properties
component_name string optional
Example: sample-golang

Name of the component, from the app spec.

component_type string, one of: SERVICE, WORKER, JOB optional
Example: SERVICE

Supported compute component by DigitalOcean App Platform.

instance_alias string optional
Example: sample-golang-0

Readable identifier, an alias of the instance name, reference for mapping insights to instance names.

instance_name string optional
Example: sample-golang-76b84c7fb8-6p8kq

Name of the instance, which is a unique identifier for the instance.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "instances": [
    {
      "component_name": "sample-golang",
      "component_type": "SERVICE",
      "instance_alias": "sample-golang-0",
      "instance_name": "sample-golang-76b84c7fb8-6p8kq"
    },
    {
      "component_name": "sample-golang",
      "component_type": "SERVICE",
      "instance_alias": "sample-golang-1",
      "instance_name": "sample-golang-76b84c7fb8-ngvpc"
    },
    {
      "component_name": "sample-php",
      "component_type": "SERVICE",
      "instance_alias": "sample-php-0",
      "instance_name": "sample-php-767c6b49c4-dkgpt"
    },
    {
      "component_name": "sample-php",
      "component_type": "SERVICE",
      "instance_alias": "sample-php-1",
      "instance_name": "sample-php-767c6b49c4-z8dll"
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List Job Invocations

/v2/apps/{app_id}/job-invocations
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

List all job invocations for an app.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

Query Parameters

job_names array of string optional
Example: ["component1","component2"]

The job names to list job invocations for.

deployment_id string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a

The deployment ID

page integer >= 1 optional
Example: 1

Which 'page' of paginated results to return.

Default: 1
per_page integer 1 – 200 optional
Example: 2

Number of items returned per page

Default: 20
Request: /v2/apps/{app_id}/job-invocations
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/job-invocations"
import os
from pydo import Client

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

get_resp = client.apps.list_job_invocations(app_id="4f6c71e2")

Responses

200

A JSON with key job_invocations
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
job_invocations array of object optional
Show child properties
completed_at string (date-time) optional
Example: 2023-10-01T12:10:00Z
created_at string (date-time) optional
Example: 2023-10-01T12:00:00Z
deployment_id string optional
Example: c020763f-ddb7-4112-a0df-7f01c69fc00b
id string optional
Example: ba32b134-569c-4c0c-ba02-8ffdb0492ece
job_name string optional
Example: good-job
phase string (enum) optional
Example: SUCCEEDED

The phase of the job invocation

started_at string (date-time) optional
Example: 2023-10-01T12:05:00Z
trigger object optional
Show child properties
manual object optional

Details about the manual trigger, if applicable

Show child properties
user object optional

The user who triggered the job

Additional nested properties not shown. Refer to the full API spec for details.
scheduled object optional
Example: {"schedule":{"cron":"0 0 * * *","time_zone":"America/New_York"}}

The schedule for the job

Show child properties
schedule object optional
Additional nested properties not shown. Refer to the full API spec for details.
type string, one of: MANUAL, SCHEDULE, UNKNOWN optional
Example: MANUAL

The type of trigger that initiated the job invocation.

links object optional
Show child properties
pages anyOf optional
One of:
Forward Links
last string optional
Example: https://api.digitalocean.com/v2/images?page=2

URI of the last page of the results.

next string optional
Example: https://api.digitalocean.com/v2/images?page=2

URI of the next page of the results.

Backward Links
first string optional
Example: https://api.digitalocean.com/v2/images?page=1

URI of the first page of the results.

prev string optional
Example: https://api.digitalocean.com/v2/images?page=1

URI of the previous page of the results.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "job_invocations": [
    {
      "completed_at": "2025-09-11T11:04:40Z",
      "created_at": "2025-09-11T11:04:05Z",
      "deployment_id": "c020763f-ddb7-4112-a0df-7f01c69fc00b",
      "id": "ba32b134-569c-4c0c-ba02-8ffdb0492ece",
      "job_name": "good-job",
      "phase": "SUCCEEDED",
      "started_at": "2025-09-11T11:04:10Z",
      "trigger": {
        "properties": {
          "scheduled": {
            "properties": {
              "schedule": {
                "properties": {
                  "cron": {
                    "example": "*/2 * * * *",
                    "type": "string"
                  },
                  "time_zone": {
                    "example": "UTC",
                    "type": "string"
                  }
                },
                "type": "object"
              }
            },
            "type": "object"
          },
          "type": {
            "type": "string"
          }
        },
        "type": "SCHEDULE"
      }
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Get Job Invocations

/v2/apps/{app_id}/job-invocations/{job_invocation_id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Get a specific job invocation for an app.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

job_invocation_id string required
Example: 123e4567-e89b-12d3-a456-426

The ID of the job invocation to retrieve.

Query Parameters

job_name string optional
Example: component

The job name to list job invocations for.

Request: /v2/apps/{app_id}/job-invocations/{job_invocation_id}
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/job-invocations/{job_invocation_id}"
import os
from pydo import Client

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

get_resp = client.apps.get_job_invocation(app_id="4f6c71e2", job_invocation_id="3aa4d20e")

Responses

200

A JSON with key job_invocation
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
completed_at string (date-time) optional
Example: 2023-10-01T12:10:00Z
created_at string (date-time) optional
Example: 2023-10-01T12:00:00Z
deployment_id string optional
Example: c020763f-ddb7-4112-a0df-7f01c69fc00b
id string optional
Example: ba32b134-569c-4c0c-ba02-8ffdb0492ece
job_name string optional
Example: good-job
phase string (enum) optional
Example: SUCCEEDED

The phase of the job invocation

started_at string (date-time) optional
Example: 2023-10-01T12:05:00Z
trigger object optional
Show child properties
manual object optional

Details about the manual trigger, if applicable

Show child properties
user object optional

The user who triggered the job

Show child properties
email string (email) optional
Example: [email protected]
full_name string optional
Example: John Doe
uuid string optional
Example: 550e8400-e29b-41d4-a716-446655440000
scheduled object optional
Example: {"schedule":{"cron":"0 0 * * *","time_zone":"America/New_York"}}

The schedule for the job

Show child properties
schedule object optional
Show child properties
cron string optional
Example: 0 0 * * *

The cron expression defining the schedule

time_zone string optional
Example: America/New_York

The time zone for the schedule

type string, one of: MANUAL, SCHEDULE, UNKNOWN optional
Example: MANUAL

The type of trigger that initiated the job invocation.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "job_invocation": [
    {
      "completed_at": "2025-09-11T11:04:40Z",
      "created_at": "2025-09-11T11:04:05Z",
      "deployment_id": "c020763f-ddb7-4112-a0df-7f01c69fc00b",
      "id": "ba32b134-569c-4c0c-ba02-8ffdb0492ece",
      "job_name": "good-job",
      "phase": "SUCCEEDED",
      "started_at": "2025-09-11T11:04:10Z",
      "trigger": [
        {
          "scheduled": [
            {
              "schedule": {
                "cron": "*/2 * * * *",
                "time_zone": "UTC"
              }
            }
          ],
          "type": "SCHEDULED"
        }
      ]
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Cancel Job Invocation

/v2/apps/{app_id}/job-invocations/{job_invocation_id}/cancel
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Cancel a specific job invocation for an app.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

job_invocation_id string required
Example: 123e4567-e89b-12d3-a456-426

The ID of the job invocation to retrieve.

Query Parameters

job_name string optional
Example: component

The job name to list job invocations for.

Request: /v2/apps/{app_id}/job-invocations/{job_invocation_id}/cancel
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/job-invocations/{job_invocation_id}/cancel"
import os
from pydo import Client

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

get_resp = client.apps.cancel_job_invocation(app_id="4f6c71e2", job_invocation_id="3aa4d20e")

Responses

200

A JSON with key job_invocation
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
completed_at string (date-time) optional
Example: 2023-10-01T12:10:00Z
created_at string (date-time) optional
Example: 2023-10-01T12:00:00Z
deployment_id string optional
Example: c020763f-ddb7-4112-a0df-7f01c69fc00b
id string optional
Example: ba32b134-569c-4c0c-ba02-8ffdb0492ece
job_name string optional
Example: good-job
phase string (enum) optional
Example: SUCCEEDED

The phase of the job invocation

started_at string (date-time) optional
Example: 2023-10-01T12:05:00Z
trigger object optional
Show child properties
manual object optional

Details about the manual trigger, if applicable

Show child properties
user object optional

The user who triggered the job

Show child properties
email string (email) optional
Example: [email protected]
full_name string optional
Example: John Doe
uuid string optional
Example: 550e8400-e29b-41d4-a716-446655440000
scheduled object optional
Example: {"schedule":{"cron":"0 0 * * *","time_zone":"America/New_York"}}

The schedule for the job

Show child properties
schedule object optional
Show child properties
cron string optional
Example: 0 0 * * *

The cron expression defining the schedule

time_zone string optional
Example: America/New_York

The time zone for the schedule

type string, one of: MANUAL, SCHEDULE, UNKNOWN optional
Example: MANUAL

The type of trigger that initiated the job invocation.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "job_invocation": [
    {
      "completed_at": "2025-09-11T11:04:40Z",
      "created_at": "2025-09-11T11:04:05Z",
      "deployment_id": "c020763f-ddb7-4112-a0df-7f01c69fc00b",
      "id": "ba32b134-569c-4c0c-ba02-8ffdb0492ece",
      "job_name": "good-job",
      "phase": "SUCCEEDED",
      "started_at": "2025-09-11T11:04:10Z",
      "trigger": [
        {
          "scheduled": [
            {
              "schedule": {
                "cron": "*/2 * * * *",
                "time_zone": "UTC"
              }
            }
          ],
          "type": "SCHEDULED"
        }
      ]
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve Job Invocation Logs

/v2/apps/{app_id}/jobs/{job_name}/invocations/{job_invocation_id}/logs
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Retrieve the logs of a past, in-progress, or active deployment. If a component name is specified, the logs will be limited to only that component. If deployment is omitted the active deployment will be selected (if available). The response will include links to either real-time logs of an in-progress or active deployment or archived logs of a past deployment.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

job_name string required
Example: component

The job name to list job invocations for.

job_invocation_id string required
Example: 123e4567-e89b-12d3-a456-426

The ID of the job invocation to retrieve.

Query Parameters

deployment_id string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a

The deployment ID

follow boolean optional
Example: true

Whether the logs should follow live updates.

type string, one of: JOB_INVOCATION required
Example: JOB_INVOCATION

The type of logs to retrieve

pod_connection_timeout string optional
Example: 3m

An optional time duration to wait if the underlying component instance is not immediately available. Default: 3m.

tail_lines string (int64) optional
Example: 100

The number of lines from the end of the logs to retrieve.

Request: /v2/apps/{app_id}/jobs/{job_name}/invocations/{job_invocation_id}/logs
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/jobs/{job_name}/invocations/{job_invocation_id}/logs"
import os
from pydo import Client

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

get_resp = client.apps.get_job_invocation_logs(app_id="4f6c71e2", job_name="component", job_invocation_id="3aa4d20e")

Responses

200

A JSON object with urls that point to Job Invocation logs
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
historic_urls array of string optional
live_url string optional
Example: ws://logs/build

A URL of the real-time live logs. This URL may use either the https:// or wss:// protocols and will keep pushing live logs as they become available.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "historic_logs": [
    "https://logs-example/archive/build.log"
  ],
  "live_url": "https://logs-example/build.log",
  "url": "https://logs/build.log"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve Active Deployment Aggregate Logs

/v2/apps/{app_id}/logs
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Retrieve the logs of the active deployment if one exists. The response will include links to either real-time logs of an in-progress or active deployment or archived logs of a past deployment. Note log_type=BUILD logs will return logs associated with the current active deployment (being served). To view build logs associated with in-progress build, the query must explicitly reference the deployment id.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

Query Parameters

follow boolean optional
Example: true

Whether the logs should follow live updates.

type string (enum) required
Example: BUILD

The type of logs to retrieve

  • BUILD: Build-time logs
  • DEPLOY: Deploy-time logs
  • RUN: Live run-time logs
  • RUN_RESTARTED: Logs of crashed/restarted instances during runtime
  • AUTOSCALE_EVENT: Logs of an autoscaling event (requires event_id)
Default: UNSPECIFIED
pod_connection_timeout string optional
Example: 3m

An optional time duration to wait if the underlying component instance is not immediately available. Default: 3m.

Request: /v2/apps/{app_id}/logs
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/logs"
import os
from pydo import Client

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

get_resp = client.apps.get_logs_active_deployment_aggregate(app_id="a6adf840")

Responses

200

A JSON object with urls that point to archived logs
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
historic_urls array of string optional
live_url string optional
Example: ws://logs/build

A URL of the real-time live logs. This URL may use either the https:// or wss:// protocols and will keep pushing live logs as they become available.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "historic_logs": [
    "https://logs-example/archive/build.log"
  ],
  "live_url": "https://logs-example/build.log",
  "url": "https://logs/build.log"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve App Daily Bandwidth Metrics

/v2/apps/{app_id}/metrics/bandwidth_daily
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Retrieve daily bandwidth usage metrics for a single app.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

Query Parameters

date string (date-time) optional
Example: 2023-01-17T00:00:00Z

Optional day to query. Only the date component of the timestamp will be considered. Default: yesterday.

Request: /v2/apps/{app_id}/metrics/bandwidth_daily
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{id}/metrics/bandwidth_daily"
import os
from pydo import Client

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

get_resp = client.apps.get_metrics_bandwidth_daily(app_id="4f6c71e2")

Responses

200

A JSON object with a app_bandwidth_usage key
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
app_bandwidth_usage array of object optional

A list of bandwidth usage details by app.

Show child properties
app_id string optional
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The ID of the app.

bandwidth_bytes string (uint64) optional
Example: 513668

The used bandwidth amount in bytes.

date string (date-time) optional
Example: 2023-01-17T00:00:00Z

The date for the metrics data.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "app_bandwidth_usage": [
    {
      "app_id": "4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf",
      "bandwidth_bytes": "513668"
    }
  ],
  "date": "2023-01-17T00:00:00Z"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Restart an App

/v2/apps/{app_id}/restart
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Perform a rolling restart of all or specific components in an app.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

Request Body: application/json

components array of string optional
Example: ["component1","component2"]
Request: /v2/apps/{app_id}/restart
Content type application/json 
{
  "components": [
    "component1",
    "component2"
  ]
}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/restart"
import os
from pydo import Client

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

create_resp = client.apps.restart(app_id="b6bdf840", body={"components": ["component1", "component2"]})

Responses

200

A JSON object with a deployment key.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
deployment object optional
Show child properties
cause string optional
Example: commit 9a4df0b pushed to github/digitalocean/sample-golang
cloned_from string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a
created_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
functions array of object optional
Show child properties
name string optional
Example: my-functions-component
namespace string optional
Example: ap-b2a93513-8d9b-4223-9d61-5e7272c81c32

The namespace where the functions are deployed.

source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405

The commit hash of the repository that was used to build this functions component.

id string optional
Example: b6bdf840-2854-4f87-a36c-5f231c617c84
jobs array of object optional
Show child properties
name string optional
Example: migrate-db
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
phase string (enum) optional
Example: ACTIVE
phase_last_updated_at string (date-time) optional
Example: 0001-01-01T00:00:00Z
progress object optional
Show child properties
error_steps integer (int32) optional
Example: 3
pending_steps integer (int32) optional
Example: 2
running_steps integer (int32) optional
Example: 2
steps array of object optional
Show child properties
component_name string optional
Example: component
ended_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
message_base string optional
Example: Building service

The base of a human-readable description of the step intended to be combined with the component name for presentation. For example:

message_base = "Building service" component_name = "api"

name string optional
Example: example_step
reason object optional
Additional nested properties not shown. Refer to the full API spec for details.
started_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
status string, one of: UNKNOWN, PENDING, RUNNING, ERROR, SUCCESS optional
Example: SUCCESS
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
success_steps integer (int32) optional
Example: 4
summary_steps array of object optional
Show child properties
component_name string optional
Example: component
ended_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
message_base string optional
Example: Building service

The base of a human-readable description of the step intended to be combined with the component name for presentation. For example:

message_base = "Building service" component_name = "api"

name string optional
Example: example_step
reason object optional
Additional nested properties not shown. Refer to the full API spec for details.
started_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
status string, one of: UNKNOWN, PENDING, RUNNING, ERROR, SUCCESS optional
Example: SUCCESS
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
total_steps integer (int32) optional
Example: 5
services array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
spec object optional

The desired configuration of an application.

Show child properties
databases array of object 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 (enum) optional
Example: PG
  • MYSQL: MySQL
  • PG: PostgreSQL
  • REDIS: Caching
  • MONGODB: MongoDB
  • KAFKA: Kafka
  • OPENSEARCH: OpenSearch
  • VALKEY: ValKey
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.

production boolean optional
Example: true

Whether this is a production or dev database.

version string optional
Example: 12

The version of the database engine

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.

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

domains array of object 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

minimum_tls_version string, one of: 1.2, 1.3 optional
Example: 1.3

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

type string, one of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS optional
Example: DEFAULT
  • 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
wildcard boolean optional
Example: true

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

zone string (hostname) 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.

egress object optional

Specification for app egress configurations.

Show child properties
type string, one of: AUTOASSIGN, DEDICATED_IP optional
Example: AUTOASSIGN
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.

functions array of object optional

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

Show child properties
alerts array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
cors object optional
envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: api

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

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

ingress object optional

Specification for app ingress configurations.

Show child properties
rules array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

kind string, one of: UNSPECIFIED, PRE_DEPLOY, POST_DEPLOY, FAILED_DEPLOY optional
Example: PRE_DEPLOY
  • 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.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
maintenance object optional

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

Show child properties
archive boolean optional
Example: true

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

enabled boolean optional
Example: true

Indicates whether maintenance mode should be enabled for the app.

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.

name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

cors object optional
health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
http_port integer (int64) 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.

internal_ports array of integer (int64) optional
Example: [80,443]

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

Additional nested properties not shown. Refer to the full API spec for details.
liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
protocol string, one of: HTTP, HTTP2 optional
Example: HTTP

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).
routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

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.

cors object optional
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.

index_document string optional
Example: main.html

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

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.

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Show child properties
egress_ips array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
id string optional
Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
workers array of object optional
Show child properties
name string optional
Example: queue-runner
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "deployment": {
    "cause": "commit 9a4df0b pushed to github/digitalocean/sample-golang",
    "created_at": "2020-07-28T18:00:00Z",
    "id": "b6bdf840-2854-4f87-a36c-5f231c617c84",
    "phase": "PENDING_BUILD",
    "phase_last_updated_at": "0001-01-01T00:00:00Z",
    "progress": {
      "pending_steps": 6,
      "steps": [
        {
          "name": "build",
          "status": "PENDING",
          "steps": [
            {
              "name": "initialize",
              "status": "PENDING"
            },
            {
              "name": "components",
              "status": "PENDING",
              "steps": [
                {
                  "component_name": "web",
                  "message_base": "Building service",
                  "name": "web",
                  "status": "PENDING"
                }
              ]
            }
          ]
        },
        {
          "name": "deploy",
          "status": "PENDING",
          "steps": [
            {
              "name": "initialize",
              "status": "PENDING"
            },
            {
              "name": "components",
              "status": "PENDING",
              "steps": [
                {
                  "component_name": "web",
                  "name": "web",
                  "status": "PENDING",
                  "steps": [
                    {
                      "component_name": "web",
                      "message_base": "Deploying service",
                      "name": "deploy",
                      "status": "PENDING"
                    },
                    {
                      "component_name": "web",
                      "message_base": "Waiting for service",
                      "name": "wait",
                      "status": "PENDING"
                    }
                  ]
                }
              ]
            },
            {
              "name": "finalize",
              "status": "PENDING"
            }
          ]
        }
      ],
      "total_steps": 6
    },
    "services": [
      {
        "name": "web",
        "source_commit_hash": "9a4df0b8e161e323bc3cdf1dc71878080fe144fa"
      }
    ],
    "spec": {
      "disable_edge_cache": true,
      "disable_email_obfuscation": true,
      "enhanced_threat_control_enabled": true,
      "name": "sample-golang",
      "region": "ams",
      "services": [
        {
          "environment_slug": "go",
          "github": {
            "branch": "branch",
            "repo": "digitalocean/sample-golang"
          },
          "instance_count": 2,
          "instance_size_slug": "apps-s-1vcpu-0.5gb",
          "name": "web",
          "routes": [
            {
              "path": "/"
            }
          ],
          "run_command": "bin/sample-golang"
        }
      ]
    },
    "tier_slug": "basic",
    "updated_at": "2020-07-28T18:00:00Z"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Rollback App

/v2/apps/{app_id}/rollback
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Rollback an app to a previous deployment. A new deployment will be created to perform the rollback. The app will be pinned to the rollback deployment preventing any new deployments from being created, either manually or through Auto Deploy on Push webhooks. To resume deployments, the rollback must be either committed or reverted.

It is recommended to use the Validate App Rollback endpoint to double check if the rollback is valid and if there are any warnings.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

Request Body: application/json

deployment_id string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a

The ID of the deployment to rollback to.

skip_pin boolean optional
Example: false

Whether to skip pinning the rollback deployment. If false, the rollback deployment will be pinned and any new deployments including Auto Deploy on Push hooks will be disabled until the rollback is either manually committed or reverted via the CommitAppRollback or RevertAppRollback endpoints respectively. If true, the rollback will be immediately committed and the app will remain unpinned.

Request: /v2/apps/{app_id}/rollback
Content type application/json 
{
  "deployment_id": "3aa4d20e-5527-4c00-b496-601fbd22520a",
  "skip_pin": false
}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{ "deployment_id": "3aa4d20e-5527-4c00-b496-601fbd22520a" }' \
  "https://api.digitalocean.com/v2/apps/{app_id}/rollback"
import os
from pydo import Client

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

create_resp = client.apps.create_rollback(app_id="b6bdf840")

Responses

200

A JSON object with a deployment key.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
deployment object optional
Show child properties
cause string optional
Example: commit 9a4df0b pushed to github/digitalocean/sample-golang
cloned_from string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a
created_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
functions array of object optional
Show child properties
name string optional
Example: my-functions-component
namespace string optional
Example: ap-b2a93513-8d9b-4223-9d61-5e7272c81c32

The namespace where the functions are deployed.

source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405

The commit hash of the repository that was used to build this functions component.

id string optional
Example: b6bdf840-2854-4f87-a36c-5f231c617c84
jobs array of object optional
Show child properties
name string optional
Example: migrate-db
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
phase string (enum) optional
Example: ACTIVE
phase_last_updated_at string (date-time) optional
Example: 0001-01-01T00:00:00Z
progress object optional
Show child properties
error_steps integer (int32) optional
Example: 3
pending_steps integer (int32) optional
Example: 2
running_steps integer (int32) optional
Example: 2
steps array of object optional
Show child properties
component_name string optional
Example: component
ended_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
message_base string optional
Example: Building service

The base of a human-readable description of the step intended to be combined with the component name for presentation. For example:

message_base = "Building service" component_name = "api"

name string optional
Example: example_step
reason object optional
Additional nested properties not shown. Refer to the full API spec for details.
started_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
status string, one of: UNKNOWN, PENDING, RUNNING, ERROR, SUCCESS optional
Example: SUCCESS
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
success_steps integer (int32) optional
Example: 4
summary_steps array of object optional
Show child properties
component_name string optional
Example: component
ended_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
message_base string optional
Example: Building service

The base of a human-readable description of the step intended to be combined with the component name for presentation. For example:

message_base = "Building service" component_name = "api"

name string optional
Example: example_step
reason object optional
Additional nested properties not shown. Refer to the full API spec for details.
started_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
status string, one of: UNKNOWN, PENDING, RUNNING, ERROR, SUCCESS optional
Example: SUCCESS
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
total_steps integer (int32) optional
Example: 5
services array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
spec object optional

The desired configuration of an application.

Show child properties
databases array of object 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 (enum) optional
Example: PG
  • MYSQL: MySQL
  • PG: PostgreSQL
  • REDIS: Caching
  • MONGODB: MongoDB
  • KAFKA: Kafka
  • OPENSEARCH: OpenSearch
  • VALKEY: ValKey
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.

production boolean optional
Example: true

Whether this is a production or dev database.

version string optional
Example: 12

The version of the database engine

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.

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

domains array of object 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

minimum_tls_version string, one of: 1.2, 1.3 optional
Example: 1.3

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

type string, one of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS optional
Example: DEFAULT
  • 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
wildcard boolean optional
Example: true

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

zone string (hostname) 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.

egress object optional

Specification for app egress configurations.

Show child properties
type string, one of: AUTOASSIGN, DEDICATED_IP optional
Example: AUTOASSIGN
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.

functions array of object optional

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

Show child properties
alerts array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
cors object optional
envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: api

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

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

ingress object optional

Specification for app ingress configurations.

Show child properties
rules array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

kind string, one of: UNSPECIFIED, PRE_DEPLOY, POST_DEPLOY, FAILED_DEPLOY optional
Example: PRE_DEPLOY
  • 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.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
maintenance object optional

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

Show child properties
archive boolean optional
Example: true

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

enabled boolean optional
Example: true

Indicates whether maintenance mode should be enabled for the app.

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.

name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

cors object optional
health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
http_port integer (int64) 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.

internal_ports array of integer (int64) optional
Example: [80,443]

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

Additional nested properties not shown. Refer to the full API spec for details.
liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
protocol string, one of: HTTP, HTTP2 optional
Example: HTTP

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).
routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

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.

cors object optional
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.

index_document string optional
Example: main.html

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

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.

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Show child properties
egress_ips array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
id string optional
Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
workers array of object optional
Show child properties
name string optional
Example: queue-runner
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "deployment": {
    "cause": "commit 9a4df0b pushed to github/digitalocean/sample-golang",
    "created_at": "2020-07-28T18:00:00Z",
    "id": "b6bdf840-2854-4f87-a36c-5f231c617c84",
    "phase": "PENDING_BUILD",
    "phase_last_updated_at": "0001-01-01T00:00:00Z",
    "progress": {
      "pending_steps": 6,
      "steps": [
        {
          "name": "build",
          "status": "PENDING",
          "steps": [
            {
              "name": "initialize",
              "status": "PENDING"
            },
            {
              "name": "components",
              "status": "PENDING",
              "steps": [
                {
                  "component_name": "web",
                  "message_base": "Building service",
                  "name": "web",
                  "status": "PENDING"
                }
              ]
            }
          ]
        },
        {
          "name": "deploy",
          "status": "PENDING",
          "steps": [
            {
              "name": "initialize",
              "status": "PENDING"
            },
            {
              "name": "components",
              "status": "PENDING",
              "steps": [
                {
                  "component_name": "web",
                  "name": "web",
                  "status": "PENDING",
                  "steps": [
                    {
                      "component_name": "web",
                      "message_base": "Deploying service",
                      "name": "deploy",
                      "status": "PENDING"
                    },
                    {
                      "component_name": "web",
                      "message_base": "Waiting for service",
                      "name": "wait",
                      "status": "PENDING"
                    }
                  ]
                }
              ]
            },
            {
              "name": "finalize",
              "status": "PENDING"
            }
          ]
        }
      ],
      "total_steps": 6
    },
    "services": [
      {
        "name": "web",
        "source_commit_hash": "9a4df0b8e161e323bc3cdf1dc71878080fe144fa"
      }
    ],
    "spec": {
      "disable_edge_cache": true,
      "disable_email_obfuscation": true,
      "enhanced_threat_control_enabled": true,
      "name": "sample-golang",
      "region": "ams",
      "services": [
        {
          "environment_slug": "go",
          "github": {
            "branch": "branch",
            "repo": "digitalocean/sample-golang"
          },
          "instance_count": 2,
          "instance_size_slug": "apps-s-1vcpu-0.5gb",
          "name": "web",
          "routes": [
            {
              "path": "/"
            }
          ],
          "run_command": "bin/sample-golang"
        }
      ]
    },
    "tier_slug": "basic",
    "updated_at": "2020-07-28T18:00:00Z"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Commit App Rollback

/v2/apps/{app_id}/rollback/commit
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Commit an app rollback. This action permanently applies the rollback and unpins the app to resume new deployments.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

Request: /v2/apps/{app_id}/rollback/commit
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/rollback/commit"
import os
from pydo import Client

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

commit_resp = client.apps.commit_rollback("1")

Responses

200

The action was successful and the response body is empty.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Revert App Rollback

/v2/apps/{app_id}/rollback/revert
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Revert an app rollback. This action reverts the active rollback by creating a new deployment from the latest app spec prior to the rollback and unpins the app to resume new deployments.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

Request: /v2/apps/{app_id}/rollback/revert
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{app_id}/rollback/revert"
import os
from pydo import Client

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

revert_resp = client.apps.revert_rollback("1")

Responses

200

A JSON object with a deployment key.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
deployment object optional
Show child properties
cause string optional
Example: commit 9a4df0b pushed to github/digitalocean/sample-golang
cloned_from string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a
created_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
functions array of object optional
Show child properties
name string optional
Example: my-functions-component
namespace string optional
Example: ap-b2a93513-8d9b-4223-9d61-5e7272c81c32

The namespace where the functions are deployed.

source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405

The commit hash of the repository that was used to build this functions component.

id string optional
Example: b6bdf840-2854-4f87-a36c-5f231c617c84
jobs array of object optional
Show child properties
name string optional
Example: migrate-db
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
phase string (enum) optional
Example: ACTIVE
phase_last_updated_at string (date-time) optional
Example: 0001-01-01T00:00:00Z
progress object optional
Show child properties
error_steps integer (int32) optional
Example: 3
pending_steps integer (int32) optional
Example: 2
running_steps integer (int32) optional
Example: 2
steps array of object optional
Show child properties
component_name string optional
Example: component
ended_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
message_base string optional
Example: Building service

The base of a human-readable description of the step intended to be combined with the component name for presentation. For example:

message_base = "Building service" component_name = "api"

name string optional
Example: example_step
reason object optional
Additional nested properties not shown. Refer to the full API spec for details.
started_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
status string, one of: UNKNOWN, PENDING, RUNNING, ERROR, SUCCESS optional
Example: SUCCESS
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
success_steps integer (int32) optional
Example: 4
summary_steps array of object optional
Show child properties
component_name string optional
Example: component
ended_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
message_base string optional
Example: Building service

The base of a human-readable description of the step intended to be combined with the component name for presentation. For example:

message_base = "Building service" component_name = "api"

name string optional
Example: example_step
reason object optional
Additional nested properties not shown. Refer to the full API spec for details.
started_at string (date-time) optional
Example: 2020-11-19T20:27:18Z
status string, one of: UNKNOWN, PENDING, RUNNING, ERROR, SUCCESS optional
Example: SUCCESS
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
total_steps integer (int32) optional
Example: 5
services array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
spec object optional

The desired configuration of an application.

Show child properties
databases array of object 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 (enum) optional
Example: PG
  • MYSQL: MySQL
  • PG: PostgreSQL
  • REDIS: Caching
  • MONGODB: MongoDB
  • KAFKA: Kafka
  • OPENSEARCH: OpenSearch
  • VALKEY: ValKey
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.

production boolean optional
Example: true

Whether this is a production or dev database.

version string optional
Example: 12

The version of the database engine

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.

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

domains array of object 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

minimum_tls_version string, one of: 1.2, 1.3 optional
Example: 1.3

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

type string, one of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS optional
Example: DEFAULT
  • 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
wildcard boolean optional
Example: true

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

zone string (hostname) 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.

egress object optional

Specification for app egress configurations.

Show child properties
type string, one of: AUTOASSIGN, DEDICATED_IP optional
Example: AUTOASSIGN
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.

functions array of object optional

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

Show child properties
alerts array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
cors object optional
envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: api

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

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

ingress object optional

Specification for app ingress configurations.

Show child properties
rules array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

kind string, one of: UNSPECIFIED, PRE_DEPLOY, POST_DEPLOY, FAILED_DEPLOY optional
Example: PRE_DEPLOY
  • 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.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
maintenance object optional

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

Show child properties
archive boolean optional
Example: true

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

enabled boolean optional
Example: true

Indicates whether maintenance mode should be enabled for the app.

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.

name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

cors object optional
health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
http_port integer (int64) 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.

internal_ports array of integer (int64) optional
Example: [80,443]

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

Additional nested properties not shown. Refer to the full API spec for details.
liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
protocol string, one of: HTTP, HTTP2 optional
Example: HTTP

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).
routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

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.

cors object optional
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.

index_document string optional
Example: main.html

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

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.

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Show child properties
egress_ips array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
id string optional
Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
workers array of object optional
Show child properties
name string optional
Example: queue-runner
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "deployment": {
    "cause": "commit 9a4df0b pushed to github/digitalocean/sample-golang",
    "created_at": "2020-07-28T18:00:00Z",
    "id": "b6bdf840-2854-4f87-a36c-5f231c617c84",
    "phase": "PENDING_BUILD",
    "phase_last_updated_at": "0001-01-01T00:00:00Z",
    "progress": {
      "pending_steps": 6,
      "steps": [
        {
          "name": "build",
          "status": "PENDING",
          "steps": [
            {
              "name": "initialize",
              "status": "PENDING"
            },
            {
              "name": "components",
              "status": "PENDING",
              "steps": [
                {
                  "component_name": "web",
                  "message_base": "Building service",
                  "name": "web",
                  "status": "PENDING"
                }
              ]
            }
          ]
        },
        {
          "name": "deploy",
          "status": "PENDING",
          "steps": [
            {
              "name": "initialize",
              "status": "PENDING"
            },
            {
              "name": "components",
              "status": "PENDING",
              "steps": [
                {
                  "component_name": "web",
                  "name": "web",
                  "status": "PENDING",
                  "steps": [
                    {
                      "component_name": "web",
                      "message_base": "Deploying service",
                      "name": "deploy",
                      "status": "PENDING"
                    },
                    {
                      "component_name": "web",
                      "message_base": "Waiting for service",
                      "name": "wait",
                      "status": "PENDING"
                    }
                  ]
                }
              ]
            },
            {
              "name": "finalize",
              "status": "PENDING"
            }
          ]
        }
      ],
      "total_steps": 6
    },
    "services": [
      {
        "name": "web",
        "source_commit_hash": "9a4df0b8e161e323bc3cdf1dc71878080fe144fa"
      }
    ],
    "spec": {
      "disable_edge_cache": true,
      "disable_email_obfuscation": true,
      "enhanced_threat_control_enabled": true,
      "name": "sample-golang",
      "region": "ams",
      "services": [
        {
          "environment_slug": "go",
          "github": {
            "branch": "branch",
            "repo": "digitalocean/sample-golang"
          },
          "instance_count": 2,
          "instance_size_slug": "apps-s-1vcpu-0.5gb",
          "name": "web",
          "routes": [
            {
              "path": "/"
            }
          ],
          "run_command": "bin/sample-golang"
        }
      ]
    },
    "tier_slug": "basic",
    "updated_at": "2020-07-28T18:00:00Z"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Validate App Rollback

/v2/apps/{app_id}/rollback/validate
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Check whether an app can be rolled back to a specific deployment. This endpoint can also be used to check if there are any warnings or validation conditions that will cause the rollback to proceed under unideal circumstances. For example, if a component must be rebuilt as part of the rollback causing it to take longer than usual.

Path Parameters

app_id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The app ID

Request Body: application/json

deployment_id string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a

The ID of the deployment to rollback to.

skip_pin boolean optional
Example: false

Whether to skip pinning the rollback deployment. If false, the rollback deployment will be pinned and any new deployments including Auto Deploy on Push hooks will be disabled until the rollback is either manually committed or reverted via the CommitAppRollback or RevertAppRollback endpoints respectively. If true, the rollback will be immediately committed and the app will remain unpinned.

Request: /v2/apps/{app_id}/rollback/validate
Content type application/json 
{
  "deployment_id": "3aa4d20e-5527-4c00-b496-601fbd22520a",
  "skip_pin": false
}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{ "deployment_id": "3aa4d20e-5527-4c00-b496-601fbd22520a" }' \
  "https://api.digitalocean.com/v2/apps/{app_id}/rollback/validate"
import os
from pydo import Client

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

validate_req = {"deployment_id": "2", "skip_pin": False}

validate_resp = client.apps.validate_rollback("1", validate_req)

Responses

200

A JSON object with the validation results.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
error object optional
valid boolean optional

Indicates whether the app can be rolled back to the specified deployment.

warnings array of object optional

Contains a list of warnings that may cause the rollback to run under unideal circumstances.

Show child properties
code string (enum) optional
Example: exceeded_revision_limit

A code identifier that represents the failing condition.

Failing conditions:

  • incompatible_phase - indicates that the deployment's phase is not suitable for rollback.
  • incompatible_result - indicates that the deployment's result is not suitable for rollback.
  • exceeded_revision_limit - indicates that the app has exceeded the rollback revision limits for its tier.
  • app_pinned - indicates that there is already a rollback in progress and the app is pinned.
  • database_config_conflict - indicates that the deployment's database config is different than the current config.
  • region_conflict - indicates that the deployment's region differs from the current app region.

Warning conditions:

  • static_site_requires_rebuild - indicates that the deployment contains at least one static site that will require a rebuild.
  • image_source_missing_digest - indicates that the deployment contains at least one component with an image source that is missing a digest.
components array of string optional
Example: ["www"]
message string optional
Example: the deployment is past the maximum historical revision limit of 0 for the "starter" app tier

A human-readable message describing the failing condition.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
Example 
{
  "error": {
    "code": "incompatible_result",
    "message": "deployment result \"failed\" is unsuitable for rollback"
  },
  "valid": false
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve an Existing App

/v2/apps/{id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:read

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Retrieve details about an existing app by either its ID or name. To retrieve an app by its name, do not include an ID in the request path. Information about the current active deployment as well as any in progress ones will also be included in the response.

Path Parameters

id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The ID of the app

Query Parameters

name string optional
Example: myApp

The name of the app to retrieve.

Request: /v2/apps/{id}
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{id}"
import os
from pydo import Client

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

create_resp = client.apps.get(id="4f6c71e2")

Responses

200

A JSON with key app
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
app object optional

An application's configuration and status.

Show child properties
active_deployment object optional
Show child properties
cause string optional
Example: commit 9a4df0b pushed to github/digitalocean/sample-golang
cloned_from string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a
created_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
functions array of object optional
Show child properties
name string optional
Example: my-functions-component
namespace string optional
Example: ap-b2a93513-8d9b-4223-9d61-5e7272c81c32

The namespace where the functions are deployed.

source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405

The commit hash of the repository that was used to build this functions component.

id string optional
Example: b6bdf840-2854-4f87-a36c-5f231c617c84
jobs array of object optional
Show child properties
name string optional
Example: migrate-db
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
phase string (enum) optional
Example: ACTIVE
phase_last_updated_at string (date-time) optional
Example: 0001-01-01T00:00:00Z
progress object optional
Show child properties
error_steps integer (int32) optional
Example: 3
pending_steps integer (int32) optional
Example: 2
running_steps integer (int32) optional
Example: 2
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
success_steps integer (int32) optional
Example: 4
summary_steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
total_steps integer (int32) optional
Example: 5
services array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
spec object optional

The desired configuration of an application.

Show child properties
databases array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

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

domains array of object optional

A set of hostnames where the application will be available.

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

Specification for app egress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
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.

functions array of object optional

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

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

Specification for app ingress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

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

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

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Additional nested properties not shown. Refer to the full API spec for details.
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
workers array of object optional
Show child properties
name string optional
Example: queue-runner
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
created_at string (date-time) optional read-only
Example: 2020-11-19T20:27:18Z
dedicated_ips array of object optional read-only
Show child properties
id string optional
Example: 9e7bc2ac-205a-45d6-919c-e1ac5e73f962
ip string optional
Example: 192.168.1.1
status string, one of: UNKNOWN, ASSIGNING, ASSIGNED, REMOVED optional read-only
Example: ASSIGNED
default_ingress string optional read-only
Example: digitalocean.com
domains array of object optional read-only
Show child properties
certificate_expires_at string (date-time) optional read-only
Example: 2024-01-29T23:59:59Z
id string optional
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf
phase string, one of: UNKNOWN, PENDING, CONFIGURING, ACTIVE, ERROR optional
Example: ACTIVE
progress object optional
Show child properties
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
rotate_validation_records boolean optional read-only
spec object optional
Show child properties
domain string required
Example: app.example.com

The hostname for the domain

minimum_tls_version string, one of: 1.2, 1.3 optional
Example: 1.3

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

type string, one of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS optional
Example: DEFAULT
  • 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
wildcard boolean optional
Example: true

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

zone string (hostname) 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.

validations array of object optional
Show child properties
txt_name string optional read-only
Example: _acme-challenge.app.example.com
txt_value string optional read-only
Example: lXLOcN6cPv0nproViNcUHcahD9TrIPlNgdwesj0pYpk
id string optional read-only
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf
in_progress_deployment object optional
Show child properties
cause string optional
Example: commit 9a4df0b pushed to github/digitalocean/sample-golang
cloned_from string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a
created_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
functions array of object optional
Show child properties
name string optional
Example: my-functions-component
namespace string optional
Example: ap-b2a93513-8d9b-4223-9d61-5e7272c81c32

The namespace where the functions are deployed.

source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405

The commit hash of the repository that was used to build this functions component.

id string optional
Example: b6bdf840-2854-4f87-a36c-5f231c617c84
jobs array of object optional
Show child properties
name string optional
Example: migrate-db
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
phase string (enum) optional
Example: ACTIVE
phase_last_updated_at string (date-time) optional
Example: 0001-01-01T00:00:00Z
progress object optional
Show child properties
error_steps integer (int32) optional
Example: 3
pending_steps integer (int32) optional
Example: 2
running_steps integer (int32) optional
Example: 2
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
success_steps integer (int32) optional
Example: 4
summary_steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
total_steps integer (int32) optional
Example: 5
services array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
spec object optional

The desired configuration of an application.

Show child properties
databases array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

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

domains array of object optional

A set of hostnames where the application will be available.

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

Specification for app egress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
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.

functions array of object optional

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

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

Specification for app ingress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

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

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

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Additional nested properties not shown. Refer to the full API spec for details.
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
workers array of object optional
Show child properties
name string optional
Example: queue-runner
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
last_deployment_created_at string (date-time) optional read-only
Example: 2020-11-19T20:27:18Z
live_domain string optional read-only
Example: live_domain
live_url string optional read-only
Example: google.com
live_url_base string optional read-only
Example: digitalocean.com
owner_uuid string optional read-only
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf
pending_deployment object optional
pinned_deployment object optional
project_id string optional read-only
Example: 88b72d1a-b78a-4d9f-9090-b53c4399073f

Requires project:read scope.

region object optional
Show child properties
continent string optional read-only
Example: europe
data_centers array of string optional read-only
Example: ["ams"]
default boolean optional read-only
Example: true

Whether or not the region is presented as the default.

disabled boolean optional read-only
Example: true
flag string optional read-only
Example: ams
label string optional read-only
Example: ams
reason string optional read-only
Example: to crowded
slug string optional read-only
Example: basic
spec object required

The desired configuration of an application.

Show child properties
databases array of object 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 (enum) optional
Example: PG
  • MYSQL: MySQL
  • PG: PostgreSQL
  • REDIS: Caching
  • MONGODB: MongoDB
  • KAFKA: Kafka
  • OPENSEARCH: OpenSearch
  • VALKEY: ValKey
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.

production boolean optional
Example: true

Whether this is a production or dev database.

version string optional
Example: 12

The version of the database engine

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.

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

domains array of object 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

minimum_tls_version string, one of: 1.2, 1.3 optional
Example: 1.3

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

type string, one of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS optional
Example: DEFAULT
  • 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
wildcard boolean optional
Example: true

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

zone string (hostname) 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.

egress object optional

Specification for app egress configurations.

Show child properties
type string, one of: AUTOASSIGN, DEDICATED_IP optional
Example: AUTOASSIGN
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.

functions array of object optional

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

Show child properties
alerts array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
cors object optional
envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: api

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

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

ingress object optional

Specification for app ingress configurations.

Show child properties
rules array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

kind string, one of: UNSPECIFIED, PRE_DEPLOY, POST_DEPLOY, FAILED_DEPLOY optional
Example: PRE_DEPLOY
  • 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.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
maintenance object optional

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

Show child properties
archive boolean optional
Example: true

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

enabled boolean optional
Example: true

Indicates whether maintenance mode should be enabled for the app.

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.

name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

cors object optional
health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
http_port integer (int64) 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.

internal_ports array of integer (int64) optional
Example: [80,443]

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

Additional nested properties not shown. Refer to the full API spec for details.
liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
protocol string, one of: HTTP, HTTP2 optional
Example: HTTP

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).
routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

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.

cors object optional
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.

index_document string optional
Example: main.html

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

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.

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Show child properties
egress_ips array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
id string optional
Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional read-only
Example: 2020-12-01T00:42:16Z
vpc object optional read-only
Show child properties
egress_ips array of object optional
Show child properties
ip string optional
Example: 10.0.0.1
id string optional
Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "app": {
    "active_deployment": {
      "cause": "manual",
      "created_at": "2021-02-10T17:05:30Z",
      "id": "991dfa59-6a23-459f-86d6-67dfa2c6f1e3",
      "phase": "ACTIVE",
      "phase_last_updated_at": "2021-02-10T17:06:53Z",
      "progress": {
        "steps": [
          {
            "ended_at": "2021-02-10T17:06:19.807834070Z",
            "name": "build",
            "started_at": "2021-02-10T17:05:35.572287990Z",
            "status": "SUCCESS",
            "steps": [
              {
                "ended_at": "2021-02-10T17:05:36.093995229Z",
                "name": "initialize",
                "started_at": "2021-02-10T17:05:35.572347485Z",
                "status": "SUCCESS"
              },
              {
                "ended_at": "2021-02-10T17:06:19.461737040Z",
                "name": "components",
                "started_at": "2021-02-10T17:05:36.094015928Z",
                "status": "SUCCESS",
                "steps": [
                  {
                    "component_name": "web",
                    "message_base": "Building service",
                    "name": "web",
                    "status": "SUCCESS"
                  }
                ]
              }
            ]
          },
          {
            "ended_at": "2021-02-10T17:06:53.404104185Z",
            "name": "deploy",
            "started_at": "2021-02-10T17:06:25.143932418Z",
            "status": "SUCCESS",
            "steps": [
              {
                "ended_at": "2021-02-10T17:06:26.120343872Z",
                "name": "initialize",
                "started_at": "2021-02-10T17:06:25.143957508Z",
                "status": "SUCCESS"
              },
              {
                "ended_at": "2021-02-10T17:06:50.029695913Z",
                "name": "components",
                "started_at": "2021-02-10T17:06:26.120385561Z",
                "status": "SUCCESS",
                "steps": [
                  {
                    "component_name": "web",
                    "name": "web",
                    "status": "SUCCESS",
                    "steps": [
                      {
                        "component_name": "web",
                        "message_base": "Deploying service",
                        "name": "deploy",
                        "status": "SUCCESS"
                      },
                      {
                        "component_name": "web",
                        "message_base": "Waiting for service",
                        "name": "wait",
                        "status": "SUCCESS"
                      }
                    ]
                  }
                ]
              },
              {
                "ended_at": "2021-02-10T17:06:53.404065961Z",
                "name": "finalize",
                "started_at": "2021-02-10T17:06:50.348459495Z",
                "status": "SUCCESS"
              }
            ]
          }
        ],
        "success_steps": 6,
        "total_steps": 6
      },
      "services": [
        {
          "name": "web",
          "source_commit_hash": "db6936cb46047c576962962eed81ad52c21f35d7"
        }
      ],
      "spec": {
        "domains": [
          {
            "domain": "sample-golang.example.com",
            "minimum_tls_version": "1.3",
            "zone": "example.com"
          }
        ],
        "name": "sample-golang",
        "region": "ams",
        "services": [
          {
            "environment_slug": "go",
            "github": {
              "branch": "main",
              "repo": "ChiefMateStarbuck/sample-golang"
            },
            "http_port": 8080,
            "instance_count": 1,
            "instance_size_slug": "apps-s-1vcpu-0.5gb",
            "name": "web",
            "routes": [
              {
                "path": "/"
              }
            ],
            "run_command": "bin/sample-golang"
          }
        ],
        "vpc": {
          "egress_ips": [
            {
              "ip": "10.0.0.1"
            }
          ],
          "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac"
        }
      },
      "tier_slug": "basic",
      "updated_at": "2021-02-10T17:06:53Z"
    },
    "created_at": "2021-02-10T16:45:14Z",
    "dedicated_ips": [
      {
        "id": "c24d8f48-3bc4-49f5-8ca0-58e8164427ac",
        "ip": "192.168.1.1",
        "status": "ASSIGNED"
      },
      {
        "id": "4768fb15-2837-4dda-9be5-3951df4bc3d0",
        "ip": "192.168.1.2",
        "status": "ASSIGNED"
      }
    ],
    "default_ingress": "https://sample-golang-zyhgn.ondigitalocean.app",
    "domains": [
      {
        "certificate_expires_at": "2024-01-29T23:59:59Z",
        "id": "e206c64e-a1a3-11ed-9e6e-9b7b6dc9a52b",
        "phase": "CONFIGURING",
        "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"
            }
          ]
        },
        "rotate_validation_records": false,
        "spec": {
          "domain": "sample-golang.example.com",
          "minimum_tls_version": "1.3",
          "type": "PRIMARY",
          "zone": "example.com"
        }
      }
    ],
    "id": "c2a93513-8d9b-4223-9d61-5e7272c81cf5",
    "last_deployment_created_at": "2021-02-10T17:05:30Z",
    "live_domain": "sample-golang-zyhgn.ondigitalocean.app",
    "live_url": "https://sample-golang-zyhgn.ondigitalocean.app",
    "live_url_base": "https://sample-golang-zyhgn.ondigitalocean.app",
    "owner_uuid": "a4e16f25-cdd1-4483-b246-d77f283c9209",
    "pending_deployment": {
      "id": "3aa4d20e-5527-4c00-b496-601fbd22520a",
      "spec": {
        "domains": [
          {
            "domain": "sample-php.example.com",
            "minimum_tls_version": "1.3",
            "type": "PRIMARY",
            "zone": "example.com"
          }
        ],
        "name": "sample-php",
        "region": "fra",
        "services": [
          {
            "environment_slug": "php",
            "git": {
              "branch": "main",
              "repo_clone_url": "https://github.com/digitalocean/sample-php.git"
            },
            "http_port": 8080,
            "instance_count": 1,
            "instance_size_slug": "apps-s-1vcpu-0.5gb",
            "name": "sample-php",
            "routes": [
              {
                "path": "/"
              }
            ],
            "run_command": "heroku-php-apache2"
          }
        ],
        "vpc": {
          "egress_ips": [
            {
              "ip": "10.0.0.1"
            }
          ],
          "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac"
        }
      }
    },
    "project_id": "88b72d1a-b78a-4d9f-9090-b53c4399073f",
    "region": {
      "continent": "Europe",
      "data_centers": [
        "ams3"
      ],
      "flag": "netherlands",
      "label": "Amsterdam",
      "slug": "ams"
    },
    "spec": {
      "disable_edge_cache": true,
      "domains": [
        {
          "domain": "sample-golang.example.com",
          "minimum_tls_version": "1.3",
          "zone": "example.com"
        }
      ],
      "enhanced_threat_control_enabled": true,
      "name": "sample-golang",
      "region": "ams",
      "services": [
        {
          "environment_slug": "go",
          "github": {
            "branch": "main",
            "repo": "ChiefMateStarbuck/sample-golang"
          },
          "http_port": 8080,
          "instance_count": 1,
          "instance_size_slug": "apps-s-1vcpu-0.5gb",
          "name": "web",
          "routes": [
            {
              "path": "/"
            }
          ],
          "run_command": "bin/sample-golang"
        }
      ],
      "vpc": {
        "egress_ips": [
          {
            "ip": "10.0.0.1"
          }
        ],
        "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac"
      }
    },
    "tier_slug": "basic",
    "updated_at": "2021-02-10T17:06:56Z",
    "vpc": {
      "egress_ips": [
        {
          "ip": "10.0.0.1"
        }
      ],
      "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac"
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

PUT Update an App

/v2/apps/{id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:update

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

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

Path Parameters

id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The ID of the app

Request Body: application/json

spec object required

The desired configuration of an application.

Show child properties
databases array of object 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 (enum) optional
Example: PG
  • MYSQL: MySQL
  • PG: PostgreSQL
  • REDIS: Caching
  • MONGODB: MongoDB
  • KAFKA: Kafka
  • OPENSEARCH: OpenSearch
  • VALKEY: ValKey
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.

production boolean optional
Example: true

Whether this is a production or dev database.

version string optional
Example: 12

The version of the database engine

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.

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

domains array of object 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

minimum_tls_version string, one of: 1.2, 1.3 optional
Example: 1.3

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

type string, one of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS optional
Example: DEFAULT
  • 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
wildcard boolean optional
Example: true

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

zone string (hostname) 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.

egress object optional

Specification for app egress configurations.

Show child properties
type string, one of: AUTOASSIGN, DEDICATED_IP optional
Example: AUTOASSIGN
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.

functions array of object optional

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

Show child properties
alerts array of object optional
Show child properties
disabled boolean optional
Example: false

Is the alert disabled?

operator string, one of: UNSPECIFIED_OPERATOR, GREATER_THAN, LESS_THAN optional
Example: GREATER_THAN
rule string (enum) optional
Example: CPU_UTILIZATION
value number (float) optional
Example: 2.32

Threshold value for alert

window string, one of: UNSPECIFIED_WINDOW, FIVE_MINUTES, TEN_MINUTES, THIRTY_MINUTES, ONE_HOUR optional
Example: FIVE_MINUTES
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

cors object optional
envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: api

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

routes array of object 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.

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.

ingress object optional

Specification for app ingress configurations.

Show child properties
rules array of object optional

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

Show child properties
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.
cors object optional
Additional nested properties not shown. Refer to the full API spec for details.
match object optional

The match configuration for the rule.

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.
jobs array of object optional

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

Show child properties
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

build_command string optional
Example: npm run build

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

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.

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.

envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

image object optional
Show child properties
deploy_on_push object optional
Additional nested properties not shown. Refer to the full API spec for details.
digest string optional
Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

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

registry string optional
Example: registry.hub.docker.com

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

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.
registry_type string, one of: DOCKER_HUB, DOCR, GHCR optional
Example: DOCR
  • DOCKER_HUB: The DockerHub container registry type.
  • DOCR: The DigitalOcean container registry type.
  • GHCR: The Github container registry type.
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.

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Show child properties
max_instance_count integer (uint32) optional
Example: 3

The maximum amount of instances for this component. Must be more than min_instance_count.

metrics object optional

The metrics that the component is scaled on.

Additional nested properties not shown. Refer to the full API spec for details.
min_instance_count integer (uint32) optional
Example: 2

The minimum amount of instances for this component. Must be less than max_instance_count.

instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

kind string, one of: UNSPECIFIED, PRE_DEPLOY, POST_DEPLOY, FAILED_DEPLOY optional
Example: PRE_DEPLOY
  • 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.
termination object optional
Show child properties
grace_period_seconds integer (int32) 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)

maintenance object optional

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

Show child properties
archive boolean optional
Example: true

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

enabled boolean optional
Example: true

Indicates whether maintenance mode should be enabled for the app.

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.

name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Show child properties
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

build_command string optional
Example: npm run build

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

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.

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.

envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

image object optional
Show child properties
deploy_on_push object optional
Additional nested properties not shown. Refer to the full API spec for details.
digest string optional
Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

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

registry string optional
Example: registry.hub.docker.com

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

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.
registry_type string, one of: DOCKER_HUB, DOCR, GHCR optional
Example: DOCR
  • DOCKER_HUB: The DockerHub container registry type.
  • DOCR: The DigitalOcean container registry type.
  • GHCR: The Github container registry type.
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.

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Show child properties
max_instance_count integer (uint32) optional
Example: 3

The maximum amount of instances for this component. Must be more than min_instance_count.

metrics object optional

The metrics that the component is scaled on.

Additional nested properties not shown. Refer to the full API spec for details.
min_instance_count integer (uint32) optional
Example: 2

The minimum amount of instances for this component. Must be less than max_instance_count.

instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

cors object optional
health_check object optional
Show child properties
failure_threshold integer (int32) optional
Example: 2

The number of failed health checks before considered unhealthy.

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 (int32) optional
Example: 30

The number of seconds to wait before beginning health checks.

period_seconds integer (int32) optional
Example: 60

The number of seconds to wait between health checks.

port integer (int64) 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.

success_threshold integer (int32) optional
Example: 3

The number of successful health checks before considered healthy.

timeout_seconds integer (int32) optional
Example: 45

The number of seconds after which the check times out.

http_port integer (int64) 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.

internal_ports array of integer (int64) optional
Example: [80,443]

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

liveness_health_check object optional
Show child properties
failure_threshold integer (int32) optional
Example: 18

The number of failed health checks before considered unhealthy.

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 (int32) optional
Example: 30

The number of seconds to wait before beginning health checks.

period_seconds integer (int32) optional
Example: 10

The number of seconds to wait between health checks.

port integer (int64) optional
Example: 80

The port on which the health check will be performed.

success_threshold integer (int32) optional
Example: 1

The number of successful health checks before considered healthy.

timeout_seconds integer (int32) optional
Example: 1

The number of seconds after which the check times out.

protocol string, one of: HTTP, HTTP2 optional
Example: HTTP

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).
routes array of object 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 (int32) 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)

grace_period_seconds integer (int32) 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)

static_sites array of object optional

Content which can be rendered to static web assets.

Show child properties
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

build_command string optional
Example: npm run build

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

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.

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.

envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

image object optional
Show child properties
deploy_on_push object optional
Additional nested properties not shown. Refer to the full API spec for details.
digest string optional
Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

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

registry string optional
Example: registry.hub.docker.com

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

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.
registry_type string, one of: DOCKER_HUB, DOCR, GHCR optional
Example: DOCR
  • DOCKER_HUB: The DockerHub container registry type.
  • DOCR: The DigitalOcean container registry type.
  • GHCR: The Github container registry type.
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.

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

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.

cors object optional
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.

index_document string optional
Example: main.html

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

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.

routes array of object 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.

vpc object optional read-only
Show child properties
egress_ips array of object optional
Show child properties
ip string optional
Example: 10.0.0.1
id string optional
Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Show child properties
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

build_command string optional
Example: npm run build

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

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.

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.

envs array of object 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, one of: UNSET, RUN_TIME, BUILD_TIME, RUN_AND_BUILD_TIME optional
Example: BUILD_TIME
  • 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
type string, one of: GENERAL, SECRET optional
Example: GENERAL
  • GENERAL: A plain-text environment variable
  • SECRET: A secret encrypted environment variable
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

image object optional
Show child properties
deploy_on_push object optional
Additional nested properties not shown. Refer to the full API spec for details.
digest string optional
Example: sha256:795e91610e9cccb7bb80893fbabf9c808df7d52ae1f39cd1158618b4a33041ac

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

registry string optional
Example: registry.hub.docker.com

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

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.
registry_type string, one of: DOCKER_HUB, DOCR, GHCR optional
Example: DOCR
  • DOCKER_HUB: The DockerHub container registry type.
  • DOCR: The DigitalOcean container registry type.
  • GHCR: The Github container registry type.
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.

log_destinations array of object optional

A list of configured log forwarding destinations.

Show child properties
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.
name string required
Example: my_log_destination
open_search object optional

OpenSearch configuration.

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

Papertrail configuration.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Show child properties
max_instance_count integer (uint32) optional
Example: 3

The maximum amount of instances for this component. Must be more than min_instance_count.

metrics object optional

The metrics that the component is scaled on.

Additional nested properties not shown. Refer to the full API spec for details.
min_instance_count integer (uint32) optional
Example: 2

The minimum amount of instances for this component. Must be less than max_instance_count.

instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

liveness_health_check object optional
Show child properties
failure_threshold integer (int32) optional
Example: 18

The number of failed health checks before considered unhealthy.

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 (int32) optional
Example: 30

The number of seconds to wait before beginning health checks.

period_seconds integer (int32) optional
Example: 10

The number of seconds to wait between health checks.

port integer (int64) optional
Example: 80

The port on which the health check will be performed.

success_threshold integer (int32) optional
Example: 1

The number of successful health checks before considered healthy.

timeout_seconds integer (int32) optional
Example: 1

The number of seconds after which the check times out.

termination object optional
Show child properties
grace_period_seconds integer (int32) 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)

update_all_source_versions boolean optional
Example: true

Whether or not to update the source versions (for example fetching a new commit or image digest) of all components. By default (when this is false) only newly added sources will be updated to avoid changes like updating the scale of a component from also updating the respective code.

Request: /v2/apps/{id}
Content type application/json 
{
  "spec": {
    "databases": [],
    "disable_edge_cache": false,
    "disable_email_obfuscation": false,
    "domains": [],
    "egress": {
      "type": "AUTOASSIGN"
    },
    "enhanced_threat_control_enabled": false,
    "functions": [],
    "ingress": {
      "rules": []
    },
    "jobs": [],
    "maintenance": {
      "archive": true,
      "enabled": true,
      "offline_page_url": "https://example.com/offline.html"
    },
    "name": "web-app-01",
    "region": "nyc",
    "services": [],
    "static_sites": [],
    "workers": []
  },
  "update_all_source_versions": true
}
curl -X PUT \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
"https://api.digitalocean.com/v2/apps/{id}" \
-d '{"alerts":[{"rule":"DEPLOYMENT_FAILED"},{"rule":"DOMAIN_FAILED"}],"domains":[{"domain":"example.com","type":"PRIMARY","zone":"example.com"}],"envs":[{"key":"API_KEY","scope":"RUN_AND_BUILD_TIME","type":"SECRET","value":"EV[1:zqiRIeaaYK/NqctZDYzy6t0pTrtRDez8:wqGpZRrsKN5nPhWQrS479cfBiXT0WQ==]"}],"features":["buildpack-stack=ubuntu-22"],"ingress":{},"name":"example-app","region":"nyc","services":[{"autoscaling":{"max_instance_count":4,"metrics":{"cpu":{"percent":70}},"min_instance_count":2},"git":{"branch":"main","repo_clone_url":"https://github.com/digitalocean/sample-nodejs.git"},"internal_ports":[8080],"log_destinations":[{"name":"your_log_consumer_name","open_search":{"endpoint":"logs.example.com:12345","basic_auth":{"user":"doadmin","password":"1234567890abcdef"},"index_name":"example-index","cluster_name":"example-cluster"}}],"name":"sample-nodejs","run_command":"yarn start","source_dir":"/"}]}'
import os
from pydo import Client

client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
req = {
"spec": {
    "name": "web-app-01",
    "region": "nyc",
    "domains": [
        {
            "domain": "app.example.com",
            "type": "DEFAULT",
            "wildcard": True,
            "zone": "example.com",
            "minimum_tls_version": "1.3",
        }
    ],
    "services": [],
    "static_sites": [
        {
            "cors": {
                "allow_origins": [
                    {"exact": "https://www.example.com"},
                    {"regex": "^.*example.com"},
                ],
                "allow_methods": [
                    "GET",
                    "OPTIONS",
                    "POST",
                    "PUT",
                    "PATCH",
                    "DELETE",
                ],
                "allow_headers": ["Content-Type", "X-Custom-Header"],
                "expose_headers": ["Content-Encoding", "X-Custom-Header"],
                "max_age": "5h30m",
                "allow_credentials": False,
            },
            "routes": [{"path": "/api", "preserve_path_prefix": True}],
        }
    ],
    "jobs": [
        {
            "name": "api",
            "gitlab": {
                "branch": "main",
                "deploy_on_push": True,
                "repo": "digitalocean/sample-golang",
            },
            "image": {
                "registry": "registry.hub.docker.com",
                "registry_type": "DOCR",
                "repository": "origin/master",
                "tag": "latest",
            },
            "dockerfile_path": "path/to/Dockerfile",
            "build_command": "npm run build",
            "run_command": "bin/api",
            "source_dir": "path/to/dir",
            "envs": [
                {
                    "key": "BASE_URL",
                    "scope": "BUILD_TIME",
                    "type": "GENERAL",
                    "value": "http://example.com",
                }
            ],
            "environment_slug": "node-js",
            "log_destinations": {
                "name": "my_log_destination",
                "papertrail": {
                    "endpoint": "https://mypapertrailendpoint.com"
                },
                "datadog": {
                    "endpoint": "https://mydatadogendpoint.com",
                    "api_key": "abcdefghijklmnopqrstuvwxyz0123456789",
                },
                "logtail": {
                    "token": "abcdefghijklmnopqrstuvwxyz0123456789"
                },
               "open_search": {
                    "endpoint": "https://myopensearchendpoint.com:9300"
                    "index_name": "logs"
                    "basic_auth": {
                        "user": "doadmin",
                        "password": "password"
                    }
                },
            },
            "instance_count": 2,
            "instance_size_slug": "apps-s-1vcpu-0.5gb",
            "kind": "PRE_DEPLOY",
        }
    ],
    "workers": [
        {
            "name": "api",
            "gitlab": {
                "branch": "main",
                "deploy_on_push": True,
                "repo": "digitalocean/sample-golang",
            },
            "image": {
                "registry": "registry.hub.docker.com",
                "registry_type": "DOCR",
                "repository": "origin/master",
                "tag": "latest",
            },
            "dockerfile_path": "path/to/Dockerfile",
            "build_command": "npm run build",
            "run_command": "bin/api",
            "source_dir": "path/to/dir",
            "envs": [
                {
                    "key": "BASE_URL",
                    "scope": "BUILD_TIME",
                    "type": "GENERAL",
                    "value": "http://example.com",
                }
            ],
            "environment_slug": "node-js",
            "log_destinations": {
                "name": "my_log_destination",
                "papertrail": {
                    "endpoint": "https://mypapertrailendpoint.com"
                },
                "datadog": {
                    "endpoint": "https://mydatadogendpoint.com",
                    "api_key": "abcdefghijklmnopqrstuvwxyz0123456789",
                },
                "logtail": {
                    "token": "abcdefghijklmnopqrstuvwxyz0123456789"
                },
               "open_search": {
                    "endpoint": "https://myopensearchendpoint.com:9300"
                    "index_name": "logs"
                    "basic_auth": {
                        "user": "doadmin",
                        "password": "password"
                    }
                },
            },
            "instance_count": 2,
            "instance_size_slug": "apps-s-1vcpu-0.5gb",
        }
    ],
    "functions": [
        {
            "cors": {
                "allow_origins": [
                    {"exact": "https://www.example.com"},
                    {"regex": "^.*example.com"},
                ],
                "allow_methods": [
                    "GET",
                    "OPTIONS",
                    "POST",
                    "PUT",
                    "PATCH",
                    "DELETE",
                ],
                "allow_headers": ["Content-Type", "X-Custom-Header"],
                "expose_headers": ["Content-Encoding", "X-Custom-Header"],
                "max_age": "5h30m",
                "allow_credentials": False,
            },
            "routes": [{"path": "/api", "preserve_path_prefix": True}],
            "name": "api",
            "source_dir": "path/to/dir",
            "alerts": [
                {
                    "rule": "CPU_UTILIZATION",
                    "disabled": False,
                    "operator": "GREATER_THAN",
                    "value": 2.32,
                    "window": "FIVE_MINUTES",
                }
            ],
            "envs": [
                {
                    "key": "BASE_URL",
                    "scope": "BUILD_TIME",
                    "type": "GENERAL",
                    "value": "http://example.com",
                }
            ],
            "gitlab": {
                "branch": "main",
                "deploy_on_push": True,
                "repo": "digitalocean/sample-golang",
            },
            "log_destinations": {
                "name": "my_log_destination",
                "papertrail": {
                    "endpoint": "https://mypapertrailendpoint.com"
                },
                "datadog": {
                    "endpoint": "https://mydatadogendpoint.com",
                    "api_key": "abcdefghijklmnopqrstuvwxyz0123456789",
                },
                "logtail": {
                    "token": "abcdefghijklmnopqrstuvwxyz0123456789"
                },
               "open_search": {
                    "endpoint": "https://myopensearchendpoint.com:9300"
                    "index_name": "logs"
                    "basic_auth": {
                        "user": "doadmin",
                        "password": "password"
                    }
                },
            },
        }
    ],
    "databases": [
        {
            "cluster_name": "cluster_name",
            "db_name": "my_db",
            "db_user": "superuser",
            "engine": "PG",
            "name": "prod-db",
            "production": True,
            "version": "12",
        }
    ],
    “vpc”: {
        “id”: “c22d8f48-4bc4-49f5-8ca0-58e7164427ac”,
    }
}
update_resp = client.apps.update(id="bb245ba", body=req)

Responses

200

A JSON object of the updated app
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
app object optional

An application's configuration and status.

Show child properties
active_deployment object optional
Show child properties
cause string optional
Example: commit 9a4df0b pushed to github/digitalocean/sample-golang
cloned_from string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a
created_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
functions array of object optional
Show child properties
name string optional
Example: my-functions-component
namespace string optional
Example: ap-b2a93513-8d9b-4223-9d61-5e7272c81c32

The namespace where the functions are deployed.

source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405

The commit hash of the repository that was used to build this functions component.

id string optional
Example: b6bdf840-2854-4f87-a36c-5f231c617c84
jobs array of object optional
Show child properties
name string optional
Example: migrate-db
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
phase string (enum) optional
Example: ACTIVE
phase_last_updated_at string (date-time) optional
Example: 0001-01-01T00:00:00Z
progress object optional
Show child properties
error_steps integer (int32) optional
Example: 3
pending_steps integer (int32) optional
Example: 2
running_steps integer (int32) optional
Example: 2
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
success_steps integer (int32) optional
Example: 4
summary_steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
total_steps integer (int32) optional
Example: 5
services array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
spec object optional

The desired configuration of an application.

Show child properties
databases array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

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

domains array of object optional

A set of hostnames where the application will be available.

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

Specification for app egress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
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.

functions array of object optional

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

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

Specification for app ingress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

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

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

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Additional nested properties not shown. Refer to the full API spec for details.
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
workers array of object optional
Show child properties
name string optional
Example: queue-runner
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
created_at string (date-time) optional read-only
Example: 2020-11-19T20:27:18Z
dedicated_ips array of object optional read-only
Show child properties
id string optional
Example: 9e7bc2ac-205a-45d6-919c-e1ac5e73f962
ip string optional
Example: 192.168.1.1
status string, one of: UNKNOWN, ASSIGNING, ASSIGNED, REMOVED optional read-only
Example: ASSIGNED
default_ingress string optional read-only
Example: digitalocean.com
domains array of object optional read-only
Show child properties
certificate_expires_at string (date-time) optional read-only
Example: 2024-01-29T23:59:59Z
id string optional
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf
phase string, one of: UNKNOWN, PENDING, CONFIGURING, ACTIVE, ERROR optional
Example: ACTIVE
progress object optional
Show child properties
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
rotate_validation_records boolean optional read-only
spec object optional
Show child properties
domain string required
Example: app.example.com

The hostname for the domain

minimum_tls_version string, one of: 1.2, 1.3 optional
Example: 1.3

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

type string, one of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS optional
Example: DEFAULT
  • 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
wildcard boolean optional
Example: true

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

zone string (hostname) 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.

validations array of object optional
Show child properties
txt_name string optional read-only
Example: _acme-challenge.app.example.com
txt_value string optional read-only
Example: lXLOcN6cPv0nproViNcUHcahD9TrIPlNgdwesj0pYpk
id string optional read-only
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf
in_progress_deployment object optional
Show child properties
cause string optional
Example: commit 9a4df0b pushed to github/digitalocean/sample-golang
cloned_from string optional
Example: 3aa4d20e-5527-4c00-b496-601fbd22520a
created_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
functions array of object optional
Show child properties
name string optional
Example: my-functions-component
namespace string optional
Example: ap-b2a93513-8d9b-4223-9d61-5e7272c81c32

The namespace where the functions are deployed.

source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405

The commit hash of the repository that was used to build this functions component.

id string optional
Example: b6bdf840-2854-4f87-a36c-5f231c617c84
jobs array of object optional
Show child properties
name string optional
Example: migrate-db
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
phase string (enum) optional
Example: ACTIVE
phase_last_updated_at string (date-time) optional
Example: 0001-01-01T00:00:00Z
progress object optional
Show child properties
error_steps integer (int32) optional
Example: 3
pending_steps integer (int32) optional
Example: 2
running_steps integer (int32) optional
Example: 2
steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
success_steps integer (int32) optional
Example: 4
summary_steps array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
total_steps integer (int32) optional
Example: 5
services array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
spec object optional

The desired configuration of an application.

Show child properties
databases array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

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

domains array of object optional

A set of hostnames where the application will be available.

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

Specification for app egress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
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.

functions array of object optional

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

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

Specification for app ingress configurations.

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

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

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

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Additional nested properties not shown. Refer to the full API spec for details.
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional
Show child properties
name string optional
Example: web
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional
Example: 2020-07-28T18:00:00Z
workers array of object optional
Show child properties
name string optional
Example: queue-runner
source_commit_hash string optional
Example: 54d4a727f457231062439895000d45437c7bb405
last_deployment_created_at string (date-time) optional read-only
Example: 2020-11-19T20:27:18Z
live_domain string optional read-only
Example: live_domain
live_url string optional read-only
Example: google.com
live_url_base string optional read-only
Example: digitalocean.com
owner_uuid string optional read-only
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf
pending_deployment object optional
pinned_deployment object optional
project_id string optional read-only
Example: 88b72d1a-b78a-4d9f-9090-b53c4399073f

Requires project:read scope.

region object optional
Show child properties
continent string optional read-only
Example: europe
data_centers array of string optional read-only
Example: ["ams"]
default boolean optional read-only
Example: true

Whether or not the region is presented as the default.

disabled boolean optional read-only
Example: true
flag string optional read-only
Example: ams
label string optional read-only
Example: ams
reason string optional read-only
Example: to crowded
slug string optional read-only
Example: basic
spec object required

The desired configuration of an application.

Show child properties
databases array of object 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 (enum) optional
Example: PG
  • MYSQL: MySQL
  • PG: PostgreSQL
  • REDIS: Caching
  • MONGODB: MongoDB
  • KAFKA: Kafka
  • OPENSEARCH: OpenSearch
  • VALKEY: ValKey
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.

production boolean optional
Example: true

Whether this is a production or dev database.

version string optional
Example: 12

The version of the database engine

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.

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

domains array of object 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

minimum_tls_version string, one of: 1.2, 1.3 optional
Example: 1.3

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

type string, one of: UNSPECIFIED, DEFAULT, PRIMARY, ALIAS optional
Example: DEFAULT
  • 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
wildcard boolean optional
Example: true

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

zone string (hostname) 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.

egress object optional

Specification for app egress configurations.

Show child properties
type string, one of: AUTOASSIGN, DEDICATED_IP optional
Example: AUTOASSIGN
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.

functions array of object optional

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

Show child properties
alerts array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
cors object optional
envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string required
Example: api

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

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
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.

ingress object optional

Specification for app ingress configurations.

Show child properties
rules array of object optional

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

Additional nested properties not shown. Refer to the full API spec for details.
jobs array of object optional

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

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

kind string, one of: UNSPECIFIED, PRE_DEPLOY, POST_DEPLOY, FAILED_DEPLOY optional
Example: PRE_DEPLOY
  • 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.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
maintenance object optional

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

Show child properties
archive boolean optional
Example: true

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

enabled boolean optional
Example: true

Indicates whether maintenance mode should be enabled for the app.

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.

name string required
Example: web-app-01

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

region string (enum) optional
Example: nyc

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

services array of object optional

Workloads which expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

cors object optional
health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
http_port integer (int64) 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.

internal_ports array of integer (int64) optional
Example: [80,443]

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

Additional nested properties not shown. Refer to the full API spec for details.
liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
protocol string, one of: HTTP, HTTP2 optional
Example: HTTP

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).
routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
static_sites array of object optional

Content which can be rendered to static web assets.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

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.

cors object optional
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.

index_document string optional
Example: main.html

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

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.

routes array of object optional Deprecated

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

Additional nested properties not shown. Refer to the full API spec for details.
vpc object optional read-only
Show child properties
egress_ips array of object optional
Additional nested properties not shown. Refer to the full API spec for details.
id string optional
Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac
workers array of object optional

Workloads which do not expose publicly-accessible HTTP services.

Show child properties
bitbucket object optional
Additional nested properties not shown. Refer to the full API spec for details.
build_command string optional
Example: npm run build

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

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.

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.

envs array of object optional

A list of environment variables made available to the component.

Additional nested properties not shown. Refer to the full API spec for details.
git object optional
Additional nested properties not shown. Refer to the full API spec for details.
github object optional
Additional nested properties not shown. Refer to the full API spec for details.
gitlab object optional
Additional nested properties not shown. Refer to the full API spec for details.
image object optional
Additional nested properties not shown. Refer to the full API spec for details.
log_destinations array of object optional

A list of configured log forwarding destinations.

Additional nested properties not shown. Refer to the full API spec for details.
name string optional
Example: api

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

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.

autoscaling object optional

Configuration for automatically scaling this component based on metrics.

Additional nested properties not shown. Refer to the full API spec for details.
instance_count integer (int64) optional
Example: 2

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

instance_size_slug string (enum, 24 values) optional
Example: apps-s-1vcpu-0.5gb

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

liveness_health_check object optional
Additional nested properties not shown. Refer to the full API spec for details.
termination object optional
Additional nested properties not shown. Refer to the full API spec for details.
tier_slug string optional read-only
Example: basic
updated_at string (date-time) optional read-only
Example: 2020-12-01T00:42:16Z
vpc object optional read-only
Show child properties
egress_ips array of object optional
Show child properties
ip string optional
Example: 10.0.0.1
id string optional
Example: c22d8f48-4bc4-49f5-8ca0-58e7164427ac
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "app": {
    "active_deployment": {
      "cause": "manual",
      "created_at": "2021-02-10T17:05:30Z",
      "id": "991dfa59-6a23-459f-86d6-67dfa2c6f1e3",
      "phase": "ACTIVE",
      "phase_last_updated_at": "2021-02-10T17:06:53Z",
      "progress": {
        "steps": [
          {
            "ended_at": "2021-02-10T17:06:19.807834070Z",
            "name": "build",
            "started_at": "2021-02-10T17:05:35.572287990Z",
            "status": "SUCCESS",
            "steps": [
              {
                "ended_at": "2021-02-10T17:05:36.093995229Z",
                "name": "initialize",
                "started_at": "2021-02-10T17:05:35.572347485Z",
                "status": "SUCCESS"
              },
              {
                "ended_at": "2021-02-10T17:06:19.461737040Z",
                "name": "components",
                "started_at": "2021-02-10T17:05:36.094015928Z",
                "status": "SUCCESS",
                "steps": [
                  {
                    "component_name": "web",
                    "message_base": "Building service",
                    "name": "web",
                    "status": "SUCCESS"
                  }
                ]
              }
            ]
          },
          {
            "ended_at": "2021-02-10T17:06:53.404104185Z",
            "name": "deploy",
            "started_at": "2021-02-10T17:06:25.143932418Z",
            "status": "SUCCESS",
            "steps": [
              {
                "ended_at": "2021-02-10T17:06:26.120343872Z",
                "name": "initialize",
                "started_at": "2021-02-10T17:06:25.143957508Z",
                "status": "SUCCESS"
              },
              {
                "ended_at": "2021-02-10T17:06:50.029695913Z",
                "name": "components",
                "started_at": "2021-02-10T17:06:26.120385561Z",
                "status": "SUCCESS",
                "steps": [
                  {
                    "component_name": "web",
                    "name": "web",
                    "status": "SUCCESS",
                    "steps": [
                      {
                        "component_name": "web",
                        "message_base": "Deploying service",
                        "name": "deploy",
                        "status": "SUCCESS"
                      },
                      {
                        "component_name": "web",
                        "message_base": "Waiting for service",
                        "name": "wait",
                        "status": "SUCCESS"
                      }
                    ]
                  }
                ]
              },
              {
                "ended_at": "2021-02-10T17:06:53.404065961Z",
                "name": "finalize",
                "started_at": "2021-02-10T17:06:50.348459495Z",
                "status": "SUCCESS"
              }
            ]
          }
        ],
        "success_steps": 6,
        "total_steps": 6
      },
      "services": [
        {
          "name": "web",
          "source_commit_hash": "db6936cb46047c576962962eed81ad52c21f35d7"
        }
      ],
      "spec": {
        "domains": [
          {
            "domain": "sample-golang.example.com",
            "minimum_tls_version": "1.3",
            "zone": "example.com"
          }
        ],
        "name": "sample-golang",
        "region": "ams",
        "services": [
          {
            "environment_slug": "go",
            "github": {
              "branch": "main",
              "repo": "ChiefMateStarbuck/sample-golang"
            },
            "http_port": 8080,
            "instance_count": 1,
            "instance_size_slug": "apps-s-1vcpu-0.5gb",
            "name": "web",
            "routes": [
              {
                "path": "/"
              }
            ],
            "run_command": "bin/sample-golang"
          }
        ],
        "vpc": {
          "egress_ips": [
            {
              "ip": "10.0.0.1"
            }
          ],
          "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac"
        }
      },
      "tier_slug": "basic",
      "updated_at": "2021-02-10T17:06:53Z"
    },
    "created_at": "2021-02-10T16:45:14Z",
    "dedicated_ips": [
      {
        "id": "c24d8f48-3bc4-49f5-8ca0-58e8164427ac",
        "ip": "192.168.1.1",
        "status": "ASSIGNED"
      },
      {
        "id": "4768fb15-2837-4dda-9be5-3951df4bc3d0",
        "ip": "192.168.1.2",
        "status": "ASSIGNED"
      }
    ],
    "default_ingress": "https://sample-golang-zyhgn.ondigitalocean.app",
    "domains": [
      {
        "certificate_expires_at": "2024-01-29T23:59:59Z",
        "id": "e206c64e-a1a3-11ed-9e6e-9b7b6dc9a52b",
        "phase": "CONFIGURING",
        "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"
            }
          ]
        },
        "rotate_validation_records": false,
        "spec": {
          "domain": "sample-golang.example.com",
          "minimum_tls_version": "1.3",
          "type": "PRIMARY",
          "zone": "example.com"
        }
      }
    ],
    "id": "c2a93513-8d9b-4223-9d61-5e7272c81cf5",
    "last_deployment_created_at": "2021-02-10T17:05:30Z",
    "live_domain": "sample-golang-zyhgn.ondigitalocean.app",
    "live_url": "https://sample-golang-zyhgn.ondigitalocean.app",
    "live_url_base": "https://sample-golang-zyhgn.ondigitalocean.app",
    "owner_uuid": "a4e16f25-cdd1-4483-b246-d77f283c9209",
    "pending_deployment": {
      "id": "3aa4d20e-5527-4c00-b496-601fbd22520a",
      "spec": {
        "domains": [
          {
            "domain": "sample-php.example.com",
            "minimum_tls_version": "1.3",
            "type": "PRIMARY",
            "zone": "example.com"
          }
        ],
        "name": "sample-php",
        "region": "fra",
        "services": [
          {
            "environment_slug": "php",
            "git": {
              "branch": "main",
              "repo_clone_url": "https://github.com/digitalocean/sample-php.git"
            },
            "http_port": 8080,
            "instance_count": 1,
            "instance_size_slug": "apps-s-1vcpu-0.5gb",
            "name": "sample-php",
            "routes": [
              {
                "path": "/"
              }
            ],
            "run_command": "heroku-php-apache2"
          }
        ],
        "vpc": {
          "egress_ips": [
            {
              "ip": "10.0.0.1"
            }
          ],
          "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac"
        }
      }
    },
    "project_id": "88b72d1a-b78a-4d9f-9090-b53c4399073f",
    "region": {
      "continent": "Europe",
      "data_centers": [
        "ams3"
      ],
      "flag": "netherlands",
      "label": "Amsterdam",
      "slug": "ams"
    },
    "spec": {
      "disable_edge_cache": true,
      "domains": [
        {
          "domain": "sample-golang.example.com",
          "minimum_tls_version": "1.3",
          "zone": "example.com"
        }
      ],
      "enhanced_threat_control_enabled": true,
      "name": "sample-golang",
      "region": "ams",
      "services": [
        {
          "environment_slug": "go",
          "github": {
            "branch": "main",
            "repo": "ChiefMateStarbuck/sample-golang"
          },
          "http_port": 8080,
          "instance_count": 1,
          "instance_size_slug": "apps-s-1vcpu-0.5gb",
          "name": "web",
          "routes": [
            {
              "path": "/"
            }
          ],
          "run_command": "bin/sample-golang"
        }
      ],
      "vpc": {
        "egress_ips": [
          {
            "ip": "10.0.0.1"
          }
        ],
        "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac"
      }
    },
    "tier_slug": "basic",
    "updated_at": "2021-02-10T17:06:56Z",
    "vpc": {
      "egress_ips": [
        {
          "ip": "10.0.0.1"
        }
      ],
      "id": "c22d8f48-4bc4-49f5-8ca0-58e7164427ac"
    }
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete an App

/v2/apps/{id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: app:delete

OAuth Authentication

In order to interact with the DigitalOcean API, you or your application must authenticate.

The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints.

You can generate an OAuth token by visiting the Apps & API section of the DigitalOcean control panel for your account.

An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair.

Because of this, it is absolutely essential that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised.

DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens.

  • dop_v1_ for personal access tokens generated in the control panel
  • doo_v1_ for tokens generated by applications using the OAuth flow
  • dor_v1_ for OAuth refresh tokens

Scopes

Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes.

Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete).

HTTP Verb CRUD Operation Scope
GET Read <resource>:read
POST Create <resource>:create
PUT/PATCH Update <resource>:update
DELETE Delete <resource>:delete

For example, creating a new Droplet by making a POST request to the /v2/droplets endpoint requires the droplet:create scope while listing Droplets by making a GET request to the /v2/droplets endpoint requires the droplet:read scope.

Each endpoint below specifies which scope is required to access it when using custom scopes.

How to Authenticate with OAuth

In order to make an authenticated request, include a bearer-type Authorization header containing your OAuth token. All requests must be made over HTTPS.

Authenticate with a Bearer Authorization Header

curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT"

Delete an existing app. Once deleted, all active deployments will be permanently shut down and the app deleted. If needed, be sure to back up your app specification so that you may re-create it at a later time.

Path Parameters

id string required
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf

The ID of the app

Request: /v2/apps/{id}
curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/apps/{id}"
import os
from pydo import Client

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

delete_resp = client.apps.delete(id="b7d64052")

Responses

200

the ID of the app deleted.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string optional
Example: 4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The resource was not found.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "id": "b7d64052-3706-4cb7-b21a-c5a2f44e63b3"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

We can't find any results for your search.

Try using different keywords or simplifying your search terms.