The DigitalOcean API lets you programmatically manage your Droplets and other resources using conventional HTTP requests. Any action that you can perform through the DigitalOcean Control Panel (except for creating personal access tokens) can also be performed with the API. Resources include Droplets, Kubernetes, Apps, Databases, Spaces, Volumes, Load Balancers, Networking, Functions, Container Registry, Monitoring, and Billing.
openapi: 3.0.0
info:
title: DigitalOcean API
version: '2.0'
description: >
# Introduction
The DigitalOcean API allows you to manage Droplets and resources within the
DigitalOcean cloud in a simple, programmatic way using conventional HTTP
requests.
All of the functionality that you are familiar with in the DigitalOcean
control panel is also available through the API, allowing you to script the
complex actions that your situation requires.
The API documentation will start with a general overview about the design
and technology that has been implemented, followed by reference information
about specific endpoints.
## Requests
Any tool that is fluent in HTTP can communicate with the API simply by
requesting the correct URI. Requests should be made using the HTTPS protocol
so that traffic is encrypted. The interface responds to different methods
depending on the action required.
|Method|Usage|
|--- |--- |
|GET|For simple retrieval of information about your account, Droplets, or
environment, you should use the GET method. The information you request
will be returned to you as a JSON object. The attributes defined by the JSON
object can be used to form additional requests. Any request using the GET
method is read-only and will not affect any of the objects you are
querying.|
|DELETE|To destroy a resource and remove it from your account and
environment, the DELETE method should be used. This will remove the
specified object if it is found. If it is not found, the operation will
return a response indicating that the object was not found. This idempotency
means that you do not have to check for a resource's availability prior to
issuing a delete command, the final state will be the same regardless of its
existence.|
|PUT|To update the information about a resource in your account, the PUT
method is available. Like the DELETE Method, the PUT method is idempotent.
It sets the state of the target using the provided values, regardless of
their current values. Requests using the PUT method do not need to check the
current attributes of the object.|
|PATCH|Some resources support partial modification. In these cases, the
PATCH method is available. Unlike PUT which generally requires a complete
representation of a resource, a PATCH request is a set of instructions on
how to modify a resource updating only specific attributes.|
|POST|To create a new object, your request should specify the POST method.
The POST request includes all of the attributes necessary to create a new
object. When you wish to create a new object, send a POST request to the
target endpoint.|
|HEAD|Finally, to retrieve metadata information, you should use the HEAD
method to get the headers. This returns only the header of what would be
returned with an associated GET request. Response headers contain some
useful information about your API access and the results that are available
for your request. For instance, the headers contain your current rate-limit
value and the amount of time available until the limit resets. It also
contains metrics about the total number of objects found, pagination
information, and the total content length.|
## HTTP Statuses
Along with the HTTP methods that the API responds to, it will also return
standard HTTP statuses, including error codes.
In the event of a problem, the status will contain the error code, while the
body of the response will usually contain additional information about the
problem that was encountered.
In general, if the status returned is in the 200 range, it indicates that
the request was fulfilled successfully and that no error was encountered.
Return codes in the 400 range typically indicate that there was an issue
with the request that was sent. Among other things, this could mean that you
did not authenticate correctly, that you are requesting an action that you
do not have authorization for, that the object you are requesting does not
exist, or that your request is malformed.
If you receive a status in the 500 range, this generally indicates a
server-side problem. This means that we are having an issue on our end and
cannot fulfill your request currently.
400 and 500 level error responses will include a JSON object in their body,
including the following attributes:
|Name|Type|Description|
|--- |--- |--- |
|id|string|A short identifier corresponding to the HTTP status code
returned. For example, the ID for a response returning a 404 status code
would be "not_found."|
|message|string|A message providing additional information about the error,
including details to help resolve it when possible.|
|request_id|string|Optionally, some endpoints may include a request ID that
should be provided when reporting bugs or opening support tickets to help
identify the issue.|
### Example Error Response
```
HTTP/1.1 403 Forbidden
{
"id": "forbidden",
"message": "You do not have access for the attempted action."
}
```
## Responses
When a request is successful, a response body will typically be sent back in
the form of a JSON object. An exception to this is when a DELETE request is
processed, which will result in a successful HTTP 204 status and an empty
response body.
Inside of this JSON object, the resource root that was the target of the
request will be set as the key. This will be the singular form of the word
if the request operated on a single object, and the plural form of the word
if a collection was processed.
For example, if you send a GET request to `/v2/droplets/$DROPLET_ID` you
will get back an object with a key called "`droplet`". However, if you send
the GET request to the general collection at `/v2/droplets`, you will get
back an object with a key called "`droplets`".
The value of these keys will generally be a JSON object for a request on a
single object and an array of objects for a request on a collection of
objects.
### Response for a Single Object
```json
{
"droplet": {
"name": "example.com"
. . .
}
}
```
### Response for an Object Collection
```json
{
"droplets": [
{
"name": "example.com"
. . .
},
{
"name": "second.com"
. . .
}
]
}
```
## Meta
In addition to the main resource root, the response may also contain a
`meta` object. This object contains information about the response itself.
The `meta` object contains a `total` key that is set to the total number of
objects returned by the request. This has implications on the `links` object
and pagination.
The `meta` object will only be displayed when it has a value. Currently, the
`meta` object will have a value when a request is made on a collection (like
`droplets` or `domains`).
### Sample Meta Object
```json
{
. . .
"meta": {
"total": 43
}
. . .
}
```
## Links & Pagination
The `links` object is returned as part of the response body when pagination
is enabled. By default, 20 objects are returned per page. If the response
contains 20 objects or fewer, no `links` object will be returned. If the
response contains more than 20 objects, the first 20 will be returned along
with the `links` object.
You can request a different pagination limit or force pagination by
appending `?per_page=` to the request with the number of items you would
like per page. For instance, to show only two results per page, you could
add `?per_page=2` to the end of your query. The maximum number of results
per page is 200.
The `links` object contains a `pages` object. The `pages` object, in turn,
contains keys indicating the relationship of additional pages. The values of
these are the URLs of the associated pages. The keys will be one of the
following:
* **first**: The URI of the first page of results.
* **prev**: The URI of the previous sequential page of results.
* **next**: The URI of the next sequential page of results.
* **last**: The URI of the last page of results.
The `pages` object will only include the links that make sense. So for the
first page of results, no `first` or `prev` links will ever be set. This
convention holds true in other situations where a link would not make sense.
### Sample Links Object
```json
{
. . .
"links": {
"pages": {
"last": "https://api.digitalocean.com/v2/images?page=2",
"next": "https://api.digitalocean.com/v2/images?page=2"
}
}
. . .
}
```
## Rate Limit
Requests through the API are rate limited per OAuth token. Current rate
limits:
* 5,000 requests per hour
* 250 requests per minute (5% of the hourly total)
Once you exceed either limit, you will be rate limited until the next cycle
starts. Space out any requests that you would otherwise issue in bursts for
the best results.
The rate limiting information is contained within the response headers of
each request. The relevant headers are:
* **ratelimit-limit**: The number of requests that can be made per hour.
* **ratelimit-remaining**: The number of requests that remain before you
hit your request limit. See the information below for how the request limits
expire.
* **ratelimit-reset**: This represents the time when the oldest request
will expire. The value is given in [Unix epoch
time](http://en.wikipedia.org/wiki/Unix_time). See below for more
information about how request limits expire.
More rate limiting information is returned only within burst limit error
response headers:
* **retry-after**: The number of seconds to wait before making another
request when rate limited.
As long as the `ratelimit-remaining` count is above zero, you will be able
to make additional requests.
The way that a request expires and is removed from the current limit count
is important to understand. Rather than counting all of the requests for an
hour and resetting the `ratelimit-remaining` value at the end of the hour,
each request instead has its own timer.
This means that each request contributes toward the `ratelimit-remaining`
count for one complete hour after the request is made. When that request's
timer runs out, it is no longer counted towards the request limit.
This has implications on the meaning of the `ratelimit-reset` header as
well. Because the entire rate limit is not reset at one time, the value of
this header is set to the time when the _oldest_ request will expire.
Keep this in mind if you see your `ratelimit-reset` value change, but not
move an entire hour into the future.
If the `ratelimit-remaining` reaches zero, subsequent requests will receive
a 429 error code until the request reset has been reached.
`ratelimit-remaining` reaching zero can also indicate that the "burst limit"
of 250
requests per minute limit was met, even if the 5,000 requests per hour limit
was not.
In this case, the 429 error response will include a `retry-after` header to
indicate how
long to wait (in seconds) until the request may be retried.
You can see the format of the response in the examples.
**Note:** The following endpoints have special rate limit requirements that
are independent of the limits defined above.
* Only 12 `POST` requests to the `/v2/floating_ips` endpoint to create
Floating IPs can be made per 60 seconds.
* Only 10 `GET` requests to the `/v2/account/keys` endpoint to list SSH
keys can be made per 60 seconds.
* Only 5 requests to any and all `v2/cdn/endpoints` can be made per 10
seconds. This includes `v2/cdn/endpoints`,
`v2/cdn/endpoints/$ENDPOINT_ID`, and `v2/cdn/endpoints/$ENDPOINT_ID/cache`.
* Only 50 strings within the `files` json struct in the
`v2/cdn/endpoints/$ENDPOINT_ID/cache`
[payload](https://docs.digitalocean.com/reference/api/api-reference/#operation/cdn_purge_cache)
can be requested every 20 seconds.
### Sample Rate Limit Headers
```
. . .
ratelimit-limit: 1200
ratelimit-remaining: 1193
rateLimit-reset: 1402425459
. . .
```
### Sample Rate Limit Headers When Burst Limit is Reached:
```
. . .
ratelimit-limit: 5000
ratelimit-remaining: 0
rateLimit-reset: 1402425459
retry-after: 29
. . .
```
### Sample Rate Exceeded Response
```
429 Too Many Requests
{
id: "too_many_requests",
message: "API Rate limit exceeded."
}
```
## Curl Examples
Throughout this document, some example API requests will be given using the
`curl` command. This will allow us to demonstrate the various endpoints in a
simple, textual format.
These examples assume that you are using a Linux or macOS command line. To run
these commands on a Windows machine, you can either use cmd.exe, PowerShell,
or WSL:
* For cmd.exe, use the `set VAR=VALUE`
[syntax](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1)
to define environment variables, call them with `%VAR%`, then replace all
backslashes (`\`) in the examples with carets (`^`).
* For PowerShell, use the `$Env:VAR = "VALUE"`
[syntax](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7.2)
to define environment variables, call them with `$Env:VAR`, then replace
`curl` with `curl.exe` and all backslashes (`\`) in the examples with
backticks (`` ` ``).
* WSL is a compatibility layer that allows you to emulate a Linux terminal
on a Windows machine.
Install WSL with our [community
tutorial](https://www.digitalocean.com/community/tutorials/how-to-install-the-windows-subsystem-for-linux-2-on-microsoft-windows-10),
then follow this API documentation normally.
The names of account-specific references (like Droplet IDs, for instance)
will be represented by variables. For instance, a Droplet ID may be
represented by a variable called `$DROPLET_ID`. You can set the associated
variables in your environment if you wish to use the examples without
modification.
The first variable that you should set to get started is your OAuth
authorization token. The next section will go over the details of this, but
you can set an environmental variable for it now.
Generate a token by going to the [Apps &
API](https://cloud.digitalocean.com/settings/applications)
section of the DigitalOcean control panel. Use an existing token if you have
saved one, or generate a new token with the "Generate new token" button.
Copy the generated token and use it to set and export the TOKEN variable in
your environment as the example shows.
You may also wish to set some other variables now or as you go along. For
example, you may wish to set the `DROPLET_ID` variable to one of your
Droplet IDs since this will be used frequently in the API.
If you are following along, make sure you use a Droplet ID that you control
so that your commands will execute correctly.
If you need access to the headers of a response through `curl`, you can pass
the `-i` flag to display the header information along with the body. If you
are only interested in the header, you can instead pass the `-I` flag, which
will exclude the response body entirely.
### Set and Export your OAuth Token
```
export DIGITALOCEAN_TOKEN=your_token_here
```
### Set and Export a Variable
```
export DROPLET_ID=1111111
```
## Parameters
There are two different ways to pass parameters in a request with the API.
When passing parameters to create or update an object, parameters should be
passed as a JSON object containing the appropriate attribute names and
values as key-value pairs. When you use this format, you should specify that
you are sending a JSON object in the header. This is done by setting the
`Content-Type` header to `application/json`. This ensures that your request
is interpreted correctly.
When passing parameters to filter a response on GET requests, parameters can
be passed using standard query attributes. In this case, the parameters
would be embedded into the URI itself by appending a `?` to the end of the
URI and then setting each attribute with an equal sign. Attributes can be
separated with a `&`. Tools like `curl` can create the appropriate URI when
given parameters and values; this can also be done using the `-F` flag and
then passing the key and value as an argument. The argument should take the
form of a quoted string with the attribute being set to a value with an
equal sign.
### Pass Parameters as a JSON Object
```
curl -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "example.com", "ip_address": "127.0.0.1"}' \
-X POST "https://api.digitalocean.com/v2/domains"
```
### Pass Filter Parameters as a Query String
```
curl -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
-X GET \
"https://api.digitalocean.com/v2/images?private=true"
```
## Cross Origin Resource Sharing
In order to make requests to the API from other domains, the API implements
Cross Origin Resource Sharing (CORS) support.
CORS support is generally used to create AJAX requests outside of the domain
that the request originated from. This is necessary to implement projects
like control panels utilizing the API. This tells the browser that it can
send requests to an outside domain.
The procedure that the browser initiates in order to perform these actions
(other than GET requests) begins by sending a "preflight" request. This sets
the `Origin` header and uses the `OPTIONS` method. The server will reply
back with the methods it allows and some of the limits it imposes. The
client then sends the actual request if it falls within the allowed
constraints.
This process is usually done in the background by the browser, but you can
use curl to emulate this process using the example provided. The headers
that will be set to show the constraints are:
* **Access-Control-Allow-Origin**: This is the domain that is sent by the
client or browser as the origin of the request. It is set through an
`Origin` header.
* **Access-Control-Allow-Methods**: This specifies the allowed options for
requests from that domain. This will generally be all available methods.
* **Access-Control-Expose-Headers**: This will contain the headers that
will be available to requests from the origin domain.
* **Access-Control-Max-Age**: This is the length of time that the access
is considered valid. After this expires, a new preflight should be sent.
* **Access-Control-Allow-Credentials**: This will be set to `true`. It
basically allows you to send your OAuth token for authentication.
You should not need to be concerned with the details of these headers,
because the browser will typically do all of the work for you.
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
contact:
name: DigitalOcean API Team
email: [email protected]
termsOfService: https://www.digitalocean.com/legal/terms-of-service-agreement/
servers:
- url: https://api.digitalocean.com
description: production
tags:
- name: 1-Click Applications
description: >-
1-Click applications are pre-built Droplet images or Kubernetes apps with
software,
features, and configuration details already set up for you. They can be
found in the
[DigitalOcean Marketplace](https://marketplace.digitalocean.com/).
- name: Account
description: Provides information about your current account.
- name: Actions
description: >-
Actions are records of events that have occurred on the resources in your
account.
These can be things like rebooting a Droplet, or transferring an image to
a new region.
An action object is created every time one of these actions is initiated.
The action
object contains information about the current status of the action, start
and complete
timestamps, and the associated resource type and ID.
Every action that creates an action object is available through this
endpoint. Completed
actions are not removed from this list and are always available for
querying.
**Note:** You can pass the following HTTP header with the request to have
the API return
the `reserved_ips` stanza instead of the `floating_ips` stanza:
- `Accept: application/vnd.digitalocean.reserveip+json`
- name: Apps
description: >-
App Platform is a Platform-as-a-Service (PaaS) offering from DigitalOcean
that allows
developers to publish code directly to DigitalOcean servers without
worrying about the
underlying infrastructure.
Most API operations are centered around a few core object types. Following
are the
definitions of these types. These definitions will be omitted from the
operation-specific
documentation.
For documentation on app specifications (`AppSpec` objects), please refer
to the
[product
documentation](https://docs.digitalocean.com/products/app-platform/reference/app-spec/)).
- name: Billing
description: >-
The billing endpoints allow you to retrieve your account balance, invoices
and billing history.
**Balance:** By sending requests to the `/v2/customers/my/balance`
endpoint, you can
retrieve the balance information for the requested customer account.
**Invoices:**
[Invoices](https://docs.digitalocean.com/platform/billing/invoices/)
are generated on the first of each month for every DigitalOcean
customer. An invoice preview is generated daily, which can be accessed
with the `preview` keyword in place of `$INVOICE_UUID`. To interact with
invoices, you will generally send requests to the invoices endpoint at
`/v2/customers/my/invoices`.
**Billing History:** Billing history is a record of billing events for
your account.
For example, entries may include events like payments made, invoices
issued, or credits granted. To interact with invoices, you
will generally send requests to the invoices endpoint at
`/v2/customers/my/billing_history`.
- name: Block Storage
description: >-
[DigitalOcean Block Storage
Volumes](https://docs.digitalocean.com/products/volumes/)
provide expanded storage capacity for your Droplets and can be moved
between Droplets within a specific region.
Volumes function as raw block devices, meaning they appear to the
operating system as locally attached storage which can be formatted using
any file system supported by the OS. They may be created in sizes from
1GiB to 16TiB.
By sending requests to the `/v2/volumes` endpoint, you can list, create,
or
delete volumes as well as attach and detach them from Droplets
- name: Block Storage Actions
description: |-
Block storage actions are commands that can be given to a DigitalOcean
Block Storage Volume. An example would be detaching or attaching a volume
from a Droplet. These requests are made on the
`/v2/volumes/$VOLUME_ID/actions` endpoint.
An action object is returned. These objects hold the current status of the
requested action.
- name: CDN Endpoints
description: |-
Content hosted in DigitalOcean's object storage solution,
[Spaces](https://docs.digitalocean.com/products/spaces/),
can optionally be served by our globally distributed Content Delivery
Network (CDN). By sending requests to `/v2/cdn/endpoints`, you can list,
create, or delete CDN Endpoints as well as purge cached content. To use a
custom subdomain to access the CDN Endpoint, provide the ID of a
DigitalOcean managed TLS certificate and the fully qualified domain name
for the custom subdomain.
CDN endpoints have a rate limit of five requests per 10 seconds.
- name: Certificates
description: >-
In order to perform SSL termination on load balancers, DigitalOcean offers
two types of [SSL certificate
management](https://docs.digitalocean.com/platform/teams/manage-certificates):
* **Custom**: User-generated certificates may be uploaded to DigitalOcean
where they will be placed in a fully encrypted and isolated storage
system.
* **Let's Encrypt**: Certificates may be automatically generated by
DigitalOcean utilizing an integration with Let's Encrypt, the free and
open certificate authority. These certificates will also be automatically
renewed as required.
- name: Container Registry
description: >-
DigitalOcean offers the ability for you to create a
[private container
registry](https://docs.digitalocean.com/products/container-registry/)
to store your Docker images for use with your Kubernetes clusters. This
container registry runs inside the same datacenters as your cluster,
ensuring reliable and performant rollout of image deployments.
You can only create one registry per DigitalOcean account, but you can use
that registry to create as many repositories as you wish.
- name: Databases
description: >-
DigitalOcean's [managed database
service](https://docs.digitalocean.com/products/databases)
simplifies the creation and management of highly available database
clusters. Currently, it
offers support for
[PostgreSQL](http://docs.digitalocean.com/products/databases/postgresql/),
[Redis](https://docs.digitalocean.com/products/databases/redis/),
[MySQL](https://docs.digitalocean.com/products/databases/mysql/),
[MongoDB](https://docs.digitalocean.com/products/databases/mongodb/), and
[OpenSearch](https://docs.digitalocean.com/products/databases/opensearch/).
By sending requests to the `/v2/databases` endpoint, you can list, create,
or delete
database clusters as well as scale the size of a cluster, add or remove
read-only replicas,
and manage other configuration details.
Database clusters may be deployed in a multi-node, high-availability
configuration.
If your machine type is above the basic nodes, your node plan is above the
smallest option,
or you are running MongoDB, you may additionally include up to two standby
nodes in your cluster.
The size of individual nodes in a database cluster is represented by a
human-readable slug,
which is used in some of the following requests. Each slug denotes the
node's identifier,
CPU count, and amount of RAM, in that order.
For a list of currently available database slugs and options, use the
`/v2/databases/options` endpoint or use the
`doctl databases options`
[command](https://docs.digitalocean.com/reference/doctl/reference/databases/options).
- name: Domain Records
description: >-
Domain record resources are used to set or retrieve information about the
individual DNS records configured for a domain. This allows you to build
and manage DNS zone files by adding and modifying individual records for a
domain.
The [DigitalOcean DNS management
interface](https://docs.digitalocean.com/products/networking/dns/)
allows you to configure the following DNS records:
Name |
Description
|
------|----------------------------------------------------------------------------------------------------------------------------------------------------|
A | This record type is used to map an IPv4 address to a
hostname.
|
AAAA | This record type is used to map an IPv6 address to a
hostname.
|
CAA | As specified in RFC-6844, this record type can be used to restrict
which certificate authorities are permitted to issue certificates for a
domain. |
CNAME | This record type defines an alias for your canonical hostname (the
one defined by an A or AAAA
record). |
MX | This record type is used to define the mail exchanges used for the
domain.
|
NS | This record type defines the name servers that are used for this
zone.
|
TXT | This record type is used to associate a string of text with a
hostname, primarily used for
verification. |
SRV | This record type specifies the location (hostname and port number)
of servers for specific
services. |
SOA | This record type defines administrative information about the
zone. Can only have ttl changed, cannot be
deleted |
- name: Domains
description: >-
Domain resources are domain names that you have purchased from a domain
name registrar that you are managing through the
[DigitalOcean DNS
interface](https://docs.digitalocean.com/products/networking/dns/).
This resource establishes top-level control over each domain. Actions that
affect individual domain records should be taken on the
[Domain Records](#tag/Domain-Records) resource.
- name: Droplet Actions
description: |-
Droplet actions are tasks that can be executed on a Droplet. These can be
things like rebooting, resizing, snapshotting, etc.
Droplet action requests are generally targeted at one of the "actions"
endpoints for a specific Droplet. The specific actions are usually
initiated by sending a POST request with the action and arguments as
parameters.
Droplet action requests create a Droplet actions object, which can be used
to get information about the status of an action. Creating a Droplet
action is asynchronous: the HTTP call will return the action object before
the action has finished processing on the Droplet. The current status of
an action can be retrieved from either the Droplet actions endpoint or the
global actions endpoint. If a Droplet action is uncompleted it may block
the creation of a subsequent action for that Droplet, the locked attribute
of the Droplet will be true and attempts to create a Droplet action will
fail with a status of 422.
- name: Droplets
description: >-
A [Drop
# --- truncated at 32 KB (1762 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/digital-ocean/refs/heads/main/openapi/digital-ocean-openapi-original.yml