Droplets
Generated on 20 Mar 2026
A Droplet is a DigitalOcean virtual machine. By sending requests to the Droplet endpoint, you can list, create, or delete Droplets.
Some of the attributes will have an object value. The region and image
objects will all contain the standard attributes of their associated
types. Find more information about each of these objects in their
respective sections.
https://api.digitalocean.com
Endpoints
GET List All Droplets
/v2/droplets
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 list all Droplets in your account, send a GET request to /v2/droplets.
The response body will be a JSON object with a key of droplets. This will be
set to an array containing objects each representing a Droplet. These will
contain the standard Droplet attributes.
Filtering Results by Tag
It's possible to request filtered results by including certain query parameters.
To only list Droplets assigned to a specific tag, include the tag_name query
parameter set to the name of the tag in your GET request. For example,
/v2/droplets?tag_name=$TAG_NAME.
GPU Droplets
By default, only non-GPU Droplets are returned. To list only GPU Droplets, set
the type query parameter to gpus. For example, /v2/droplets?type=gpus.
Query Parameters
per_page
1 – 200 optional
2Number of items returned per page
Default:20page
>= 1 optional
1Which 'page' of paginated results to return.
Default:1tag_name
optional
env:prodUsed to filter Droplets by a specific tag. Can not be combined with name or type.
Requires tag:read scope.
name
optional
web-01Used to filter list response by Droplet name returning only exact matches. It is case-insensitive and can not be combined with tag_name.
type
optional
dropletsWhen type is set to gpus, only GPU Droplets will be returned. By default, only non-GPU Droplets are returned. Can not be combined with tag_name.
Request: /v2/droplets
curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
"https://api.digitalocean.com/v2/droplets?page=1&per_page=1"import (
"context"
"os"
"github.com/digitalocean/godo"
)
func main() {
token := os.Getenv("DIGITALOCEAN_TOKEN")
client := godo.NewFromToken(token)
ctx := context.TODO()
opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
droplets, _, err := client.Droplets.List(ctx, opt)
}require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)
droplets = client.droplets.all
droplets.eachimport os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.droplets.list()Responses
200
A JSON object with a key of droplets.
droplets.ratelimit-limit
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
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
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.
application/json
droplets
optional
Show child properties
backup_ids
required
[53893572]An array of backup IDs of any backups that have been taken of the Droplet instance. Droplet backups are enabled at the time of the instance creation.
Requires image:read scope.
created_at
required
2020-07-21T18:37:44ZA time value given in ISO8601 combined date and time format that represents when the Droplet was created.
disk
required
25The size of the Droplet's disk in gigabytes.
disk_info
optional
An array of objects containing information about the disks available to the Droplet.
Show child properties
size
optional
Show child properties
amount
optional
25The amount of space allocated to the disk.
unit
optional
gibThe unit of measure for the disk size.
type
optional
localThe type of disk. All Droplets contain a local disk. Additionally, GPU Droplets can also have a scratch disk for non-persistent data.
features
required
["backups","private_networking","ipv6"]An array of features enabled on this Droplet.
gpu_info
optional
An object containing information about the GPU capabilities of Droplets created with this size.
Show child properties
count
optional
1The number of GPUs allocated to the Droplet.
model
optional
nvidia_h100The model of the GPU.
vram
optional
Show child properties
amount
optional
25The amount of VRAM allocated to the GPU.
unit
optional
gibThe unit of measure for the VRAM.
id
required
3164444A unique identifier for each Droplet instance. This is automatically generated upon Droplet creation.
image
required
kernel
optional Deprecated Nullable
Note: All Droplets created after March 2017 use internal kernels by default.
These Droplets will have this attribute set to null.
The current kernel for Droplets with externally managed kernels. This will initially be set to the kernel of the base image when the Droplet is created.
Show child properties
id
optional
7515A unique number used to identify and reference a specific kernel.
name
optional
DigitalOcean GrubLoader v0.2 (20160714)The display name of the kernel. This is shown in the web UI and is generally a descriptive title for the kernel in question.
version
optional
2016.07.13-DigitalOcean_loader_UbuntuA standard kernel version string representing the version, patch, and release information.
locked
required
falseA boolean value indicating whether the Droplet has been locked, preventing actions by users.
memory
required
1024Memory of the Droplet in megabytes.
name
required
example.comThe human-readable name set for the Droplet instance.
networks
required
The details of the network that are configured for the Droplet instance. This is an object that contains keys for IPv4 and IPv6. The value of each of these is an array that contains objects describing an individual IP resource allocated to the Droplet. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is.
Show child properties
v4
optional
Show child properties
gateway
optional
104.236.0.1The gateway of the specified IPv4 network interface.
For private interfaces, a gateway is not provided. This is denoted by
returning nil as its value.
ip_address
optional
104.236.32.182The IP address of the IPv4 network interface.
netmask
optional
255.255.192.0The netmask of the IPv4 network interface.
type
optional
publicThe type of the IPv4 network interface.
v6
optional
Show child properties
gateway
optional
2604:a880:0:1010::1The gateway of the specified IPv6 network interface.
ip_address
optional
2604:a880:0:1010::18a:a001The IP address of the IPv6 network interface.
netmask
optional
64The netmask of the IPv6 network interface.
type
optional
publicThe type of the IPv6 network interface.
Note: IPv6 private networking is not currently supported.
next_backup_window
required
region
required
Show child properties
available
required
trueThis is a boolean value that represents whether new Droplets can be created in this region.
features
required
["private_networking","backups","ipv6","metadata","install_agent","storage","image_transfer"]This attribute is set to an array which contains features available in this region
name
required
New York 3The display name of the region. This will be a full name that is used in the control panel and other interfaces.
sizes
required
This attribute is set to an array which contains the identifying slugs for the sizes available in this region. sizes:read is required to view.
slug
required
nyc3A human-readable string that is used as a unique identifier for each region.
size
required
Show child properties
available
required
trueThis is a boolean value that represents whether new Droplets can be created with this size.
description
required
BasicA string describing the class of Droplets created from this size. For example: Basic, General Purpose, CPU-Optimized, Memory-Optimized, or Storage-Optimized.
disk
required
25The amount of disk space set aside for Droplets of this size. The value is represented in gigabytes.
disk_info
optional
An array of objects containing information about the disks available to Droplets created with this size.
Show child properties
size
optional
type
optional
localThe type of disk. All Droplets contain a local disk. Additionally, GPU Droplets can also have a scratch disk for non-persistent data.
gpu_info
optional
An object containing information about the GPU capabilities of Droplets created with this size.
Show child properties
count
optional
1The number of GPUs allocated to the Droplet.
model
optional
nvidia_h100The model of the GPU.
vram
optional
memory
required
1024The amount of RAM allocated to Droplets created of this size. The value is represented in megabytes.
price_hourly
required
0.00743999984115362This describes the price of the Droplet size as measured hourly. The value is measured in US dollars.
price_monthly
required
5This attribute describes the monthly cost of this Droplet size if the Droplet is kept for an entire month. The value is measured in US dollars.
regions
required
["ams2","ams3","blr1","fra1","lon1","nyc1","nyc2","nyc3","sfo1","sfo2","sfo3","sgp1","tor1"]An array containing the region slugs where this size is available for Droplet creates.
slug
required
s-1vcpu-1gbA human-readable string that is used to uniquely identify each size.
transfer
required
1The amount of transfer bandwidth that is available for Droplets created in this size. This only counts traffic on the public interface. The value is given in terabytes.
vcpus
required
1The number of CPUs allocated to Droplets of this size.
size_slug
required
s-1vcpu-1gbThe unique slug identifier for the size of this Droplet.
snapshot_ids
required
[67512819]An array of snapshot IDs of any snapshots created from the Droplet instance.
Requires image:read scope.
status
required
activeA status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive".
tags
required
["web","env:prod"]An array of Tags the Droplet has been tagged with.
Requires tag:read scope.
vcpus
required
1The number of virtual CPUs.
volume_ids
required
["506f78a4-e098-11e5-ad9f-000f53306ae1"]A flat array including the unique identifier for each Block Storage volume attached to the Droplet.
Requires block_storage:read scope.
vpc_uuid
optional
760e09ef-dc84-11e8-981e-3cfdfeaae000A string specifying the UUID of the VPC to which the Droplet is assigned.
Requires vpc:read scope.
links
optional
Show child properties
pages
optional
Forward Links
last
optional
https://api.digitalocean.com/v2/images?page=2URI of the last page of the results.
next
optional
https://api.digitalocean.com/v2/images?page=2URI of the next page of the results.
Backward Links
first
optional
https://api.digitalocean.com/v2/images?page=1URI of the first page of the results.
prev
optional
https://api.digitalocean.com/v2/images?page=1URI of the previous page of the results.
meta
required
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"droplets": [
{
"backup_ids": [
53893572
],
"created_at": "2020-07-21T18:37:44Z",
"disk": 25,
"disk_info": [
{
"size": {
"amount": 25,
"unit": "gib"
},
"type": "local"
}
],
"features": [
"backups",
"private_networking",
"ipv6"
],
"id": 3164444,
"image": {
"created_at": "2020-05-15T05:47:50Z",
"description": "",
"distribution": "Ubuntu",
"error_message": "",
"id": 63663980,
"min_disk_size": 20,
"name": "20.04 (LTS) x64",
"public": true,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sfo3",
"sgp1",
"tor1"
],
"size_gigabytes": 2.36,
"slug": "ubuntu-20-04-x64",
"status": "available",
"tags": [],
"type": "snapshot"
},
"kernel": null,
"locked": false,
"memory": 1024,
"name": "example.com",
"networks": {
"v4": [
{
"gateway": "nil",
"ip_address": "10.128.192.124",
"netmask": "255.255.0.0",
"type": "private"
},
{
"gateway": "192.241.165.1",
"ip_address": "192.241.165.154",
"netmask": "255.255.255.0",
"type": "public"
}
],
"v6": [
{
"gateway": "2604:a880:0:1010::1",
"ip_address": "2604:a880:0:1010::18a:a001",
"netmask": 64,
"type": "public"
}
]
},
"next_backup_window": {
"end": "2020-07-30T23:00:00Z",
"start": "2020-07-30T00:00:00Z"
},
"region": {
"available": true,
"features": [
"private_networking",
"backups",
"ipv6",
"metadata",
"install_agent",
"storage",
"image_transfer"
],
"name": "New York 3",
"sizes": [
"s-1vcpu-1gb",
"s-1vcpu-2gb",
"s-1vcpu-3gb",
"s-2vcpu-2gb",
"s-3vcpu-1gb",
"s-2vcpu-4gb",
"s-4vcpu-8gb",
"s-6vcpu-16gb",
"s-8vcpu-32gb",
"s-12vcpu-48gb",
"s-16vcpu-64gb",
"s-20vcpu-96gb",
"s-24vcpu-128gb",
"s-32vcpu-192g"
],
"slug": "nyc3"
},
"size": {
"available": true,
"description": "Basic",
"disk": 25,
"memory": 1024,
"price_hourly": 0.00743999984115362,
"price_monthly": 5,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sfo3",
"sgp1",
"tor1"
],
"slug": "s-1vcpu-1gb",
"transfer": 1,
"vcpus": 1
},
"size_slug": "s-1vcpu-1gb",
"snapshot_ids": [
67512819
],
"status": "active",
"tags": [
"web",
"env:prod"
],
"vcpus": 1,
"volume_ids": [],
"vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000"
},
{
"backup_ids": [],
"created_at": "2020-07-21T18:42:27Z",
"disk": 25,
"disk_info": [
{
"size": {
"amount": 25,
"unit": "gib"
},
"type": "local"
}
],
"features": [
"private_networking"
],
"id": 3164459,
"image": {
"created_at": "2020-05-15T05:47:50Z",
"description": "",
"distribution": "Ubuntu",
"error_message": "",
"id": 63663980,
"min_disk_size": 20,
"name": "20.04 (LTS) x64",
"public": true,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sfo3",
"sgp1",
"tor1"
],
"size_gigabytes": 2.36,
"slug": "ubuntu-20-04-x64",
"status": "available",
"tags": [],
"type": "snapshot"
},
"kernel": null,
"locked": false,
"memory": 1024,
"name": "assets.example.com",
"networks": {
"v4": [
{
"gateway": "nil",
"ip_address": "10.128.192.138",
"netmask": "255.255.0.0",
"type": "private"
},
{
"gateway": "162.243.0.1",
"ip_address": "162.243.0.4",
"netmask": "255.255.255.0",
"type": "public"
}
],
"v6": []
},
"next_backup_window": {
"end": "2020-07-30T23:00:00Z",
"start": "2020-07-30T00:00:00Z"
},
"region": {
"available": true,
"features": [
"private_networking",
"backups",
"ipv6",
"metadata",
"install_agent",
"storage",
"image_transfer"
],
"name": "New York 3",
"sizes": [
"s-1vcpu-1gb",
"s-1vcpu-2gb",
"s-1vcpu-3gb",
"s-2vcpu-2gb",
"s-3vcpu-1gb",
"s-2vcpu-4gb",
"s-4vcpu-8gb",
"s-6vcpu-16gb",
"s-8vcpu-32gb",
"s-12vcpu-48gb",
"s-16vcpu-64gb",
"s-20vcpu-96gb",
"s-24vcpu-128gb",
"s-32vcpu-192g"
],
"slug": "nyc3"
},
"size": {
"available": true,
"description": "Basic",
"disk": 25,
"memory": 1024,
"price_hourly": 0.00743999984115362,
"price_monthly": 5,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sfo3",
"sgp1",
"tor1"
],
"slug": "s-1vcpu-1gb",
"transfer": 1,
"vcpus": 1
},
"size_slug": "s-1vcpu-1gb",
"snapshot_ids": [],
"status": "active",
"tags": [
"storage",
"env:prod"
],
"vcpus": 1,
"volume_ids": [
"506f78a4-e098-11e5-ad9f-000f53306ae1"
],
"vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000"
},
{
"backup_ids": [],
"created_at": "2020-07-21T18:32:55Z",
"disk": 25,
"disk_info": [
{
"size": {
"amount": 25,
"unit": "gib"
},
"type": "local"
}
],
"features": [
"private_networking"
],
"id": 3164412,
"image": {
"created_at": "2020-05-15T05:47:50Z",
"description": "",
"distribution": "Ubuntu",
"error_message": "",
"id": 63663980,
"min_disk_size": 20,
"name": "20.04 (LTS) x64",
"public": true,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sfo3",
"sgp1",
"tor1"
],
"size_gigabytes": 2.36,
"slug": "ubuntu-20-04-x64",
"status": "available",
"tags": [],
"type": "snapshot"
},
"kernel": null,
"locked": false,
"memory": 1024,
"name": "stage.example.com",
"networks": {
"v4": [
{
"gateway": "nil",
"ip_address": "10.128.192.125",
"netmask": "255.255.0.0",
"type": "private"
},
{
"gateway": "192.241.247.1",
"ip_address": "192.241.247.248",
"netmask": "255.255.255.0",
"type": "public"
}
],
"v6": []
},
"next_backup_window": {
"end": "2020-07-30T23:00:00Z",
"start": "2020-07-30T00:00:00Z"
},
"region": {
"available": true,
"features": [
"private_networking",
"backups",
"ipv6",
"metadata",
"install_agent",
"storage",
"image_transfer"
],
"name": "New York 3",
"sizes": [
"s-1vcpu-1gb",
"s-1vcpu-2gb",
"s-1vcpu-3gb",
"s-2vcpu-2gb",
"s-3vcpu-1gb",
"s-2vcpu-4gb",
"s-4vcpu-8gb",
"s-6vcpu-16gb",
"s-8vcpu-32gb",
"s-12vcpu-48gb",
"s-16vcpu-64gb",
"s-20vcpu-96gb",
"s-24vcpu-128gb",
"s-32vcpu-192g"
],
"slug": "nyc3"
},
"size": {
"available": true,
"description": "Basic",
"disk": 25,
"memory": 1024,
"price_hourly": 0.00743999984115362,
"price_monthly": 5,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sfo3",
"sgp1",
"tor1"
],
"slug": "s-1vcpu-1gb",
"transfer": 1,
"vcpus": 1
},
"size_slug": "s-1vcpu-1gb",
"snapshot_ids": [],
"status": "active",
"tags": [
"env:stage"
],
"vcpus": 1,
"volume_ids": [
"7724db7c-e098-11e5-b522-000f53304e51"
],
"vpc_uuid": "5a4981aa-9653-4bd1-bef5-d6bff52042e4"
}
],
"links": {
"pages": {}
},
"meta": {
"total": 3
}
}{
"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 Droplet
/v2/droplets
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 create a new Droplet, send a POST request to /v2/droplets setting the
required attributes.
A Droplet will be created using the provided information. The response body
will contain a JSON object with a key called droplet. The value will be an
object containing the standard attributes for your new Droplet. The response
code, 202 Accepted, does not indicate the success or failure of the operation,
just that the request has been accepted for processing. The actions returned
as part of the response's links object can be used to check the status
of the Droplet create event.
Create Multiple Droplets
Creating multiple Droplets is very similar to creating a single Droplet.
Instead of sending name as a string, send names as an array of strings. A
Droplet will be created for each name you send using the associated
information. Up to ten Droplets may be created this way at a time.
Rather than returning a single Droplet, the response body will contain a JSON
array with a key called droplets. This will be set to an array of JSON
objects, each of which will contain the standard Droplet attributes. The
response code, 202 Accepted, does not indicate the success or failure of any
operation, just that the request has been accepted for processing. The array
of actions returned as part of the response's links object can be used to
check the status of each individual Droplet create event.
Request Body: application/json
name
required
example.comThe human-readable string you wish to use when displaying the Droplet name. The name, if set to a domain name managed in the DigitalOcean DNS management system, will configure a PTR record for the Droplet. The name set during creation will also determine the hostname for the Droplet in its internal configuration.
backup_policy
optional
backups
optional
trueA boolean indicating whether automated backups should be enabled for the Droplet.
image
required
ubuntu-20-04-x64The image ID of a public or private image or the slug identifier for a public image. This image will be the base image for your Droplet.
Requires image:read scope.
ipv6
optional
trueA boolean indicating whether to enable IPv6 on the Droplet.
monitoring
optional
trueA boolean indicating whether to install the DigitalOcean agent for monitoring.
private_networking
optional Deprecated
trueThis parameter has been deprecated. Use vpc_uuid instead to specify a VPC network for the Droplet. If no vpc_uuid is provided, the Droplet will be placed in your account's default VPC for the region.
region
optional
nyc3The slug identifier for the region that you wish to deploy the Droplet in. If the specific datacenter is not not important, a slug prefix (e.g. nyc) can be used to deploy the Droplet in any of the that region's locations (nyc1, nyc2, or nyc3). If the region is omitted from the create request completely, the Droplet may deploy in any region.
size
required
s-1vcpu-1gbThe slug identifier for the size that you wish to select for this Droplet.
ssh_keys
optional
[289794,"3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"]An array containing the IDs or fingerprints of the SSH keys that you wish to embed in the Droplet's root account upon creation. You must add the keys to your team before they can be embedded on a Droplet.
Requires ssh_key:read scope.
tags
optional Nullable
["env:prod","web"]A flat array of tag names as strings to apply to the Droplet after it is created. Tag names can either be existing or new tags.
Requires tag:create scope.
user_data
optional
A string containing 'user data' which may be used to configure the Droplet on first boot, often a 'cloud-config' file or Bash script. It must be plain text and may not exceed 64 KiB in size.
volumes
optional
["12e97116-7280-11ed-b3d0-0a58ac146812"]An array of IDs for block storage volumes that will be attached to the Droplet once created. The volumes must not already be attached to an existing Droplet.
Requires block_storage:read scpoe.
vpc_uuid
optional
760e09ef-dc84-11e8-981e-3cfdfeaae000A string specifying the UUID of the VPC to which the Droplet will be assigned. If excluded, the Droplet will be assigned to your account's default VPC for the region.
Requires vpc:read scope.
with_droplet_agent
optional
trueA boolean indicating whether to install the DigitalOcean agent used for providing access to the Droplet web console in the control panel. By default, the agent is installed on new Droplets but installation errors (i.e. OS not supported) are ignored. To prevent it from being installed, set to false. To make installation errors fatal, explicitly set it to true.
names
required
["sub-01.example.com","sub-02.example.com"]An array of human human-readable strings you wish to use when displaying the Droplet name. Each name, if set to a domain name managed in the DigitalOcean DNS management system, will configure a PTR record for the Droplet. Each name set during creation will also determine the hostname for the Droplet in its internal configuration.
backup_policy
optional
backups
optional
trueA boolean indicating whether automated backups should be enabled for the Droplet.
image
required
ubuntu-20-04-x64The image ID of a public or private image or the slug identifier for a public image. This image will be the base image for your Droplet.
Requires image:read scope.
ipv6
optional
trueA boolean indicating whether to enable IPv6 on the Droplet.
monitoring
optional
trueA boolean indicating whether to install the DigitalOcean agent for monitoring.
private_networking
optional Deprecated
trueThis parameter has been deprecated. Use vpc_uuid instead to specify a VPC network for the Droplet. If no vpc_uuid is provided, the Droplet will be placed in your account's default VPC for the region.
region
optional
nyc3The slug identifier for the region that you wish to deploy the Droplet in. If the specific datacenter is not not important, a slug prefix (e.g. nyc) can be used to deploy the Droplet in any of the that region's locations (nyc1, nyc2, or nyc3). If the region is omitted from the create request completely, the Droplet may deploy in any region.
size
required
s-1vcpu-1gbThe slug identifier for the size that you wish to select for this Droplet.
ssh_keys
optional
[289794,"3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"]An array containing the IDs or fingerprints of the SSH keys that you wish to embed in the Droplet's root account upon creation. You must add the keys to your team before they can be embedded on a Droplet.
Requires ssh_key:read scope.
tags
optional Nullable
["env:prod","web"]A flat array of tag names as strings to apply to the Droplet after it is created. Tag names can either be existing or new tags.
Requires tag:create scope.
user_data
optional
A string containing 'user data' which may be used to configure the Droplet on first boot, often a 'cloud-config' file or Bash script. It must be plain text and may not exceed 64 KiB in size.
volumes
optional
["12e97116-7280-11ed-b3d0-0a58ac146812"]An array of IDs for block storage volumes that will be attached to the Droplet once created. The volumes must not already be attached to an existing Droplet.
Requires block_storage:read scpoe.
vpc_uuid
optional
760e09ef-dc84-11e8-981e-3cfdfeaae000A string specifying the UUID of the VPC to which the Droplet will be assigned. If excluded, the Droplet will be assigned to your account's default VPC for the region.
Requires vpc:read scope.
with_droplet_agent
optional
trueA boolean indicating whether to install the DigitalOcean agent used for providing access to the Droplet web console in the control panel. By default, the agent is installed on new Droplets but installation errors (i.e. OS not supported) are ignored. To prevent it from being installed, set to false. To make installation errors fatal, explicitly set it to true.
Request: /v2/droplets
{
"backups": true,
"image": "ubuntu-20-04-x64",
"ipv6": true,
"monitoring": true,
"name": "example.com",
"region": "nyc3",
"size": "s-1vcpu-1gb",
"ssh_keys": [
289794,
"3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"
],
"tags": [
"env:prod",
"web"
],
"user_data": "#cloud-config\nruncmd:\n - touch /test.txt\n",
"vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000"
}curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
-d '{"name":"example.com","region":"nyc3","size":"s-1vcpu-1gb","image":"ubuntu-20-04-x64","ssh_keys":[289794,"3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"],"backups":true,"ipv6":true,"monitoring":true,"tags":["env:prod","web"],"user_data":"#cloud-config\nruncmd:\n - touch /test.txt\n","vpc_uuid":"760e09ef-dc84-11e8-981e-3cfdfeaae000"}' \
"https://api.digitalocean.com/v2/droplets"import (
"context"
"os"
"github.com/digitalocean/godo"
)
func main() {
token := os.Getenv("DIGITALOCEAN_TOKEN")
client := godo.NewFromToken(token)
ctx := context.TODO()
createRequest := &godo.DropletCreateRequest{
Name: "example.com",
Region: "nyc3",
Size: "s-1vcpu-1gb",
Image: godo.DropletCreateImage{
Slug: "ubuntu-20-04-x64",
},
SSHKeys: []godo.DropletCreateSSHKey{
godo.DropletCreateSSHKey{ID: 289794},
godo.DropletCreateSSHKey{Fingerprint: "3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"}
},
Backups: true,
IPv6: true,
Monitoring: true,
Tags: []string{"env:prod","web"},
UserData: "#cloud-config\nruncmd:\n - touch /test.txt\n",
VPCUUID: "760e09ef-dc84-11e8-981e-3cfdfeaae000",
}require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)
droplet = DropletKit::Droplet.new(
name: 'example.com',
region: 'nyc3',
size: 's-1vcpu-1gb',
image: 'ubuntu-20-04-x64',
ssh_keys: [289794,"3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"],
backups: true,
ipv6: true,
monitoring: true,
tags: ["env:prod","web"],
user_data: "#cloud-config\nruncmd:\n - touch /test.txt\n",
vpc_uuid: "760e09ef-dc84-11e8-981e-3cfdfeaae000",
)
client.droplets.create(droplet)import os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
req = {
"name": "example.com",
"region": "nyc3",
"size": "s-1vcpu-1gb",
"image": "ubuntu-20-04-x64",
"ssh_keys": [
289794,
"3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45"
],
"backups": True,
"ipv6": True,
"monitoring": True,
"tags": [
"env:prod",
"web"
],
"user_data": "#cloud-config\nruncmd:\n - touch /test.txt\n",
"vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000"
}
resp = client.droplets.create(body=req)Responses
202
Accepted
ratelimit-limit
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
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
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.
application/json
droplet
required
Show child properties
backup_ids
required
[53893572]An array of backup IDs of any backups that have been taken of the Droplet instance. Droplet backups are enabled at the time of the instance creation.
Requires image:read scope.
created_at
required
2020-07-21T18:37:44ZA time value given in ISO8601 combined date and time format that represents when the Droplet was created.
disk
required
25The size of the Droplet's disk in gigabytes.
disk_info
optional
An array of objects containing information about the disks available to the Droplet.
Show child properties
size
optional
Show child properties
amount
optional
25The amount of space allocated to the disk.
unit
optional
gibThe unit of measure for the disk size.
type
optional
localThe type of disk. All Droplets contain a local disk. Additionally, GPU Droplets can also have a scratch disk for non-persistent data.
features
required
["backups","private_networking","ipv6"]An array of features enabled on this Droplet.
gpu_info
optional
An object containing information about the GPU capabilities of Droplets created with this size.
Show child properties
count
optional
1The number of GPUs allocated to the Droplet.
model
optional
nvidia_h100The model of the GPU.
vram
optional
Show child properties
amount
optional
25The amount of VRAM allocated to the GPU.
unit
optional
gibThe unit of measure for the VRAM.
id
required
3164444A unique identifier for each Droplet instance. This is automatically generated upon Droplet creation.
image
required
kernel
optional Deprecated Nullable
Note: All Droplets created after March 2017 use internal kernels by default.
These Droplets will have this attribute set to null.
The current kernel for Droplets with externally managed kernels. This will initially be set to the kernel of the base image when the Droplet is created.
Show child properties
id
optional
7515A unique number used to identify and reference a specific kernel.
name
optional
DigitalOcean GrubLoader v0.2 (20160714)The display name of the kernel. This is shown in the web UI and is generally a descriptive title for the kernel in question.
version
optional
2016.07.13-DigitalOcean_loader_UbuntuA standard kernel version string representing the version, patch, and release information.
locked
required
falseA boolean value indicating whether the Droplet has been locked, preventing actions by users.
memory
required
1024Memory of the Droplet in megabytes.
name
required
example.comThe human-readable name set for the Droplet instance.
networks
required
The details of the network that are configured for the Droplet instance. This is an object that contains keys for IPv4 and IPv6. The value of each of these is an array that contains objects describing an individual IP resource allocated to the Droplet. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is.
Show child properties
v4
optional
Show child properties
gateway
optional
104.236.0.1The gateway of the specified IPv4 network interface.
For private interfaces, a gateway is not provided. This is denoted by
returning nil as its value.
ip_address
optional
104.236.32.182The IP address of the IPv4 network interface.
netmask
optional
255.255.192.0The netmask of the IPv4 network interface.
type
optional
publicThe type of the IPv4 network interface.
v6
optional
Show child properties
gateway
optional
2604:a880:0:1010::1The gateway of the specified IPv6 network interface.
ip_address
optional
2604:a880:0:1010::18a:a001The IP address of the IPv6 network interface.
netmask
optional
64The netmask of the IPv6 network interface.
type
optional
publicThe type of the IPv6 network interface.
Note: IPv6 private networking is not currently supported.
next_backup_window
required
region
required
Show child properties
available
required
trueThis is a boolean value that represents whether new Droplets can be created in this region.
features
required
["private_networking","backups","ipv6","metadata","install_agent","storage","image_transfer"]This attribute is set to an array which contains features available in this region
name
required
New York 3The display name of the region. This will be a full name that is used in the control panel and other interfaces.
sizes
required
This attribute is set to an array which contains the identifying slugs for the sizes available in this region. sizes:read is required to view.
slug
required
nyc3A human-readable string that is used as a unique identifier for each region.
size
required
Show child properties
available
required
trueThis is a boolean value that represents whether new Droplets can be created with this size.
description
required
BasicA string describing the class of Droplets created from this size. For example: Basic, General Purpose, CPU-Optimized, Memory-Optimized, or Storage-Optimized.
disk
required
25The amount of disk space set aside for Droplets of this size. The value is represented in gigabytes.
disk_info
optional
An array of objects containing information about the disks available to Droplets created with this size.
Show child properties
size
optional
type
optional
localThe type of disk. All Droplets contain a local disk. Additionally, GPU Droplets can also have a scratch disk for non-persistent data.
gpu_info
optional
An object containing information about the GPU capabilities of Droplets created with this size.
Show child properties
count
optional
1The number of GPUs allocated to the Droplet.
model
optional
nvidia_h100The model of the GPU.
vram
optional
memory
required
1024The amount of RAM allocated to Droplets created of this size. The value is represented in megabytes.
price_hourly
required
0.00743999984115362This describes the price of the Droplet size as measured hourly. The value is measured in US dollars.
price_monthly
required
5This attribute describes the monthly cost of this Droplet size if the Droplet is kept for an entire month. The value is measured in US dollars.
regions
required
["ams2","ams3","blr1","fra1","lon1","nyc1","nyc2","nyc3","sfo1","sfo2","sfo3","sgp1","tor1"]An array containing the region slugs where this size is available for Droplet creates.
slug
required
s-1vcpu-1gbA human-readable string that is used to uniquely identify each size.
transfer
required
1The amount of transfer bandwidth that is available for Droplets created in this size. This only counts traffic on the public interface. The value is given in terabytes.
vcpus
required
1The number of CPUs allocated to Droplets of this size.
size_slug
required
s-1vcpu-1gbThe unique slug identifier for the size of this Droplet.
snapshot_ids
required
[67512819]An array of snapshot IDs of any snapshots created from the Droplet instance.
Requires image:read scope.
status
required
activeA status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive".
tags
required
["web","env:prod"]An array of Tags the Droplet has been tagged with.
Requires tag:read scope.
vcpus
required
1The number of virtual CPUs.
volume_ids
required
["506f78a4-e098-11e5-ad9f-000f53306ae1"]A flat array including the unique identifier for each Block Storage volume attached to the Droplet.
Requires block_storage:read scope.
vpc_uuid
optional
760e09ef-dc84-11e8-981e-3cfdfeaae000A string specifying the UUID of the VPC to which the Droplet is assigned.
Requires vpc:read scope.
links
required
Show child properties
actions
optional
Show child properties
href
optional
https://api.digitalocean.com/v2/actions/7515A URL that can be used to access the action.
id
optional
7515A unique numeric ID that can be used to identify and reference an action.
rel
optional
createA string specifying the type of the related action.
droplets
required
Show child properties
backup_ids
required
[53893572]An array of backup IDs of any backups that have been taken of the Droplet instance. Droplet backups are enabled at the time of the instance creation.
Requires image:read scope.
created_at
required
2020-07-21T18:37:44ZA time value given in ISO8601 combined date and time format that represents when the Droplet was created.
disk
required
25The size of the Droplet's disk in gigabytes.
disk_info
optional
An array of objects containing information about the disks available to the Droplet.
Show child properties
size
optional
Show child properties
amount
optional
25The amount of space allocated to the disk.
unit
optional
gibThe unit of measure for the disk size.
type
optional
localThe type of disk. All Droplets contain a local disk. Additionally, GPU Droplets can also have a scratch disk for non-persistent data.
features
required
["backups","private_networking","ipv6"]An array of features enabled on this Droplet.
gpu_info
optional
An object containing information about the GPU capabilities of Droplets created with this size.
Show child properties
count
optional
1The number of GPUs allocated to the Droplet.
model
optional
nvidia_h100The model of the GPU.
vram
optional
Show child properties
amount
optional
25The amount of VRAM allocated to the GPU.
unit
optional
gibThe unit of measure for the VRAM.
id
required
3164444A unique identifier for each Droplet instance. This is automatically generated upon Droplet creation.
image
required
kernel
optional Deprecated Nullable
Note: All Droplets created after March 2017 use internal kernels by default.
These Droplets will have this attribute set to null.
The current kernel for Droplets with externally managed kernels. This will initially be set to the kernel of the base image when the Droplet is created.
Show child properties
id
optional
7515A unique number used to identify and reference a specific kernel.
name
optional
DigitalOcean GrubLoader v0.2 (20160714)The display name of the kernel. This is shown in the web UI and is generally a descriptive title for the kernel in question.
version
optional
2016.07.13-DigitalOcean_loader_UbuntuA standard kernel version string representing the version, patch, and release information.
locked
required
falseA boolean value indicating whether the Droplet has been locked, preventing actions by users.
memory
required
1024Memory of the Droplet in megabytes.
name
required
example.comThe human-readable name set for the Droplet instance.
networks
required
The details of the network that are configured for the Droplet instance. This is an object that contains keys for IPv4 and IPv6. The value of each of these is an array that contains objects describing an individual IP resource allocated to the Droplet. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is.
Show child properties
v4
optional
Show child properties
gateway
optional
104.236.0.1The gateway of the specified IPv4 network interface.
For private interfaces, a gateway is not provided. This is denoted by
returning nil as its value.
ip_address
optional
104.236.32.182The IP address of the IPv4 network interface.
netmask
optional
255.255.192.0The netmask of the IPv4 network interface.
type
optional
publicThe type of the IPv4 network interface.
v6
optional
Show child properties
gateway
optional
2604:a880:0:1010::1The gateway of the specified IPv6 network interface.
ip_address
optional
2604:a880:0:1010::18a:a001The IP address of the IPv6 network interface.
netmask
optional
64The netmask of the IPv6 network interface.
type
optional
publicThe type of the IPv6 network interface.
Note: IPv6 private networking is not currently supported.
next_backup_window
required
region
required
Show child properties
available
required
trueThis is a boolean value that represents whether new Droplets can be created in this region.
features
required
["private_networking","backups","ipv6","metadata","install_agent","storage","image_transfer"]This attribute is set to an array which contains features available in this region
name
required
New York 3The display name of the region. This will be a full name that is used in the control panel and other interfaces.
sizes
required
This attribute is set to an array which contains the identifying slugs for the sizes available in this region. sizes:read is required to view.
slug
required
nyc3A human-readable string that is used as a unique identifier for each region.
size
required
Show child properties
available
required
trueThis is a boolean value that represents whether new Droplets can be created with this size.
description
required
BasicA string describing the class of Droplets created from this size. For example: Basic, General Purpose, CPU-Optimized, Memory-Optimized, or Storage-Optimized.
disk
required
25The amount of disk space set aside for Droplets of this size. The value is represented in gigabytes.
disk_info
optional
An array of objects containing information about the disks available to Droplets created with this size.
Show child properties
size
optional
type
optional
localThe type of disk. All Droplets contain a local disk. Additionally, GPU Droplets can also have a scratch disk for non-persistent data.
gpu_info
optional
An object containing information about the GPU capabilities of Droplets created with this size.
Show child properties
count
optional
1The number of GPUs allocated to the Droplet.
model
optional
nvidia_h100The model of the GPU.
vram
optional
memory
required
1024The amount of RAM allocated to Droplets created of this size. The value is represented in megabytes.
price_hourly
required
0.00743999984115362This describes the price of the Droplet size as measured hourly. The value is measured in US dollars.
price_monthly
required
5This attribute describes the monthly cost of this Droplet size if the Droplet is kept for an entire month. The value is measured in US dollars.
regions
required
["ams2","ams3","blr1","fra1","lon1","nyc1","nyc2","nyc3","sfo1","sfo2","sfo3","sgp1","tor1"]An array containing the region slugs where this size is available for Droplet creates.
slug
required
s-1vcpu-1gbA human-readable string that is used to uniquely identify each size.
transfer
required
1The amount of transfer bandwidth that is available for Droplets created in this size. This only counts traffic on the public interface. The value is given in terabytes.
vcpus
required
1The number of CPUs allocated to Droplets of this size.
size_slug
required
s-1vcpu-1gbThe unique slug identifier for the size of this Droplet.
snapshot_ids
required
[67512819]An array of snapshot IDs of any snapshots created from the Droplet instance.
Requires image:read scope.
status
required
activeA status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive".
tags
required
["web","env:prod"]An array of Tags the Droplet has been tagged with.
Requires tag:read scope.
vcpus
required
1The number of virtual CPUs.
volume_ids
required
["506f78a4-e098-11e5-ad9f-000f53306ae1"]A flat array including the unique identifier for each Block Storage volume attached to the Droplet.
Requires block_storage:read scope.
vpc_uuid
optional
760e09ef-dc84-11e8-981e-3cfdfeaae000A string specifying the UUID of the VPC to which the Droplet is assigned.
Requires vpc:read scope.
links
required
Show child properties
actions
optional
Show child properties
href
optional
https://api.digitalocean.com/v2/actions/7515A URL that can be used to access the action.
id
optional
7515A unique numeric ID that can be used to identify and reference an action.
rel
optional
createA string specifying the type of the related action.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"droplet": {
"backup_ids": [],
"created_at": "2020-07-21T18:37:44Z",
"disk": 25,
"disk_info": [
{
"size": {
"amount": 25,
"unit": "gib"
},
"type": "local"
}
],
"features": [
"backups",
"private_networking",
"ipv6",
"monitoring"
],
"id": 3164444,
"image": {
"created_at": "2020-05-15T05:47:50Z",
"description": "",
"distribution": "Ubuntu",
"error_message": "",
"id": 63663980,
"min_disk_size": 20,
"name": "20.04 (LTS) x64",
"public": true,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sfo3",
"sgp1",
"tor1"
],
"size_gigabytes": 2.36,
"slug": "ubuntu-20-04-x64",
"status": "available",
"tags": [],
"type": "snapshot"
},
"kernel": null,
"locked": false,
"memory": 1024,
"name": "example.com",
"networks": {
"v4": [],
"v6": []
},
"next_backup_window": null,
"region": {
"available": true,
"features": [
"private_networking",
"backups",
"ipv6",
"metadata",
"install_agent",
"storage",
"image_transfer"
],
"name": "New York 3",
"sizes": [
"s-1vcpu-1gb",
"s-1vcpu-2gb",
"s-1vcpu-3gb",
"s-2vcpu-2gb",
"s-3vcpu-1gb",
"s-2vcpu-4gb",
"s-4vcpu-8gb",
"s-6vcpu-16gb",
"s-8vcpu-32gb",
"s-12vcpu-48gb",
"s-16vcpu-64gb",
"s-20vcpu-96gb",
"s-24vcpu-128gb",
"s-32vcpu-192g"
],
"slug": "nyc3"
},
"size": {
"available": true,
"description": "Basic",
"disk": 25,
"memory": 1024,
"price_hourly": 0.00743999984115362,
"price_monthly": 5,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sfo3",
"sgp1",
"tor1"
],
"slug": "s-1vcpu-1gb",
"transfer": 1,
"vcpus": 1
},
"size_slug": "s-1vcpu-1gb",
"snapshot_ids": [],
"status": "new",
"tags": [
"web",
"env:prod"
],
"vcpus": 1,
"volume_ids": []
},
"links": {
"actions": [
{
"href": "https://api.digitalocean.com/v2/actions/7515",
"id": 7515,
"rel": "create"
}
]
}
}{
"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"
}DELETE Deleting Droplets by Tag
/v2/droplets
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 delete all Droplets assigned to a specific tag, include the tag_name
query parameter set to the name of the tag in your DELETE request. For
example, /v2/droplets?tag_name=$TAG_NAME.
This endpoint requires tag:read scope.
A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully.
Query Parameters
tag_name
required
env:testSpecifies Droplets to be deleted by tag.
Request: /v2/droplets
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
"https://api.digitalocean.com/v2/droplets?tag_name=awesome"import (
"context"
"os"
"github.com/digitalocean/godo"
)
func main() {
token := os.Getenv("DIGITALOCEAN_TOKEN")
client := godo.NewFromToken(token)
ctx := context.TODO()
client.Droplets.DeleteByTag(ctx, "awesome")
}require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)
client.droplets.delete_for_tag(tag_name: awesome)import os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.droplets.destroy_by_tag(tag_name="production")Responses
204
The action was successful and the response body is empty. This response has content-type set.
content-type
The type of data that is returned from a request.
ratelimit-limit
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
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
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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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"
}GET List Backup Policies for All Existing Droplets
/v2/droplets/backups/policies
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 list information about the backup policies for all Droplets in the account,
send a GET request to /v2/droplets/backups/policies.
Query Parameters
per_page
1 – 200 optional
2Number of items returned per page
Default:20page
>= 1 optional
1Which 'page' of paginated results to return.
Default:1Request: /v2/droplets/backups/policies
curl -X GET \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
"https://api.digitalocean.com/v2/droplets/backups/policies"import (
"context"
"os"
"github.com/digitalocean/godo"
)
func main() {
token := os.Getenv("DIGITALOCEAN_TOKEN")
client := godo.NewFromToken(token)
ctx := context.TODO()
droplet, _, err := client.Droplets.ListBackupPolicies(ctx)
}import os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.droplets.list_backup_policies()Responses
200
A JSON object with a policies key set to a map. The keys are Droplet IDs and the values are objects containing the backup policy information for each Droplet.
policies key set to a map. The keys are Droplet IDs and the values are objects containing the backup policy information for each Droplet.ratelimit-limit
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
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
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.
application/json
policies
optional
A map where the keys are the Droplet IDs and the values are objects containing the backup policy information for each Droplet.
Show child properties
(additional properties)
optional
Additional properties are allowed.
links
optional
Show child properties
pages
optional
Forward Links
last
optional
https://api.digitalocean.com/v2/images?page=2URI of the last page of the results.
next
optional
https://api.digitalocean.com/v2/images?page=2URI of the next page of the results.
Backward Links
first
optional
https://api.digitalocean.com/v2/images?page=1URI of the first page of the results.
prev
optional
https://api.digitalocean.com/v2/images?page=1URI of the previous page of the results.
meta
required
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"links": {},
"meta": {
"total": 3
},
"policies": {
"436444618": {
"backup_enabled": false,
"droplet_id": 436444618
},
"444909314": {
"backup_enabled": true,
"backup_policy": {
"hour": 20,
"plan": "daily",
"retention_period_days": 7,
"window_length_hours": 4
},
"droplet_id": 444909314,
"next_backup_window": {
"end": "2024-09-14T00:00:00Z",
"start": "2024-09-13T20:00:00Z"
}
},
"444909706": {
"backup_enabled": true,
"backup_policy": {
"hour": 20,
"plan": "weekly",
"retention_period_days": 28,
"weekday": "SUN",
"window_length_hours": 4
},
"droplet_id": 444909706,
"next_backup_window": {
"end": "2024-09-16T00:00:00Z",
"start": "2024-09-15T20: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 List Supported Droplet Backup Policies
/v2/droplets/backups/supported_policies
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 retrieve a list of all supported Droplet backup policies, send a GET
request to /v2/droplets/backups/supported_policies.
Request: /v2/droplets/backups/supported_policies
curl -X GET \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
"https://api.digitalocean.com/v2/droplets/backups/supported_policies"import (
"context"
"os"
"github.com/digitalocean/godo"
)
func main() {
token := os.Getenv("DIGITALOCEAN_TOKEN")
client := godo.NewFromToken(token)
ctx := context.TODO()
droplet, _, err := client.Droplets.ListSupportedBackupPolicies(ctx)
}import os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.droplets.list_supported_backup_policies()Responses
200
A JSON object with an supported_policies key set to an array of objects describing each supported backup policy.
supported_policies key set to an array of objects describing each supported backup policy.ratelimit-limit
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
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
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.
application/json
supported_policies
optional
Show child properties
name
optional
dailyThe name of the Droplet backup plan.
possible_days
optional
["SUN","MON","TUE","WED","THU","FRI","SAT"]The day of the week the backup will occur.
possible_window_starts
optional
[0,4,8,12,16,20]An array of integers representing the hours of the day that a backup can start.
retention_period_days
optional
7The number of days that a backup will be kept.
window_length_hours
optional
4The number of hours that a backup window is open.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"supported_policies": [
{
"name": "weekly",
"possible_days": [
"SUN",
"MON",
"TUE",
"WED",
"THU",
"FRI",
"SAT"
],
"possible_window_starts": [
0,
4,
8,
12,
16,
20
],
"retention_period_days": 28,
"window_length_hours": 4
},
{
"name": "daily",
"possible_days": [],
"possible_window_starts": [
0,
4,
8,
12,
16,
20
],
"retention_period_days": 7,
"window_length_hours": 4
}
]
}{
"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 Droplet
/v2/droplets/{droplet_id}
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 show information about an individual Droplet, send a GET request to
/v2/droplets/$DROPLET_ID.
Path Parameters
droplet_id
>= 1 required
3164444A unique identifier for a Droplet instance.
Request: /v2/droplets/{droplet_id}
curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
"https://api.digitalocean.com/v2/droplets/3164494"import (
"context"
"os"
"github.com/digitalocean/godo"
)
func main() {
token := os.Getenv("DIGITALOCEAN_TOKEN")
client := godo.NewFromToken(token)
ctx := context.TODO()
droplet, _, err := client.Droplets.Get(ctx, 3164494)
}require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)
client.droplets.find(id: 3164494)import os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.droplets.get(droplet_id=594828)Responses
200
The response will be a JSON object with a key called droplet. This will be
set to a JSON object that contains the standard Droplet attributes.
droplet. This will be
set to a JSON object that contains the standard Droplet attributes.ratelimit-limit
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
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
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.
application/json
droplet
optional
Show child properties
backup_ids
required
[53893572]An array of backup IDs of any backups that have been taken of the Droplet instance. Droplet backups are enabled at the time of the instance creation.
Requires image:read scope.
created_at
required
2020-07-21T18:37:44ZA time value given in ISO8601 combined date and time format that represents when the Droplet was created.
disk
required
25The size of the Droplet's disk in gigabytes.
disk_info
optional
An array of objects containing information about the disks available to the Droplet.
Show child properties
size
optional
Show child properties
amount
optional
25The amount of space allocated to the disk.
unit
optional
gibThe unit of measure for the disk size.
type
optional
localThe type of disk. All Droplets contain a local disk. Additionally, GPU Droplets can also have a scratch disk for non-persistent data.
features
required
["backups","private_networking","ipv6"]An array of features enabled on this Droplet.
gpu_info
optional
An object containing information about the GPU capabilities of Droplets created with this size.
Show child properties
count
optional
1The number of GPUs allocated to the Droplet.
model
optional
nvidia_h100The model of the GPU.
vram
optional
Show child properties
amount
optional
25The amount of VRAM allocated to the GPU.
unit
optional
gibThe unit of measure for the VRAM.
id
required
3164444A unique identifier for each Droplet instance. This is automatically generated upon Droplet creation.
image
required
kernel
optional Deprecated Nullable
Note: All Droplets created after March 2017 use internal kernels by default.
These Droplets will have this attribute set to null.
The current kernel for Droplets with externally managed kernels. This will initially be set to the kernel of the base image when the Droplet is created.
Show child properties
id
optional
7515A unique number used to identify and reference a specific kernel.
name
optional
DigitalOcean GrubLoader v0.2 (20160714)The display name of the kernel. This is shown in the web UI and is generally a descriptive title for the kernel in question.
version
optional
2016.07.13-DigitalOcean_loader_UbuntuA standard kernel version string representing the version, patch, and release information.
locked
required
falseA boolean value indicating whether the Droplet has been locked, preventing actions by users.
memory
required
1024Memory of the Droplet in megabytes.
name
required
example.comThe human-readable name set for the Droplet instance.
networks
required
The details of the network that are configured for the Droplet instance. This is an object that contains keys for IPv4 and IPv6. The value of each of these is an array that contains objects describing an individual IP resource allocated to the Droplet. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is.
Show child properties
v4
optional
Show child properties
gateway
optional
104.236.0.1The gateway of the specified IPv4 network interface.
For private interfaces, a gateway is not provided. This is denoted by
returning nil as its value.
ip_address
optional
104.236.32.182The IP address of the IPv4 network interface.
netmask
optional
255.255.192.0The netmask of the IPv4 network interface.
type
optional
publicThe type of the IPv4 network interface.
v6
optional
Show child properties
gateway
optional
2604:a880:0:1010::1The gateway of the specified IPv6 network interface.
ip_address
optional
2604:a880:0:1010::18a:a001The IP address of the IPv6 network interface.
netmask
optional
64The netmask of the IPv6 network interface.
type
optional
publicThe type of the IPv6 network interface.
Note: IPv6 private networking is not currently supported.
next_backup_window
required
region
required
Show child properties
available
required
trueThis is a boolean value that represents whether new Droplets can be created in this region.
features
required
["private_networking","backups","ipv6","metadata","install_agent","storage","image_transfer"]This attribute is set to an array which contains features available in this region
name
required
New York 3The display name of the region. This will be a full name that is used in the control panel and other interfaces.
sizes
required
This attribute is set to an array which contains the identifying slugs for the sizes available in this region. sizes:read is required to view.
slug
required
nyc3A human-readable string that is used as a unique identifier for each region.
size
required
Show child properties
available
required
trueThis is a boolean value that represents whether new Droplets can be created with this size.
description
required
BasicA string describing the class of Droplets created from this size. For example: Basic, General Purpose, CPU-Optimized, Memory-Optimized, or Storage-Optimized.
disk
required
25The amount of disk space set aside for Droplets of this size. The value is represented in gigabytes.
disk_info
optional
An array of objects containing information about the disks available to Droplets created with this size.
Show child properties
size
optional
type
optional
localThe type of disk. All Droplets contain a local disk. Additionally, GPU Droplets can also have a scratch disk for non-persistent data.
gpu_info
optional
An object containing information about the GPU capabilities of Droplets created with this size.
Show child properties
count
optional
1The number of GPUs allocated to the Droplet.
model
optional
nvidia_h100The model of the GPU.
vram
optional
memory
required
1024The amount of RAM allocated to Droplets created of this size. The value is represented in megabytes.
price_hourly
required
0.00743999984115362This describes the price of the Droplet size as measured hourly. The value is measured in US dollars.
price_monthly
required
5This attribute describes the monthly cost of this Droplet size if the Droplet is kept for an entire month. The value is measured in US dollars.
regions
required
["ams2","ams3","blr1","fra1","lon1","nyc1","nyc2","nyc3","sfo1","sfo2","sfo3","sgp1","tor1"]An array containing the region slugs where this size is available for Droplet creates.
slug
required
s-1vcpu-1gbA human-readable string that is used to uniquely identify each size.
transfer
required
1The amount of transfer bandwidth that is available for Droplets created in this size. This only counts traffic on the public interface. The value is given in terabytes.
vcpus
required
1The number of CPUs allocated to Droplets of this size.
size_slug
required
s-1vcpu-1gbThe unique slug identifier for the size of this Droplet.
snapshot_ids
required
[67512819]An array of snapshot IDs of any snapshots created from the Droplet instance.
Requires image:read scope.
status
required
activeA status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive".
tags
required
["web","env:prod"]An array of Tags the Droplet has been tagged with.
Requires tag:read scope.
vcpus
required
1The number of virtual CPUs.
volume_ids
required
["506f78a4-e098-11e5-ad9f-000f53306ae1"]A flat array including the unique identifier for each Block Storage volume attached to the Droplet.
Requires block_storage:read scope.
vpc_uuid
optional
760e09ef-dc84-11e8-981e-3cfdfeaae000A string specifying the UUID of the VPC to which the Droplet is assigned.
Requires vpc:read scope.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"droplet": {
"backup_ids": [
53893572
],
"created_at": "2020-07-21T18:37:44Z",
"disk": 25,
"disk_info": [
{
"size": {
"amount": 25,
"unit": "gib"
},
"type": "local"
}
],
"features": [
"backups",
"private_networking",
"ipv6"
],
"id": 3164444,
"image": {
"created_at": "2020-05-15T05:47:50Z",
"description": "",
"distribution": "Ubuntu",
"error_message": "",
"id": 63663980,
"min_disk_size": 20,
"name": "20.04 (LTS) x64",
"public": true,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sfo3",
"sgp1",
"tor1"
],
"size_gigabytes": 2.36,
"slug": "ubuntu-20-04-x64",
"status": "available",
"tags": [],
"type": "snapshot"
},
"kernel": null,
"locked": false,
"memory": 1024,
"name": "example.com",
"networks": {
"v4": [
{
"gateway": "nil",
"ip_address": "10.128.192.124",
"netmask": "255.255.0.0",
"type": "private"
},
{
"gateway": "192.241.165.1",
"ip_address": "192.241.165.154",
"netmask": "255.255.255.0",
"type": "public"
}
],
"v6": [
{
"gateway": "2604:a880:0:1010::1",
"ip_address": "2604:a880:0:1010::18a:a001",
"netmask": 64,
"type": "public"
}
]
},
"next_backup_window": {
"end": "2020-07-30T23:00:00Z",
"start": "2020-07-30T00:00:00Z"
},
"region": {
"available": true,
"features": [
"private_networking",
"backups",
"ipv6",
"metadata",
"install_agent",
"storage",
"image_transfer"
],
"name": "New York 3",
"sizes": [
"s-1vcpu-1gb",
"s-1vcpu-2gb",
"s-1vcpu-3gb",
"s-2vcpu-2gb",
"s-3vcpu-1gb",
"s-2vcpu-4gb",
"s-4vcpu-8gb",
"s-6vcpu-16gb",
"s-8vcpu-32gb",
"s-12vcpu-48gb",
"s-16vcpu-64gb",
"s-20vcpu-96gb",
"s-24vcpu-128gb",
"s-32vcpu-192g"
],
"slug": "nyc3"
},
"size": {
"available": true,
"description": "Basic",
"disk": 25,
"memory": 1024,
"price_hourly": 0.00743999984115362,
"price_monthly": 5,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sfo3",
"sgp1",
"tor1"
],
"slug": "s-1vcpu-1gb",
"transfer": 1,
"vcpus": 1
},
"size_slug": "s-1vcpu-1gb",
"snapshot_ids": [
67512819
],
"status": "active",
"tags": [
"web",
"env:prod"
],
"vcpus": 1,
"volume_ids": [],
"vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000"
}
}{
"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 Existing Droplet
/v2/droplets/{droplet_id}
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 delete a Droplet, send a DELETE request to /v2/droplets/$DROPLET_ID.
A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully.
Path Parameters
droplet_id
>= 1 required
3164444A unique identifier for a Droplet instance.
Request: /v2/droplets/{droplet_id}
curl -X DELETE \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
"https://api.digitalocean.com/v2/droplets/3164494"import (
"context"
"os"
"github.com/digitalocean/godo"
)
func main() {
token := os.Getenv("DIGITALOCEAN_TOKEN")
client := godo.NewFromToken(token)
ctx := context.TODO()
_, err := client.Droplets.Delete(ctx, 3164494)
}require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)
client.droplets.delete(id: 3164494)import os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.droplets.destroy(droplet_id=553456)Responses
204
The action was successful and the response body is empty. This response has content-type set.
content-type
The type of data that is returned from a request.
ratelimit-limit
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
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
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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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"
}GET List Backups for a Droplet
/v2/droplets/{droplet_id}/backups
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 retrieve any backups associated with a Droplet, send a GET request to
/v2/droplets/$DROPLET_ID/backups.
You will get back a JSON object that has a backups key. This will be set to
an array of backup objects, each of which contain the standard
Droplet backup attributes.
Path Parameters
droplet_id
>= 1 required
3164444A unique identifier for a Droplet instance.
Query Parameters
per_page
1 – 200 optional
2Number of items returned per page
Default:20page
>= 1 optional
1Which 'page' of paginated results to return.
Default:1Request: /v2/droplets/{droplet_id}/backups
curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
"https://api.digitalocean.com/v2/droplets/3067509/backups"import (
"context"
"os"
"github.com/digitalocean/godo"
)
func main() {
token := os.Getenv("DIGITALOCEAN_TOKEN")
client := godo.NewFromToken(token)
ctx := context.TODO()
opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
backups, _, err := client.Droplets.Backups(ctx, 3164494, opt)
}require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)
backups = client.droplets.backups(id: 3164494)
backups.eachimport os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.droplets.list_backups(droplet_id=594828)Responses
200
A JSON object with an backups key.
backups key.ratelimit-limit
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
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
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.
application/json
backups
optional
Show child properties
id
required
6372321The unique identifier for the snapshot or backup.
created_at
required
2020-07-28T16:47:44ZA time value given in ISO8601 combined date and time format that represents when the snapshot was created.
min_disk_size
required
25The minimum size in GB required for a volume or Droplet to use this snapshot.
name
required
web-01-1595954862243A human-readable name for the snapshot.
regions
required
["nyc3","sfo3"]An array of the regions that the snapshot is available in. The regions are represented by their identifying slug values.
size_gigabytes
required
2.34The billable size of the snapshot in gigabytes.
type
required
snapshotDescribes the kind of image. It may be one of snapshot or backup. This specifies whether an image is a user-generated Droplet snapshot or automatically created Droplet backup.
links
optional
Show child properties
pages
optional
Forward Links
last
optional
https://api.digitalocean.com/v2/images?page=2URI of the last page of the results.
next
optional
https://api.digitalocean.com/v2/images?page=2URI of the next page of the results.
Backward Links
first
optional
https://api.digitalocean.com/v2/images?page=1URI of the first page of the results.
prev
optional
https://api.digitalocean.com/v2/images?page=1URI of the previous page of the results.
meta
required
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"backups": [
{
"created_at": "2020-07-29T01:44:35Z",
"distribution": "Ubuntu",
"id": 67539192,
"min_disk_size": 50,
"name": "web-01- 2020-07-29",
"public": false,
"regions": [
"nyc3"
],
"size_gigabytes": 2.34,
"slug": null,
"type": "backup"
}
],
"links": {},
"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"
}GET Retrieve the Backup Policy for an Existing Droplet
/v2/droplets/{droplet_id}/backups/policy
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 show information about an individual Droplet's backup policy, send a GET
request to /v2/droplets/$DROPLET_ID/backups/policy.
Path Parameters
droplet_id
>= 1 required
3164444A unique identifier for a Droplet instance.
Request: /v2/droplets/{droplet_id}/backups/policy
curl -X GET \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
"https://api.digitalocean.com/v2/droplets/3164494/backups/policy"import (
"context"
"os"
"github.com/digitalocean/godo"
)
func main() {
token := os.Getenv("DIGITALOCEAN_TOKEN")
client := godo.NewFromToken(token)
ctx := context.TODO()
droplet, _, err := client.Droplets.GetBackupPolicy(ctx, 444909706)
}import os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.droplets.get_backup_policy(droplet_id=444909706)Responses
200
The response will be a JSON object with a key called policy. This will be
set to a JSON object that contains the standard Droplet backup policy attributes.
policy. This will be
set to a JSON object that contains the standard Droplet backup policy attributes.ratelimit-limit
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
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
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.
application/json
policy
optional
Show child properties
backup_enabled
optional
trueA boolean value indicating whether backups are enabled for the Droplet.
backup_policy
optional
droplet_id
optional
7101383The unique identifier for the Droplet.
next_backup_window
optional
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"policy": {
"backup_enabled": true,
"backup_policy": {
"hour": 20,
"plan": "weekly",
"retention_period_days": 28,
"weekday": "SUN",
"window_length_hours": 4
},
"droplet_id": 444909706,
"next_backup_window": {
"end": "2024-09-16T00:00:00Z",
"start": "2024-09-15T20: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 List Associated Resources for a Droplet
/v2/droplets/{droplet_id}/destroy_with_associated_resources
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 list the associated billable resources that can be destroyed along with a
Droplet, send a GET request to the
/v2/droplets/$DROPLET_ID/destroy_with_associated_resources endpoint.
This endpoint will only return resources that you are authorized to see. For
example, to see associated Reserved IPs, include the reserved_ip:read scope.
The response will be a JSON object containing snapshots, volumes, and
volume_snapshots keys. Each will be set to an array of objects containing
information about the associated resources.
Path Parameters
droplet_id
>= 1 required
3164444A unique identifier for a Droplet instance.
Request: /v2/droplets/{droplet_id}/destroy_with_associated_resources
curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
"https://api.digitalocean.com/v2/droplets/3164494/destroy_with_associated_resources"import os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.droplets.list_associated_resources(droplet_id=594828)Responses
200
A JSON object containing snapshots, volumes, and volume_snapshots keys.
snapshots, volumes, and volume_snapshots keys.ratelimit-limit
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
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
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.
application/json
floating_ips
optional
Floating IPs that are associated with this Droplet.
Requires reserved_ip:read scope.
Show child properties
cost
optional
0.05The cost of the resource in USD per month if the resource is retained after the Droplet is destroyed.
id
optional
61486916The unique identifier for the resource associated with the Droplet.
name
optional
ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330The name of the resource associated with the Droplet.
reserved_ips
optional
Reserved IPs that are associated with this Droplet.
Requires reserved_ip:read scope.
Show child properties
cost
optional
0.05The cost of the resource in USD per month if the resource is retained after the Droplet is destroyed.
id
optional
61486916The unique identifier for the resource associated with the Droplet.
name
optional
ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330The name of the resource associated with the Droplet.
snapshots
optional
Snapshots that are associated with this Droplet.
Requires image:read scope.
Show child properties
cost
optional
0.05The cost of the resource in USD per month if the resource is retained after the Droplet is destroyed.
id
optional
61486916The unique identifier for the resource associated with the Droplet.
name
optional
ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330The name of the resource associated with the Droplet.
volume_snapshots
optional
Volume Snapshots that are associated with this Droplet.
Requires block_storage_snapshot:read scope.
Show child properties
cost
optional
0.05The cost of the resource in USD per month if the resource is retained after the Droplet is destroyed.
id
optional
61486916The unique identifier for the resource associated with the Droplet.
name
optional
ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330The name of the resource associated with the Droplet.
volumes
optional
Volumes that are associated with this Droplet.
Requires block_storage:read scope.
Show child properties
cost
optional
0.05The cost of the resource in USD per month if the resource is retained after the Droplet is destroyed.
id
optional
61486916The unique identifier for the resource associated with the Droplet.
name
optional
ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330The name of the resource associated with the Droplet.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"floating_ips": [
{
"cost": "4.00",
"id": "6186916",
"name": "45.55.96.47"
}
],
"reserved_ips": [
{
"cost": "4.00",
"id": "6186916",
"name": "45.55.96.47"
}
],
"snapshots": [
{
"cost": "0.05",
"id": "61486916",
"name": "ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330"
}
],
"volume_snapshots": [
{
"cost": "0.04",
"id": "edb0478d-7436-11ea-86e6-0a58ac144b91",
"name": "volume-nyc1-01-1585758983629"
}
],
"volumes": [
{
"cost": "10.00",
"id": "ba49449a-7435-11ea-b89e-0a58ac14480f",
"name": "volume-nyc1-01"
}
]
}{
"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 Destroy a Droplet and All of its Associated Resources (Dangerous)
/v2/droplets/{droplet_id}/destroy_with_associated_resources/dangerous
Authorizations:
bearer_auth
(5 scopes)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 destroy a Droplet along with all of its associated resources, send a DELETE
request to the /v2/droplets/$DROPLET_ID/destroy_with_associated_resources/dangerous
endpoint. The headers of this request must include an X-Dangerous key set to
true. To preview which resources will be destroyed, first query the
Droplet's associated resources. This operation can not be reverse and should
be used with caution.
A successful response will include a 202 response code and no content. Use the status endpoint to check on the success or failure of the destruction of the individual resources.
Path Parameters
droplet_id
>= 1 required
3164444A unique identifier for a Droplet instance.
Header Parameters
X-Dangerous
required
trueAcknowledge this action will destroy the Droplet and all associated resources and can not be reversed.
Request: /v2/droplets/{droplet_id}/destroy_with_associated_resources/dangerous
curl -X DELETE -H "X-Dangerous: true" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
"https://api.digitalocean.com/v2/droplets/187000742/destroy_with_associated_resources/dangerous"import os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.droplets.destroy_with_associated_resources_dangerous(droplet_id=524512)Responses
202
This does not indicate the success or failure of any operation, just that the request has been accepted for processing.
ratelimit-limit
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
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
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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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 Retry a Droplet Destroy with Associated Resources Request
/v2/droplets/{droplet_id}/destroy_with_associated_resources/retry
Authorizations:
bearer_auth
(5 scopes)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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"
If the status of a request to destroy a Droplet with its associated resources
reported any errors, it can be retried by sending a POST request to the
/v2/droplets/$DROPLET_ID/destroy_with_associated_resources/retry endpoint.
Only one destroy can be active at a time per Droplet. If a retry is issued while another destroy is in progress for the Droplet a 409 status code will be returned. A successful response will include a 202 response code and no content.
Path Parameters
droplet_id
>= 1 required
3164444A unique identifier for a Droplet instance.
Request: /v2/droplets/{droplet_id}/destroy_with_associated_resources/retry
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
"https://api.digitalocean.com/v2/droplets/3164494/destroy_with_associated_resources/retry"import os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.droplets.destroy_retry_with_associated_resources(droplet_id=524512)Responses
202
This does not indicate the success or failure of any operation, just that the request has been accepted for processing.
ratelimit-limit
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
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
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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
409
The request could not be completed due to a conflict.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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": "conflict",
"message": "The request could not be completed due to a conflict."
}{
"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 Selectively Destroy a Droplet and its Associated Resources
/v2/droplets/{droplet_id}/destroy_with_associated_resources/selective
Authorizations:
bearer_auth
(5 scopes)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 destroy a Droplet along with a sub-set of its associated resources, send a
DELETE request to the /v2/droplets/$DROPLET_ID/destroy_with_associated_resources/selective
endpoint. The JSON body of the request should include reserved_ips, snapshots, volumes,
or volume_snapshots keys each set to an array of IDs for the associated
resources to be destroyed. The IDs can be found by querying the Droplet's
associated resources. Any associated resource not included in the request
will remain and continue to accrue changes on your account.
A successful response will include a 202 response code and no content. Use the status endpoint to check on the success or failure of the destruction of the individual resources.
Path Parameters
droplet_id
>= 1 required
3164444A unique identifier for a Droplet instance.
Request Body: application/json
floating_ips
optional Deprecated
["6186916"]An array of unique identifiers for the floating IPs to be scheduled for deletion.
reserved_ips
optional
["6186916"]An array of unique identifiers for the reserved IPs to be scheduled for deletion.
snapshots
optional
["61486916"]An array of unique identifiers for the snapshots to be scheduled for deletion.
volume_snapshots
optional
["edb0478d-7436-11ea-86e6-0a58ac144b91"]An array of unique identifiers for the volume snapshots to be scheduled for deletion.
volumes
optional
["ba49449a-7435-11ea-b89e-0a58ac14480f"]An array of unique identifiers for the volumes to be scheduled for deletion.
Request: /v2/droplets/{droplet_id}/destroy_with_associated_resources/selective
{
"floating_ips": [
"6186916"
],
"reserved_ips": [
"6186916"
],
"snapshots": [
"61486916"
],
"volume_snapshots": [
"edb0478d-7436-11ea-86e6-0a58ac144b91"
],
"volumes": [
"ba49449a-7435-11ea-b89e-0a58ac14480f"
]
}curl -X DELETE \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
-d '{"reserved_ips":["6186916"],"snapshots": ["61486916"],"volumes": ["ba49449a-7435-11ea-b89e-0a58ac14480f"],"volume_snapshots": ["edb0478d-7436-11ea-86e6-0a58ac144b91"]}' \
"https://api.digitalocean.com/v2/droplets/187000742/destroy_with_associated_resources/selective"import os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.droplets.destroy_with_associated_resources_selective(droplet_id=524512)Responses
202
This does not indicate the success or failure of any operation, just that the request has been accepted for processing.
ratelimit-limit
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
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
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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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"
}GET Check Status of a Droplet Destroy with Associated Resources Request
/v2/droplets/{droplet_id}/destroy_with_associated_resources/status
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 check on the status of a request to destroy a Droplet with its associated
resources, send a GET request to the
/v2/droplets/$DROPLET_ID/destroy_with_associated_resources/status endpoint.
Path Parameters
droplet_id
>= 1 required
3164444A unique identifier for a Droplet instance.
Request: /v2/droplets/{droplet_id}/destroy_with_associated_resources/status
curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
"https://api.digitalocean.com/v2/droplets/3164494/destroy_with_associated_resources/status"import os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.droplets.get_destroy_associated_resources_status(droplet_id=5624512)Responses
200
A JSON object containing containing the status of a request to destroy a Droplet and its associated resources.
ratelimit-limit
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
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
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.
application/json
completed_at
optional
2020-04-01T18:11:49ZA time value given in ISO8601 combined date and time format indicating when the requested action was completed.
droplet
optional
An object containing information about a resource scheduled for deletion.
Show child properties
destroyed_at
optional
2020-04-01T18:11:49ZA time value given in ISO8601 combined date and time format indicating when the resource was destroyed if the request was successful.
error_message
optional
A string indicating that the resource was not successfully destroyed and providing additional information.
id
optional
61486916The unique identifier for the resource scheduled for deletion.
name
optional
ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330The name of the resource scheduled for deletion.
failures
optional
0A count of the associated resources that failed to be destroyed, if any.
resources
optional
An object containing additional information about resource related to a Droplet requested to be destroyed.
Show child properties
floating_ips
optional
Show child properties
destroyed_at
optional
2020-04-01T18:11:49ZA time value given in ISO8601 combined date and time format indicating when the resource was destroyed if the request was successful.
error_message
optional
A string indicating that the resource was not successfully destroyed and providing additional information.
id
optional
61486916The unique identifier for the resource scheduled for deletion.
name
optional
ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330The name of the resource scheduled for deletion.
reserved_ips
optional
Show child properties
destroyed_at
optional
2020-04-01T18:11:49ZA time value given in ISO8601 combined date and time format indicating when the resource was destroyed if the request was successful.
error_message
optional
A string indicating that the resource was not successfully destroyed and providing additional information.
id
optional
61486916The unique identifier for the resource scheduled for deletion.
name
optional
ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330The name of the resource scheduled for deletion.
snapshots
optional
Show child properties
destroyed_at
optional
2020-04-01T18:11:49ZA time value given in ISO8601 combined date and time format indicating when the resource was destroyed if the request was successful.
error_message
optional
A string indicating that the resource was not successfully destroyed and providing additional information.
id
optional
61486916The unique identifier for the resource scheduled for deletion.
name
optional
ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330The name of the resource scheduled for deletion.
volume_snapshots
optional
Show child properties
destroyed_at
optional
2020-04-01T18:11:49ZA time value given in ISO8601 combined date and time format indicating when the resource was destroyed if the request was successful.
error_message
optional
A string indicating that the resource was not successfully destroyed and providing additional information.
id
optional
61486916The unique identifier for the resource scheduled for deletion.
name
optional
ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330The name of the resource scheduled for deletion.
volumes
optional
Show child properties
destroyed_at
optional
2020-04-01T18:11:49ZA time value given in ISO8601 combined date and time format indicating when the resource was destroyed if the request was successful.
error_message
optional
A string indicating that the resource was not successfully destroyed and providing additional information.
id
optional
61486916The unique identifier for the resource scheduled for deletion.
name
optional
ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330The name of the resource scheduled for deletion.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"completed_at": "2020-04-01T18:11:49Z",
"droplet": {
"destroyed_at": "2020-04-01T18:11:49Z",
"id": "187000742",
"name": "ubuntu-s-1vcpu-1gb-nyc1-01"
},
"failures": 0,
"resources": {
"floating_ips": [
{
"destroyed_at": "2020-04-01T18:11:44Z",
"id": "6186916",
"name": "45.55.96.47"
}
],
"reserved_ips": [
{
"destroyed_at": "2020-04-01T18:11:44Z",
"id": "6186916",
"name": "45.55.96.47"
}
],
"snapshots": [
{
"destroyed_at": "2020-04-01T18:11:44Z",
"id": "61486916",
"name": "ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330"
}
],
"volume_snapshots": [
{
"destroyed_at": "2020-04-01T18:11:44Z",
"id": "edb0478d-7436-11ea-86e6-0a58ac144b91",
"name": "volume-nyc1-01-1585758983629"
}
],
"volumes": []
}
}{
"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 Firewalls Applied to a Droplet
/v2/droplets/{droplet_id}/firewalls
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 retrieve a list of all firewalls available to a Droplet, send a GET request
to /v2/droplets/$DROPLET_ID/firewalls
The response will be a JSON object that has a key called firewalls. This will
be set to an array of firewall objects, each of which contain the standard
firewall attributes.
Path Parameters
droplet_id
>= 1 required
3164444A unique identifier for a Droplet instance.
Query Parameters
per_page
1 – 200 optional
2Number of items returned per page
Default:20page
>= 1 optional
1Which 'page' of paginated results to return.
Default:1Request: /v2/droplets/{droplet_id}/firewalls
curl -X GET \
-H "Authorization: Bearer $API_TOKEN" \
"https://api.digitalocean.com/v2/droplets/{droplet_id}/firewalls"Responses
200
A JSON object that has a key called firewalls.
firewalls.ratelimit-limit
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
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
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.
application/json
firewalls
optional
Show child properties
created_at
optional read-only
2020-05-23T21:24:00ZA time value given in ISO8601 combined date and time format that represents when the firewall was created.
droplet_ids
optional Nullable
[8043964]An array containing the IDs of the Droplets assigned to the firewall.
Requires droplet:read scope.
id
optional read-only
bb4b2611-3d72-467b-8602-280330ecd65cA unique ID that can be used to identify and reference a firewall.
name
optional
firewallA human-readable name for a firewall. The name must begin with an alphanumeric character. Subsequent characters must either be alphanumeric characters, a period (.), or a dash (-).
pending_changes
optional read-only
[{"droplet_id":8043964,"removing":false,"status":"waiting"}]An array of objects each containing the fields "droplet_id", "removing", and "status". It is provided to detail exactly which Droplets are having their security policies updated. When empty, all changes have been successfully applied.
Show child properties
droplet_id
optional
8043964removing
optional
falsestatus
optional
waitingstatus
optional read-only
waitingA status string indicating the current state of the firewall. This can be "waiting", "succeeded", or "failed".
tags
optional
inbound_rules
optional Nullable
Show child properties
ports
required
8000The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "0" when all ports are open for a protocol. For ICMP rules this parameter will always return "0".
protocol
required
tcpThe type of traffic to be allowed. This may be one of tcp, udp, or icmp.
sources
required
outbound_rules
optional Nullable
Show child properties
ports
required
8000The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "0" when all ports are open for a protocol. For ICMP rules this parameter will always return "0".
protocol
required
tcpThe type of traffic to be allowed. This may be one of tcp, udp, or icmp.
destinations
required
links
optional
Show child properties
pages
optional
Forward Links
last
optional
https://api.digitalocean.com/v2/images?page=2URI of the last page of the results.
next
optional
https://api.digitalocean.com/v2/images?page=2URI of the next page of the results.
Backward Links
first
optional
https://api.digitalocean.com/v2/images?page=1URI of the first page of the results.
prev
optional
https://api.digitalocean.com/v2/images?page=1URI of the previous page of the results.
meta
required
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"firewalls": [
{
"created_at": "2020-05-23T21:24:00Z",
"droplet_ids": [
89989,
33322
],
"id": "bb4b2611-3d72-467b-8602-280330ecd65c",
"inbound_rules": [
{
"ports": "8000-9000",
"protocol": "udp",
"sources": {
"addresses": [
"1.2.3.4",
"18.0.0.0/8"
],
"droplet_ids": [
8282823,
3930392
],
"load_balancer_uids": [
"4de7ac8b-495b-4884-9a69-1050c6793cd6"
],
"tags": [
"base-image",
"dev"
]
}
}
],
"name": "firewall",
"outbound_rules": [
{
"destinations": {
"addresses": [
"1.2.3.4",
"18.0.0.0/8"
],
"droplet_ids": [
3827493,
213213
],
"load_balancer_uids": [
"4de7ac8b-495b-4884-9a69-1050c6793cd6"
],
"tags": [
"base-image",
"prod"
]
},
"ports": "7000-9000",
"protocol": "tcp"
}
],
"pending_changes": [
{
"droplet_id": 8043964,
"removing": true,
"status": "waiting"
}
],
"status": "succeeded",
"tags": [
"base-image",
"prod"
]
}
],
"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"
}GET List All Available Kernels for a Droplet
/v2/droplets/{droplet_id}/kernels
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 retrieve a list of all kernels available to a Droplet, send a GET request
to /v2/droplets/$DROPLET_ID/kernels
The response will be a JSON object that has a key called kernels. This will
be set to an array of kernel objects, each of which contain the standard
kernel attributes.
Path Parameters
droplet_id
>= 1 required
3164444A unique identifier for a Droplet instance.
Query Parameters
per_page
1 – 200 optional
2Number of items returned per page
Default:20page
>= 1 optional
1Which 'page' of paginated results to return.
Default:1Request: /v2/droplets/{droplet_id}/kernels
curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
"https://api.digitalocean.com/v2/droplets/3164494/kernels?page=1&per_page=1"import (
"context"
"os"
"github.com/digitalocean/godo"
)
func main() {
token := os.Getenv("DIGITALOCEAN_TOKEN")
client := godo.NewFromToken(token)
ctx := context.TODO()
opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
kernels, _, err := client.Droplets.Kernels(ctx, 3164494, opt)
}require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)
kernels = client.droplets.kernels(id: 3164494)
kernels.eachimport os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.droplets.list_kernels(droplet_id=594828)Responses
200
A JSON object that has a key called kernels.
kernels.ratelimit-limit
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
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
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.
application/json
kernels
optional
Show child properties
id
optional
7515A unique number used to identify and reference a specific kernel.
name
optional
DigitalOcean GrubLoader v0.2 (20160714)The display name of the kernel. This is shown in the web UI and is generally a descriptive title for the kernel in question.
version
optional
2016.07.13-DigitalOcean_loader_UbuntuA standard kernel version string representing the version, patch, and release information.
links
optional
Show child properties
pages
optional
Forward Links
last
optional
https://api.digitalocean.com/v2/images?page=2URI of the last page of the results.
next
optional
https://api.digitalocean.com/v2/images?page=2URI of the next page of the results.
Backward Links
first
optional
https://api.digitalocean.com/v2/images?page=1URI of the first page of the results.
prev
optional
https://api.digitalocean.com/v2/images?page=1URI of the previous page of the results.
meta
required
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"kernels": [
{
"id": 7515,
"name": "DigitalOcean GrubLoader v0.2 (20160714)",
"version": "2016.07.13-DigitalOcean_loader_Ubuntu"
}
],
"links": {
"pages": {
"last": "https://api.digitalocean.com/v2/droplets/3164444/kernels?page=171\u0026per_page=1",
"next": "https://api.digitalocean.com/v2/droplets/3164444/kernels?page=2\u0026per_page=1"
}
},
"meta": {
"total": 171
}
}{
"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 Neighbors for a Droplet
/v2/droplets/{droplet_id}/neighbors
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 retrieve a list of any "neighbors" (i.e. Droplets that are co-located on
the same physical hardware) for a specific Droplet, send a GET request to
/v2/droplets/$DROPLET_ID/neighbors.
The results will be returned as a JSON object with a key of droplets. This
will be set to an array containing objects representing any other Droplets
that share the same physical hardware. An empty array indicates that the
Droplet is not co-located any other Droplets associated with your account.
Path Parameters
droplet_id
>= 1 required
3164444A unique identifier for a Droplet instance.
Request: /v2/droplets/{droplet_id}/neighbors
curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
"https://api.digitalocean.com/v2/droplets/3164494/neighbors"import os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.droplets.list_neighbors(droplet_id=594828)Responses
200
A JSON object with an droplets key.
droplets key.ratelimit-limit
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
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
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.
application/json
droplets
optional
Show child properties
backup_ids
required
[53893572]An array of backup IDs of any backups that have been taken of the Droplet instance. Droplet backups are enabled at the time of the instance creation.
Requires image:read scope.
created_at
required
2020-07-21T18:37:44ZA time value given in ISO8601 combined date and time format that represents when the Droplet was created.
disk
required
25The size of the Droplet's disk in gigabytes.
disk_info
optional
An array of objects containing information about the disks available to the Droplet.
Show child properties
size
optional
Show child properties
amount
optional
25The amount of space allocated to the disk.
unit
optional
gibThe unit of measure for the disk size.
type
optional
localThe type of disk. All Droplets contain a local disk. Additionally, GPU Droplets can also have a scratch disk for non-persistent data.
features
required
["backups","private_networking","ipv6"]An array of features enabled on this Droplet.
gpu_info
optional
An object containing information about the GPU capabilities of Droplets created with this size.
Show child properties
count
optional
1The number of GPUs allocated to the Droplet.
model
optional
nvidia_h100The model of the GPU.
vram
optional
Show child properties
amount
optional
25The amount of VRAM allocated to the GPU.
unit
optional
gibThe unit of measure for the VRAM.
id
required
3164444A unique identifier for each Droplet instance. This is automatically generated upon Droplet creation.
image
required
kernel
optional Deprecated Nullable
Note: All Droplets created after March 2017 use internal kernels by default.
These Droplets will have this attribute set to null.
The current kernel for Droplets with externally managed kernels. This will initially be set to the kernel of the base image when the Droplet is created.
Show child properties
id
optional
7515A unique number used to identify and reference a specific kernel.
name
optional
DigitalOcean GrubLoader v0.2 (20160714)The display name of the kernel. This is shown in the web UI and is generally a descriptive title for the kernel in question.
version
optional
2016.07.13-DigitalOcean_loader_UbuntuA standard kernel version string representing the version, patch, and release information.
locked
required
falseA boolean value indicating whether the Droplet has been locked, preventing actions by users.
memory
required
1024Memory of the Droplet in megabytes.
name
required
example.comThe human-readable name set for the Droplet instance.
networks
required
The details of the network that are configured for the Droplet instance. This is an object that contains keys for IPv4 and IPv6. The value of each of these is an array that contains objects describing an individual IP resource allocated to the Droplet. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is.
Show child properties
v4
optional
Show child properties
gateway
optional
104.236.0.1The gateway of the specified IPv4 network interface.
For private interfaces, a gateway is not provided. This is denoted by
returning nil as its value.
ip_address
optional
104.236.32.182The IP address of the IPv4 network interface.
netmask
optional
255.255.192.0The netmask of the IPv4 network interface.
type
optional
publicThe type of the IPv4 network interface.
v6
optional
Show child properties
gateway
optional
2604:a880:0:1010::1The gateway of the specified IPv6 network interface.
ip_address
optional
2604:a880:0:1010::18a:a001The IP address of the IPv6 network interface.
netmask
optional
64The netmask of the IPv6 network interface.
type
optional
publicThe type of the IPv6 network interface.
Note: IPv6 private networking is not currently supported.
next_backup_window
required
region
required
Show child properties
available
required
trueThis is a boolean value that represents whether new Droplets can be created in this region.
features
required
["private_networking","backups","ipv6","metadata","install_agent","storage","image_transfer"]This attribute is set to an array which contains features available in this region
name
required
New York 3The display name of the region. This will be a full name that is used in the control panel and other interfaces.
sizes
required
This attribute is set to an array which contains the identifying slugs for the sizes available in this region. sizes:read is required to view.
slug
required
nyc3A human-readable string that is used as a unique identifier for each region.
size
required
Show child properties
available
required
trueThis is a boolean value that represents whether new Droplets can be created with this size.
description
required
BasicA string describing the class of Droplets created from this size. For example: Basic, General Purpose, CPU-Optimized, Memory-Optimized, or Storage-Optimized.
disk
required
25The amount of disk space set aside for Droplets of this size. The value is represented in gigabytes.
disk_info
optional
An array of objects containing information about the disks available to Droplets created with this size.
Show child properties
size
optional
type
optional
localThe type of disk. All Droplets contain a local disk. Additionally, GPU Droplets can also have a scratch disk for non-persistent data.
gpu_info
optional
An object containing information about the GPU capabilities of Droplets created with this size.
Show child properties
count
optional
1The number of GPUs allocated to the Droplet.
model
optional
nvidia_h100The model of the GPU.
vram
optional
memory
required
1024The amount of RAM allocated to Droplets created of this size. The value is represented in megabytes.
price_hourly
required
0.00743999984115362This describes the price of the Droplet size as measured hourly. The value is measured in US dollars.
price_monthly
required
5This attribute describes the monthly cost of this Droplet size if the Droplet is kept for an entire month. The value is measured in US dollars.
regions
required
["ams2","ams3","blr1","fra1","lon1","nyc1","nyc2","nyc3","sfo1","sfo2","sfo3","sgp1","tor1"]An array containing the region slugs where this size is available for Droplet creates.
slug
required
s-1vcpu-1gbA human-readable string that is used to uniquely identify each size.
transfer
required
1The amount of transfer bandwidth that is available for Droplets created in this size. This only counts traffic on the public interface. The value is given in terabytes.
vcpus
required
1The number of CPUs allocated to Droplets of this size.
size_slug
required
s-1vcpu-1gbThe unique slug identifier for the size of this Droplet.
snapshot_ids
required
[67512819]An array of snapshot IDs of any snapshots created from the Droplet instance.
Requires image:read scope.
status
required
activeA status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive".
tags
required
["web","env:prod"]An array of Tags the Droplet has been tagged with.
Requires tag:read scope.
vcpus
required
1The number of virtual CPUs.
volume_ids
required
["506f78a4-e098-11e5-ad9f-000f53306ae1"]A flat array including the unique identifier for each Block Storage volume attached to the Droplet.
Requires block_storage:read scope.
vpc_uuid
optional
760e09ef-dc84-11e8-981e-3cfdfeaae000A string specifying the UUID of the VPC to which the Droplet is assigned.
Requires vpc:read scope.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"droplets": [
{
"backup_ids": [
53893572
],
"created_at": "2020-07-21T18:37:44Z",
"disk": 25,
"disk_info": [],
"features": [
"backups",
"private_networking",
"ipv6"
],
"id": 3164444,
"locked": false,
"memory": 1024,
"name": "example.com",
"size_slug": "s-1vcpu-1gb",
"snapshot_ids": [
67512819
],
"status": "active",
"tags": [
"web",
"env:prod"
],
"vcpus": 1,
"volume_ids": [
"506f78a4-e098-11e5-ad9f-000f53306ae1"
],
"vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000"
}
]
}{
"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 Snapshots for a Droplet
/v2/droplets/{droplet_id}/snapshots
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 retrieve the snapshots that have been created from a Droplet, send a GET
request to /v2/droplets/$DROPLET_ID/snapshots.
You will get back a JSON object that has a snapshots key. This will be set
to an array of snapshot objects, each of which contain the standard Droplet
snapshot attributes.
Path Parameters
droplet_id
>= 1 required
3164444A unique identifier for a Droplet instance.
Query Parameters
per_page
1 – 200 optional
2Number of items returned per page
Default:20page
>= 1 optional
1Which 'page' of paginated results to return.
Default:1Request: /v2/droplets/{droplet_id}/snapshots
curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
"https://api.digitalocean.com/v2/droplets/3164494/snapshots?page=1&per_page=1"import (
"context"
"os"
"github.com/digitalocean/godo"
)
func main() {
token := os.Getenv("DIGITALOCEAN_TOKEN")
client := godo.NewFromToken(token)
ctx := context.TODO()
opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
snapshots, _, err := client.Droplets.Snapshots(ctx, 3164494, opt)
}require 'droplet_kit'
token = ENV['DIGITALOCEAN_TOKEN']
client = DropletKit::Client.new(access_token: token)
snapshots = client.droplets.snapshots(id: 3164494)
snapshots.eachimport os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.droplets.list_snapshots(droplet_id=3929391)Responses
200
A JSON object with an snapshots key.
snapshots key.ratelimit-limit
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
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
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.
application/json
snapshots
optional
Show child properties
id
required
6372321The unique identifier for the snapshot or backup.
created_at
required
2020-07-28T16:47:44ZA time value given in ISO8601 combined date and time format that represents when the snapshot was created.
min_disk_size
required
25The minimum size in GB required for a volume or Droplet to use this snapshot.
name
required
web-01-1595954862243A human-readable name for the snapshot.
regions
required
["nyc3","sfo3"]An array of the regions that the snapshot is available in. The regions are represented by their identifying slug values.
size_gigabytes
required
2.34The billable size of the snapshot in gigabytes.
type
required
snapshotDescribes the kind of image. It may be one of snapshot or backup. This specifies whether an image is a user-generated Droplet snapshot or automatically created Droplet backup.
links
optional
Show child properties
pages
optional
Forward Links
last
optional
https://api.digitalocean.com/v2/images?page=2URI of the last page of the results.
next
optional
https://api.digitalocean.com/v2/images?page=2URI of the next page of the results.
Backward Links
first
optional
https://api.digitalocean.com/v2/images?page=1URI of the first page of the results.
prev
optional
https://api.digitalocean.com/v2/images?page=1URI of the previous page of the results.
meta
required
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"links": {},
"meta": {
"total": 1
},
"snapshots": [
{
"created_at": "2020-07-28T16:47:44Z",
"id": 6372321,
"min_disk_size": 25,
"name": "web-01-1595954862243",
"regions": [
"nyc3",
"sfo3"
],
"size_gigabytes": 2.34,
"type": "snapshot"
}
]
}{
"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 Droplet Neighbors
/v2/reports/droplet_neighbors_ids
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 retrieve a list of all Droplets that are co-located on the same physical
hardware, send a GET request to /v2/reports/droplet_neighbors_ids.
The results will be returned as a JSON object with a key of neighbor_ids.
This will be set to an array of arrays. Each array will contain a set of
Droplet IDs for Droplets that share a physical server. An empty array
indicates that all Droplets associated with your account are located on
separate physical hardware.
Request: /v2/reports/droplet_neighbors_ids
curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
"https://api.digitalocean.com/v2/reports/droplet_neighbors_ids"import os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.droplets.list_neighbors_ids()Responses
200
A JSON object with an neighbor_ids key.
neighbor_ids key.ratelimit-limit
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
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
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.
application/json
neighbor_ids
optional
[[168671828,168663509,168671815],[168671883,168671750]]An array of arrays. Each array will contain a set of Droplet IDs for Droplets that share a physical server.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"neighbor_ids": [
[
168671828,
168663509,
168671815
],
[
168671883,
168671750
]
]
}{
"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"
}