API v2 Introduction

Welcome to the DigitalOcean API documentation.

The DigitalOcean API allows you to manage Droplets and resources within the DigitalOcean cloud in a simple, programmatic way using conventional HTTP requests. The endpoints are intuitive and powerful, allowing you to easily make calls to retrieve information or to execute actions.

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 patial modification. In these cases, the PATCH method is available.

Unlike PUT which generally requires a complete representation of a resource, a PATCH request is 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.

HTTP Statuses

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.

Responses

Response for a Single Object

{
    "droplet": {
        "name": "example.com"
        . . .
    }
}

Response for an Object Collection

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

Meta

Sample Meta Object

{
    . . .
    "meta": {
        "total": 43
    }
    . . .
}

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. See below for more information about how request limits expire.

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

Rate Limit

Sample Rate Limit Headers

. . .
RateLimit-Limit: 1200
RateLimit-Remaining: 1193
RateLimit-Reset: 1402425459
. . .

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.

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

Curl Examples

Set and Export your OAuth Token

export TOKEN=your_token_here

Set and Export a Variable

export DROPLET_ID=1111111

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 in full or in read-only mode.

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.

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.

OAuth Authentication

Authenticate with a Bearer Authorization Header

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

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.

Parameters

Pass Parameters as a JSON Object

curl -H "Authorization: Bearer $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 $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.

Cross Origin Resource Sharing

Example Preflight Request

curl -I -H "Origin: https://example.com" -X OPTIONS "https://api.digitalocean.com/v2/droplets"

Example Preflight Response

. . .
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Expose-Headers: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Total, Link
Access-Control-Max-Age: 86400
Access-Control-Allow-Credentials: true
. . .

1-Click Applications

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.

NameTypeDescription
slugstringThe slug identifier for the 1-Click application.
typestringThe type of the 1-Click application.

Install Kubernetes 1-Click Applications

To install a Kubernetes 1-Click application on a cluster, send a POST request to /v2/1-clicks/kubernetes. The addon_slugs and cluster_uuid must be provided as body parameter in order to specify which 1-Click application(s) to install. To list all available 1-Click Kubernetes applications, send a request to /v2/1-clicks?type=kubernetes.

NameTypeDescription
addon_slugsarrayAn array of 1-Click Application slugs to be installed to the Kubernetes cluster.
cluster_uuidstringA unique ID for the Kubernetes cluster to which the 1-Click Applications will be installed.

The response will verify that a job has been successfully created to install a 1-Click. The post-installation lifecycle of a 1-Click application can not be managed via the DigitalOcean API. For additional details specific to the 1-Click, find and view its DigitalOcean Marketplace page.

NameTypeDescription
messagestringA message about the result of the request.

Install Kubernetes 1-Click Applications

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d "{\"addon_slugs\": [\"kube-state-metrics\", \"loki\"], \"cluster_uuid\": \"50a994b6-c303-438f-9495-7e896cfe6b08\"}" "https://api.digitalocean.com/v2/1-clicks/kubernetes"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "addon_slugs": [
    "kube-state-metrics",
    "loki"
  ],
  "cluster_uuid": "50a994b6-c303-438f-9495-7e896cfe6b08"
}

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Response Body

{
  "message": "Successfully kicked off addon job."
}

List 1-Click Applications

To list all available 1-Click applications, send a GET request to /v2/1-clicks. The type may be provided as query paramater in order to restrict results to a certain type of 1-Click, for example: /v2/1-clicks?type=droplet. Current supported types are kubernetes and droplet.

The response will be a JSON object with a key called 1_clicks. This will be set to an array of 1-Click application data, each of which will contain the the slug and type for the 1-Click.

NameTypeDescription
slugstringThe slug identifier for the 1-Click application.
typestringThe type of the 1-Click application.

List 1-Click Applications

cURL Example

curl -X GET -H "Content-Type: application/json"  -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/1-clicks"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Response Body

{"1_clicks": [{"slug": "monitoring", "type": "kubernetes"}, {"slug": "wordpress-18-04", "type": "droplet"}, ...]}

Account

By sending requests to the /v2/account endpoint, you can retrieve information about your current account.

NameTypeDescription
droplet_limitintegerThe total number of Droplets the current user or team may have at one time.
floating_ip_limitintegerThe total number of floating IPs the current user or team may have.
volume_limitintegerThe total number of volumes the current user or team may have.
emailstringThe email address used by the current user to register for DigitalOcean.
uuidstringThe unique universal identifier for the current user.
email_verifiedbooleanIf true, the user has verified their account via email. False otherwise.
statusstringThis value is one of "active", "warning" or "locked".
status_messagestringA human-readable message giving more details about the status of the account.

Get User Information

To show information about the current user's account, send a GET request to /v2/account.

The response will be a JSON object with a key called account. This will be set to a JSON object that contains the following attributes:

NameTypeDescription
droplet_limitintegerThe total number of Droplets the current user or team may have at one time.
floating_ip_limitintegerThe total number of floating IPs the current user or team may have.
volume_limitintegerThe total number of volumes the current user or team may have.
emailstringThe email address used by the current user to register for DigitalOcean.
uuidstringThe unique universal identifier for the current user.
email_verifiedbooleanIf true, the user has verified their account via email. False otherwise.
statusstringThis value is one of "active", "warning" or "locked".
status_messagestringA human-readable message giving more details about the status of the account.

Get User Information

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/account"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.account.info

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

account, _, err := client.Account.Get(ctx)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1137
ratelimit-reset: 1415984218

Response Body

{
  "account": {
    "droplet_limit": 25,
    "floating_ip_limit": 5,
    "volume_limit": 10,
    "email": "sammy@digitalocean.com",
    "uuid": "b6fr89dbf6d9156cace5f3c78dc9851d957381ef",
    "email_verified": true,
    "status": "active",
    "status_message": ""
  }
}

Actions

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.

NameTypeDescription
idintegerA unique numeric ID that can be used to identify and reference an action.
statusstringThe current status of the action. This can be "in-progress", "completed", or "errored".
typestringThis is the type of action that the object represents. For example, this could be "transfer" to represent the state of an image transfer action.
started_atstringA time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_atstringA time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_idintegerA unique identifier for the resource that the action is associated with.
resource_typestringThe type of resource that the action is associated with.
regionobjectA full region object containing information about the region where the action occurred.
region_slugnullable stringA slug representing the region where the action occurred.

List All Actions

To list all of the actions that have been executed on the current account, send a GET request to /v2/actions.

This will be the entire list of actions taken on your account, so it will be quite large. As with any large collection returned by the API, the results will be paginated with only 20 on each page by default.

The results will be returned as a JSON object with an actions key. This will be set to an array filled with action objects containing the standard action attributes:

NameTypeDescription
idintegerA unique numeric ID that can be used to identify and reference an action.
statusstringThe current status of the action. This can be "in-progress", "completed", or "errored".
typestringThis is the type of action that the object represents. For example, this could be "transfer" to represent the state of an image transfer action.
started_atstringA time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_atstringA time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_idintegerA unique identifier for the resource that the action is associated with.
resource_typestringThe type of resource that the action is associated with.
regionobjectA full region object containing information about the region where the action occurred.
region_slugnullable stringA slug representing the region where the action occurred.

List All Actions

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/actions?page=1&per_page=1"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

actions = client.actions.all
actions.each

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

opt := &godo.ListOptions{
    Page:    1,
    PerPage: 200,
}
actions, _, err := client.Actions.List(ctx, opt)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1124
ratelimit-reset: 1415984218

Response Body

{
  "actions": [
    {
      "id": 36804636,
      "status": "completed",
      "type": "create",
      "started_at": "2014-11-14T16:29:21Z",
      "completed_at": "2014-11-14T16:30:06Z",
      "resource_id": 3164444,
      "resource_type": "droplet",
      "region": {
        "name": "New York 3",
        "slug": "nyc3",
        "sizes": [
          "s-1vcpu-3gb",
          "m-1vcpu-8gb",
          "s-3vcpu-1gb",
          "s-1vcpu-2gb",
          "s-2vcpu-2gb",
          "s-2vcpu-4gb",
          "s-4vcpu-8gb",
          "s-6vcpu-16gb",
          "s-8vcpu-32gb",
          "s-12vcpu-48gb",
          "s-16vcpu-64gb",
          "s-20vcpu-96gb",
          "s-1vcpu-1gb",
          "c-1vcpu-2gb",
          "s-24vcpu-128gb"
        ],
        "features": [
          "private_networking",
          "backups",
          "ipv6",
          "metadata",
          "server_id",
          "install_agent",
          "storage",
          "image_transfer"
        ],
        "available": true
      },
      "region_slug": "nyc3"
    }
  ],
  "links": {
    "pages": {
      "last": "https://api.digitalocean.com/v2/actions?page=159&per_page=1",
      "next": "https://api.digitalocean.com/v2/actions?page=2&per_page=1"
    }
  },
  "meta": {
    "total": 159
  }
}

Retrieve an Existing Action

To retrieve a specific action object, send a GET request to /v2/actions/$ACTION_ID.

The result will be a JSON object with an action key. This will be set to an action object containing the standard action attributes:

NameTypeDescription
idintegerA unique numeric ID that can be used to identify and reference an action.
statusstringThe current status of the action. This can be "in-progress", "completed", or "errored".
typestringThis is the type of action that the object represents. For example, this could be "transfer" to represent the state of an image transfer action.
started_atstringA time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_atstringA time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_idintegerA unique identifier for the resource that the action is associated with.
resource_typestringThe type of resource that the action is associated with.
regionobjectA full region object containing information about the region where the action occurred.
region_slugnullable stringA slug representing the region where the action occurred.

Retrieve an Existing Action

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/actions/36804636"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.actions.find(id: 36804636)

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

action, _, err := client.Actions.Get(ctx, 36804636)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1123
ratelimit-reset: 1415984218

Response Body

{
  "action": {
    "id": 36804636,
    "status": "completed",
    "type": "create",
    "started_at": "2014-11-14T16:29:21Z",
    "completed_at": "2014-11-14T16:30:06Z",
    "resource_id": 3164444,
    "resource_type": "droplet",
    "region": {
      "name": "New York 3",
      "slug": "nyc3",
      "sizes": [
        "s-1vcpu-3gb",
        "m-1vcpu-8gb",
        "s-3vcpu-1gb",
        "s-1vcpu-2gb",
        "s-2vcpu-2gb",
        "s-2vcpu-4gb",
        "s-4vcpu-8gb",
        "s-6vcpu-16gb",
        "s-8vcpu-32gb",
        "s-12vcpu-48gb",
        "s-16vcpu-64gb",
        "s-20vcpu-96gb",
        "s-1vcpu-1gb",
        "c-1vcpu-2gb",
        "s-24vcpu-128gb"
      ],
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata",
        "server_id",
        "install_agent",
        "storage",
        "image_transfer"
      ],
      "available": true
    },
    "region_slug": "nyc3"
  }
}

Apps

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.

The standard attributes of App objects are:

NameTypeDescription
idstringThe ID of the application
owner_uuidstringThe ID of the account to which the application belongs
specAppSpec objectThe latest app specification
default_ingressstringThe default hostname on which the app is accessible
created_atstringThe creation time of the app
updated_atstringTime of the app's last configuration update
active_deploymentDeployment objectThe current active deployment
in_progress_deploymentDeployment objectThe current in-progress deployment
last_deployment_created_atstringThe creation time of the last deployment
live_urlstringThe live URL of the app
regionRegion objectGeographical information about the app origin
tier_slugstringThe current pricing tier slug of the app
live_url_basestringThe live URL base of the app, the URL excluding the path
live_domainstringThe live domain of the app

The standard attributes of Deployment objects are:

NameTypeDescription
idstringThe ID of the deployment
specAppSpec objectThe app specification of this specific deployment
servicesDeploymentService arrayService components that are part of this deployment
static_sitesDeploymentStaticSite arrayStatic Site components that are part of this deployment
workersDeploymentWorker arrayWorker components that are part of this deployment
jobsDeploymentJob arrayJob components that are part of this deployment
phase_last_updated_atstringWhen the deployment phase was last updated
created_atstringThe creation time of the deployment
updated_atstringWhen the deployment was last updated
causestringWhat caused this deployment to be created
cloned_fromstringThe ID of a previous deployment that this deployment was cloned from
progressDeploymentProgress objectInformation about this deployment's progress
phasestringThe current phase of the deployment
tier_slugstringThe current pricing tier slug of the deployment

The standard attributes of DeploymentService objects are:

NameTypeDescription
namestringThe name of this service
imagestringThe image that this service uses
source_commit_hashstringThe commit hash of the repository that was used to build this service

The standard attributes of DeploymentStaticSite objects are:

NameTypeDescription
namestringThe name of this static site
source_commit_hashstringThe commit hash of the repository that was used to build this static site

The standard attributes of DeploymentWorker objects are:

NameTypeDescription
namestringThe name of this worker
imagestringThe image that this worker uses
source_commit_hashstringThe commit hash of the repository that was used to build this worker

The standard attributes of DeploymentJob objects are:

NameTypeDescription
namestringThe name of this job
imagestringThe image that this job uses
source_commit_hashstringThe commit hash of the repository that was used to build this job

The standard attributes of DeploymentProgress objects are:

NameTypeDescription
pending_stepsintegerNumber of pending steps
running_stepsintegerNumber of currently running steps
success_stepsintegerNumber of successful steps
error_stepsintegerNumber of unsuccessful steps
total_stepsintegerTotal number of steps
stepsProgressStep arrayThe deployment's steps
summary_stepsProgressStep arrayA flattened summary of the steps

The standard attributes of ProgressStep objects are:

NameTypeDescription
namestringThe name of this step
statusstringThe current status of this step - `PENDING`: Pending - `RUNNING`: Running - `ERROR`: Error - `SUCCESS`: Success
stepsProgressStep arrayChild steps that constitute this step
started_atstringThe start time of this step
ended_atstringThe end time of this step
reasonStepReason objectThe reason behind this step's status
component_namestringThe component name that this step is associated with
message_basestringThe base of a human-readable description of the step intended to be combined with the component name for presentation. For example: `message_base` = "Building service" `component_name` = "api"

The standard attributes of StepReason objects are:

NameTypeDescription
codestringThe error code
messagestringThe error message

The standard attributes of Region objects are:

NameTypeDescription
slugstringThe slug form of the region name
labelstringA human-readable name of the region
flagstringThe flag of this region
continentstringThe continent that this region is in
disabledbooleanWhether or not the region is open for new apps
data_centersstring arrayData centers that are in this region
reasonstringReason that this region is not available
defaultbooleanWhether or not the region is presented as the default.

List All Apps

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

To run this operation, send a GET request to /v2/apps.

Response

The response will be a JSON object with a key called apps. This will be set to an array of app objects, each of which will contain the standard app attributes:

NameTypeDescriptionRequired
idstringThe ID of the applicationread-only
owner_uuidstringThe ID of the account to which the application belongsread-only
specAppSpec objectThe latest app specification
default_ingressstringThe default hostname on which the app is accessibleread-only
created_atstringThe creation time of the appread-only
updated_atstringTime of the app's last configuration updateread-only
active_deploymentDeployment objectThe current active deploymentread-only
in_progress_deploymentDeployment objectThe current in-progress deploymentread-only
last_deployment_created_atstringThe creation time of the last deploymentread-only
live_urlstringThe live URL of the appread-only
regionRegion objectGeographical information about the app originread-only
tier_slugstringThe current pricing tier slug of the appread-only
live_url_basestringThe live URL base of the app, the URL excluding the pathread-only
live_domainstringThe live domain of the appread-only

List All Apps

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/apps"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 838
ratelimit-reset: 1415984218

Response Body

{
  "apps": [
    {
      "id": "b7d64052-3706-4cb7-b21a-c5a2f44e63b3",
      "spec": {
        "name": "sample-golang",
        "services": [
          {
            "name": "web",
            "github": {
              "repo": "digitalocean/sample-golang",
              "branch": "branch"
            },
            "run_command": "bin/sample-golang",
            "environment_slug": "go",
            "instance_size_slug": "professional-xs",
            "instance_count": 2,
            "routes": [
              {
                "path": "/"
              }
            ]
          }
        ],
        "region": "ams3"
      },
      "default_ingress": "sample-golang.ondigitalocean.app",
      "created_at": "2020-07-28T18:00:00Z",
      "updated_at": "2020-07-28T18:00:00Z",
      "active_deployment": {
        "id": "b6bdf840-2854-4f87-a36c-5f231c617c84",
        "spec": {
          "name": "sample-golang",
          "services": [
            {
              "name": "web",
              "github": {
                "repo": "digitalocean/sample-golang",
                "branch": "branch"
              },
              "run_command": "bin/sample-golang",
              "environment_slug": "go",
              "instance_size_slug": "professional-xs",
              "instance_count": 2,
              "routes": [
                {
                  "path": "/"
                }
              ]
            }
          ],
          "region": "ams3"
        },
        "services": [
          {
            "name": "web",
            "source_commit_hash": "9a4df0b8e161e323bc3cdf1dc71878080fe144fa"
          }
        ],
        "cause": "commit 9a4df0b pushed to github/digitalocean/sample-golang",
        "progress": null,
        "created_at": "2020-07-28T18:00:00Z",
        "updated_at": "2020-07-28T18:00:00Z"
      }
    }
  ]
}

Retrieve an Existing App

Retrieve details about an existing app by either its ID or name. To retrieve an app by its name, do not include an ID in the request path. Information about the current active deployment as well as any in progress ones will also be included in the response.

To run this operation, send a GET request to /v2/apps/{id}.

Request

The attribute values that may be set in the path of this request are:

NameTypeDescriptionRequired
idstringThe ID of the app to retrieve. If set, the name field will be ignored.required

The attribute values that may be set in the query of this request are:

NameTypeDescription
namestringThe name of the app to retrieve.

Response

The response will be a JSON object with a key called app. This will be set to an app object which will contain the standard app attributes:

NameTypeDescriptionRequired
idstringThe ID of the applicationread-only
owner_uuidstringThe ID of the account to which the application belongsread-only
specAppSpec objectThe latest app specification
default_ingressstringThe default hostname on which the app is accessibleread-only
created_atstringThe creation time of the appread-only
updated_atstringTime of the app's last configuration updateread-only
active_deploymentDeployment objectThe current active deploymentread-only
in_progress_deploymentDeployment objectThe current in-progress deploymentread-only
last_deployment_created_atstringThe creation time of the last deploymentread-only
live_urlstringThe live URL of the appread-only
regionRegion objectGeographical information about the app originread-only
tier_slugstringThe current pricing tier slug of the appread-only
live_url_basestringThe live URL base of the app, the URL excluding the pathread-only
live_domainstringThe live domain of the appread-only

Retrieve an Existing App

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/apps/{id}"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 838
ratelimit-reset: 1415984218

Response Body

{
  "app": {
    "id": "b7d64052-3706-4cb7-b21a-c5a2f44e63b3",
    "spec": {
      "name": "sample-golang",
      "services": [
        {
          "name": "web",
          "github": {
            "repo": "digitalocean/sample-golang",
            "branch": "branch"
          },
          "run_command": "bin/sample-golang",
          "environment_slug": "go",
          "instance_size_slug": "professional-xs",
          "instance_count": 2,
          "routes": [
            {
              "path": "/"
            }
          ]
        }
      ],
      "region": "ams3"
    },
    "default_ingress": "sample-golang.ondigitalocean.app",
    "created_at": "2020-07-28T18:00:00Z",
    "updated_at": "2020-07-28T18:00:00Z",
    "active_deployment": {
      "id": "b6bdf840-2854-4f87-a36c-5f231c617c84",
      "spec": {
        "name": "sample-golang",
        "services": [
          {
            "name": "web",
            "github": {
              "repo": "digitalocean/sample-golang",
              "branch": "branch"
            },
            "run_command": "bin/sample-golang",
            "environment_slug": "go",
            "instance_size_slug": "professional-xs",
            "instance_count": 2,
            "routes": [
              {
                "path": "/"
              }
            ]
          }
        ],
        "region": "ams3"
      },
      "services": [
        {
          "name": "web",
          "source_commit_hash": "9a4df0b8e161e323bc3cdf1dc71878080fe144fa"
        }
      ],
      "cause": "commit 9a4df0b pushed to github/digitalocean/sample-golang",
      "progress": null,
      "created_at": "2020-07-28T18:00:00Z",
      "updated_at": "2020-07-28T18:00:00Z"
    }
  }
}

Create a New App

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

To run this operation, send a POST request to /v2/apps.

Request

The attribute values that may be set in the body of this request are:

NameTypeDescription
specAppSpec objectThe app specification to use for the new app

Response

The response will be a JSON object with a key called app. This will be set to an app object which will contain the standard app attributes:

NameTypeDescriptionRequired
idstringThe ID of the applicationread-only
owner_uuidstringThe ID of the account to which the application belongsread-only
specAppSpec objectThe latest app specification
default_ingressstringThe default hostname on which the app is accessibleread-only
created_atstringThe creation time of the appread-only
updated_atstringTime of the app's last configuration updateread-only
active_deploymentDeployment objectThe current active deploymentread-only
in_progress_deploymentDeployment objectThe current in-progress deploymentread-only
last_deployment_created_atstringThe creation time of the last deploymentread-only
live_urlstringThe live URL of the appread-only
regionRegion objectGeographical information about the app originread-only
tier_slugstringThe current pricing tier slug of the appread-only
live_url_basestringThe live URL base of the app, the URL excluding the pathread-only
live_domainstringThe live domain of the appread-only

Create a New App

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/apps"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "spec": {
    "name": "sample-golang",
    "services": [
      {
        "name": "web",
        "github": {
          "repo": "digitalocean/sample-golang",
          "branch": "branch"
        },
        "run_command": "bin/sample-golang",
        "environment_slug": "go",
        "instance_size_slug": "professional-xs",
        "instance_count": 2,
        "routes": [
          {
            "path": "/"
          }
        ]
      }
    ],
    "region": "ams3"
  }
}

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 838
ratelimit-reset: 1415984218

Response Body

{
  "app": {
    "id": "b7d64052-3706-4cb7-b21a-c5a2f44e63b3",
    "spec": {
      "name": "sample-golang",
      "services": [
        {
          "name": "web",
          "github": {
            "repo": "digitalocean/sample-golang",
            "branch": "branch"
          },
          "run_command": "bin/sample-golang",
          "environment_slug": "go",
          "instance_size_slug": "professional-xs",
          "instance_count": 2,
          "routes": [
            {
              "path": "/"
            }
          ]
        }
      ],
      "region": "ams3"
    },
    "default_ingress": "sample-golang.ondigitalocean.app",
    "created_at": "2020-07-28T18:00:00Z",
    "updated_at": "2020-07-28T18:00:00Z",
    "active_deployment": {
      "id": "b6bdf840-2854-4f87-a36c-5f231c617c84",
      "spec": {
        "name": "sample-golang",
        "services": [
          {
            "name": "web",
            "github": {
              "repo": "digitalocean/sample-golang",
              "branch": "branch"
            },
            "run_command": "bin/sample-golang",
            "environment_slug": "go",
            "instance_size_slug": "professional-xs",
            "instance_count": 2,
            "routes": [
              {
                "path": "/"
              }
            ]
          }
        ],
        "region": "ams3"
      },
      "services": [
        {
          "name": "web",
          "source_commit_hash": "9a4df0b8e161e323bc3cdf1dc71878080fe144fa"
        }
      ],
      "cause": "commit 9a4df0b pushed to github/digitalocean/sample-golang",
      "progress": null,
      "created_at": "2020-07-28T18:00:00Z",
      "updated_at": "2020-07-28T18:00:00Z"
    }
  }
}

Update an App

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

To run this operation, send a PUT request to /v2/apps/{id}.

Request

The attribute values that may be set in the body of this request are:

NameTypeDescription
specAppSpec objectThe new app specification to apply

The attribute values that may be set in the path of this request are:

NameTypeDescriptionRequired
idstringThe ID of the apprequired

Response

The response will be a JSON object with a key called app. This will be set to an app object which will contain the standard app attributes:

NameTypeDescriptionRequired
idstringThe ID of the applicationread-only
owner_uuidstringThe ID of the account to which the application belongsread-only
specAppSpec objectThe latest app specification
default_ingressstringThe default hostname on which the app is accessibleread-only
created_atstringThe creation time of the appread-only
updated_atstringTime of the app's last configuration updateread-only
active_deploymentDeployment objectThe current active deploymentread-only
in_progress_deploymentDeployment objectThe current in-progress deploymentread-only
last_deployment_created_atstringThe creation time of the last deploymentread-only
live_urlstringThe live URL of the appread-only
regionRegion objectGeographical information about the app originread-only
tier_slugstringThe current pricing tier slug of the appread-only
live_url_basestringThe live URL base of the app, the URL excluding the pathread-only
live_domainstringThe live domain of the appread-only

Update an App

cURL Example

curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/apps/{id}"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "spec": {
    "name": "sample-golang",
    "services": [
      {
        "name": "web",
        "github": {
          "repo": "digitalocean/sample-golang",
          "branch": "branch"
        },
        "run_command": "bin/sample-golang",
        "environment_slug": "go",
        "instance_size_slug": "professional-xs",
        "instance_count": 2,
        "routes": [
          {
            "path": "/"
          }
        ]
      }
    ],
    "region": "ams3"
  }
}

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 838
ratelimit-reset: 1415984218

Response Body

{
  "app": {
    "id": "b7d64052-3706-4cb7-b21a-c5a2f44e63b3",
    "spec": {
      "name": "sample-golang",
      "services": [
        {
          "name": "web",
          "github": {
            "repo": "digitalocean/sample-golang",
            "branch": "branch"
          },
          "run_command": "bin/sample-golang",
          "environment_slug": "go",
          "instance_size_slug": "professional-xs",
          "instance_count": 2,
          "routes": [
            {
              "path": "/"
            }
          ]
        }
      ],
      "region": "ams3"
    },
    "default_ingress": "sample-golang.ondigitalocean.app",
    "created_at": "2020-07-28T18:00:00Z",
    "updated_at": "2020-07-28T18:00:00Z",
    "active_deployment": {
      "id": "b6bdf840-2854-4f87-a36c-5f231c617c84",
      "spec": {
        "name": "sample-golang",
        "services": [
          {
            "name": "web",
            "github": {
              "repo": "digitalocean/sample-golang",
              "branch": "branch"
            },
            "run_command": "bin/sample-golang",
            "environment_slug": "go",
            "instance_size_slug": "professional-xs",
            "instance_count": 2,
            "routes": [
              {
                "path": "/"
              }
            ]
          }
        ],
        "region": "ams3"
      },
      "services": [
        {
          "name": "web",
          "source_commit_hash": "9a4df0b8e161e323bc3cdf1dc71878080fe144fa"
        }
      ],
      "cause": "commit 9a4df0b pushed to github/digitalocean/sample-golang",
      "progress": null,
      "created_at": "2020-07-28T18:00:00Z",
      "updated_at": "2020-07-28T18:00:00Z"
    }
  }
}

Delete an App

Delete an existing app. Once deleted, all active deployments will be permanently shut down and the app deleted. If needed, be sure to back up your app specification so that you may re-create it at a later time.

To run this operation, send a DELETE request to /v2/apps/{id}.

Request

The attribute values that may be set in the path of this request are:

NameTypeDescriptionRequired
idstringThe ID of the apprequired

Response

The response will be a JSON object that contains the following attributes:

NameTypeDescription
idstringThe ID of the app that was deleted

Delete an App

cURL Example

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/apps/{id}"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 838
ratelimit-reset: 1415984218

Response Body

{
  "id": "b7d64052-3706-4cb7-b21a-c5a2f44e63b3"
}

Run App Detection

Given a git repository, app detection will scan it for supported types of applications and return the first match. You can use this information to aid in the creation of app specifications.

You may specify either a branch in the source spec or a specific commit hash. Additionally, you may pass a preferred component type to target. For documentation on app specifications (AppSpec objects), please refer to the product documentation.

To run this operation, send a POST request to /v2/apps/detect.

Request

The attribute values that may be set in the body of this request are:

NameTypeDescription
gitGitSourceSpec objectA Git source to analyze. Only one of `git` and `github` must be set.
githubGitHubSourceSpec objectA GitHub source to analyze. Only one of `git` and `github` must be set.
commit_shastringAn optional commit hash to use instead of the branch specified in the source spec
component_typestringAn optional component type to target while running detection. Can be one of: `service`, `static_site`, `worker`, `job`.

The standard attributes of GitSourceSpec objects are:

NameTypeDescription
repo_clone_urlstringThe clone URL of the repo. Example: `https://github.com/digitalocean/sample-golang.git`
branchstringThe name of the branch to use

The standard attributes of GitHubSourceSpec objects are:

NameTypeDescription
repostringThe name of the repo in the format owner/repo. Example: `digitalocean/sample-golang`
branchstringThe name of the branch to use
deploy_on_pushbooleanWhether to automatically deploy new commits made to the repo

Response

The response will be a JSON object that contains the following attributes:

NameTypeDescription
componentsDetectResponseComponent arrayA list of detected app components

The standard attributes of DetectResponseComponent objects are:

NameTypeDescription
strategystringThe detection strategy that was used for this component
typesstring arrayA list of supported App Platform component types
dockerfilesstring arrayA list of Dockerfiles that were found for this component. The recommendation is to use the first Dockerfile.
build_commandstringThe detected build command
run_commandstringThe detected run command
environment_slugstringThe detected environment
http_portsint64 arrayA list of HTTP ports that this component may listen on. The recommendation is to use the last port in the list.
env_varsAppVariableDefinition arrayA list of suggested environment variables

The standard attributes of AppVariableDefinition objects are:

NameTypeDescription
keystringThe name
valuestringThe value. If the type is `SECRET`, the value will be encrypted on first submission. On following submissions, the encrypted value should be used.
scopestringThe visibility scope - `RUN_TIME`: Made available only at run-time - `BUILD_TIME`: Made available only at build-time - `RUN_AND_BUILD_TIME`: Made available at both build and run-time
typestringThe type - `GENERAL`: A plain-text environment variable - `SECRET`: A secret encrypted environment variable

Run App Detection

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/apps/detect"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "github": {
    "repo": "digitalocean/sample-golang",
    "branch": "master"
  }
}

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 838
ratelimit-reset: 1415984218

Response Body

{
  "components": [
    {
      "strategy": "BUILDPACK",
      "types": [
        "service",
        "static_site",
        "worker",
        "job"
      ],
      "run_command": "bin/sample-golang",
      "environment_slug": "go"
    }
  ]
}

List App Deployments

List all deployments of an app.

To run this operation, send a GET request to /v2/apps/{app_id}/deployments.

Request

The attribute values that may be set in the path of this request are:

NameTypeDescriptionRequired
app_idstringThe app IDrequired

Response

The response will be a JSON object with a key called deployments. This will be set to a array of deployment objects, each of which will contain the standard deployment attributes:

NameTypeDescription
idstringThe ID of the deployment
specAppSpec objectThe app specification of this specific deployment
servicesDeploymentService arrayService components that are part of this deployment
static_sitesDeploymentStaticSite arrayStatic Site components that are part of this deployment
workersDeploymentWorker arrayWorker components that are part of this deployment
jobsDeploymentJob arrayJob components that are part of this deployment
phase_last_updated_atstringWhen the deployment phase was last updated
created_atstringThe creation time of the deployment
updated_atstringWhen the deployment was last updated
causestringWhat caused this deployment to be created
cloned_fromstringThe ID of a previous deployment that this deployment was cloned from
progressDeploymentProgress objectInformation about this deployment's progress
phasestringThe current phase of the deployment
tier_slugstringThe current pricing tier slug of the deployment

List App Deployments

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/apps/{app_id}/deployments"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 838
ratelimit-reset: 1415984218

Response Body

{
  "deployments": [
    {
      "id": "b6bdf840-2854-4f87-a36c-5f231c617c84",
      "spec": {
        "name": "sample-golang",
        "services": [
          {
            "name": "web",
            "github": {
              "repo": "digitalocean/sample-golang",
              "branch": "branch"
            },
            "run_command": "bin/sample-golang",
            "environment_slug": "go",
            "instance_size_slug": "professional-xs",
            "instance_count": 2,
            "routes": [
              {
                "path": "/"
              }
            ]
          }
        ],
        "region": "ams3"
      },
      "services": [
        {
          "name": "web",
          "source_commit_hash": "9a4df0b8e161e323bc3cdf1dc71878080fe144fa"
        }
      ],
      "cause": "commit 9a4df0b pushed to github/digitalocean/sample-golang",
      "progress": null,
      "created_at": "2020-07-28T18:00:00Z",
      "updated_at": "2020-07-28T18:00:00Z"
    }
  ]
}

Retrieve an App Deployment

Retrieve information about an app deployment.

To run this operation, send a GET request to /v2/apps/{app_id}/deployments/{deployment_id}.

Request

The attribute values that may be set in the path of this request are:

NameTypeDescriptionRequired
app_idstringThe app IDrequired
deployment_idstringThe deployment IDrequired

Response

The response will be a JSON object with a key called deployment. This will be set to a deployment object which will contain the standard deployment attributes:

NameTypeDescription
idstringThe ID of the deployment
specAppSpec objectThe app specification of this specific deployment
servicesDeploymentService arrayService components that are part of this deployment
static_sitesDeploymentStaticSite arrayStatic Site components that are part of this deployment
workersDeploymentWorker arrayWorker components that are part of this deployment
jobsDeploymentJob arrayJob components that are part of this deployment
phase_last_updated_atstringWhen the deployment phase was last updated
created_atstringThe creation time of the deployment
updated_atstringWhen the deployment was last updated
causestringWhat caused this deployment to be created
cloned_fromstringThe ID of a previous deployment that this deployment was cloned from
progressDeploymentProgress objectInformation about this deployment's progress
phasestringThe current phase of the deployment
tier_slugstringThe current pricing tier slug of the deployment

Retrieve an App Deployment

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/apps/{app_id}/deployments/{deployment_id}"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 838
ratelimit-reset: 1415984218

Response Body

{
  "deployment": {
    "id": "b6bdf840-2854-4f87-a36c-5f231c617c84",
    "spec": {
      "name": "sample-golang",
      "services": [
        {
          "name": "web",
          "github": {
            "repo": "digitalocean/sample-golang",
            "branch": "branch"
          },
          "run_command": "bin/sample-golang",
          "environment_slug": "go",
          "instance_size_slug": "professional-xs",
          "instance_count": 2,
          "routes": [
            {
              "path": "/"
            }
          ]
        }
      ],
      "region": "ams3"
    },
    "services": [
      {
        "name": "web",
        "source_commit_hash": "9a4df0b8e161e323bc3cdf1dc71878080fe144fa"
      }
    ],
    "cause": "commit 9a4df0b pushed to github/digitalocean/sample-golang",
    "progress": null,
    "created_at": "2020-07-28T18:00:00Z",
    "updated_at": "2020-07-28T18:00:00Z"
  }
}

Create an App Deployment

Creating an app deployment will pull the latest changes from your repository and schedule a new deployment for your app.

To run this operation, send a POST request to /v2/apps/{app_id}/deployments.

Request

The attribute values that may be set in the path of this request are:

NameTypeDescriptionRequired
app_idstringThe app IDrequired

Response

The response will be a JSON object with a key called deployment. This will be set to a deployment object which will contain the standard deployment attributes:

NameTypeDescription
idstringThe ID of the deployment
specAppSpec objectThe app specification of this specific deployment
servicesDeploymentService arrayService components that are part of this deployment
static_sitesDeploymentStaticSite arrayStatic Site components that are part of this deployment
workersDeploymentWorker arrayWorker components that are part of this deployment
jobsDeploymentJob arrayJob components that are part of this deployment
phase_last_updated_atstringWhen the deployment phase was last updated
created_atstringThe creation time of the deployment
updated_atstringWhen the deployment was last updated
causestringWhat caused this deployment to be created
cloned_fromstringThe ID of a previous deployment that this deployment was cloned from
progressDeploymentProgress objectInformation about this deployment's progress
phasestringThe current phase of the deployment
tier_slugstringThe current pricing tier slug of the deployment

Create an App Deployment

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/apps/{app_id}/deployments"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 838
ratelimit-reset: 1415984218

Response Body

{
  "deployment": {
    "id": "b6bdf840-2854-4f87-a36c-5f231c617c84",
    "spec": {
      "name": "sample-golang",
      "services": [
        {
          "name": "web",
          "github": {
            "repo": "digitalocean/sample-golang",
            "branch": "branch"
          },
          "run_command": "bin/sample-golang",
          "environment_slug": "go",
          "instance_size_slug": "professional-xs",
          "instance_count": 2,
          "routes": [
            {
              "path": "/"
            }
          ]
        }
      ],
      "region": "ams3"
    },
    "services": [
      {
        "name": "web",
        "source_commit_hash": "9a4df0b8e161e323bc3cdf1dc71878080fe144fa"
      }
    ],
    "cause": "commit 9a4df0b pushed to github/digitalocean/sample-golang",
    "progress": null,
    "created_at": "2020-07-28T18:00:00Z",
    "updated_at": "2020-07-28T18:00:00Z"
  }
}

Cancel a Deployment

Immediately cancel an in-progress deployment.

To run this operation, send a POST request to /v2/apps/{app_id}/deployments/{deployment_id}/cancel.

Request

The attribute values that may be set in the path of this request are:

NameTypeDescriptionRequired
app_idstringThe app IDrequired
deployment_idstringThe deployment IDrequired

Response

The response will be a JSON object with a key called deployment. This will be set to a deployment object which will contain the standard deployment attributes:

NameTypeDescription
idstringThe ID of the deployment
specAppSpec objectThe app specification of this specific deployment
servicesDeploymentService arrayService components that are part of this deployment
static_sitesDeploymentStaticSite arrayStatic Site components that are part of this deployment
workersDeploymentWorker arrayWorker components that are part of this deployment
jobsDeploymentJob arrayJob components that are part of this deployment
phase_last_updated_atstringWhen the deployment phase was last updated
created_atstringThe creation time of the deployment
updated_atstringWhen the deployment was last updated
causestringWhat caused this deployment to be created
cloned_fromstringThe ID of a previous deployment that this deployment was cloned from
progressDeploymentProgress objectInformation about this deployment's progress
phasestringThe current phase of the deployment
tier_slugstringThe current pricing tier slug of the deployment

Cancel a Deployment

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/apps/{app_id}/deployments/{deployment_id}/cancel"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 838
ratelimit-reset: 1415984218

Response Body

{
  "deployment": {
    "id": "b6bdf840-2854-4f87-a36c-5f231c617c84",
    "spec": {
      "name": "sample-golang",
      "services": [
        {
          "name": "web",
          "github": {
            "repo": "digitalocean/sample-golang",
            "branch": "branch"
          },
          "run_command": "bin/sample-golang",
          "environment_slug": "go",
          "instance_size_slug": "professional-xs",
          "instance_count": 2,
          "routes": [
            {
              "path": "/"
            }
          ]
        }
      ],
      "region": "ams3"
    },
    "services": [
      {
        "name": "web",
        "source_commit_hash": "9a4df0b8e161e323bc3cdf1dc71878080fe144fa"
      }
    ],
    "cause": "commit 9a4df0b pushed to github/digitalocean/sample-golang",
    "progress": null,
    "created_at": "2020-07-28T18:00:00Z",
    "updated_at": "2020-07-28T18:00:00Z"
  }
}

Retrieve Deployment Logs

Retrieve the logs of a past, in-progress, or active deployment. If a component name is specified, the logs will be limited to only that component. The response will include links to either real-time logs of an in-progress or active deployment or archived logs of a past deployment.

To run this operation, send a GET request to /v2/apps/{app_id}/deployments/{deployment_id}/components/{component_name}/logs.

Request

The attribute values that may be set in the path of this request are:

NameTypeDescriptionRequired
app_idstringThe ID of the apprequired
deployment_idstringThe ID of the deploymentrequired
component_namestringAn optional component name. If set, logs will be limited to this component only.required

The attribute values that may be set in the query of this request are:

NameTypeDescription
followbooleanWhether the logs should follow live updates.
typestringThe type of logs to retrieve - `BUILD`: Build-time logs - `DEPLOY`: Deploy-time logs - `RUN`: Live run-time logs
pod_connection_timeoutstringAn optional time duration to wait if the underlying component instance is not immediately available. Default: `3m`.

Response

The response will be a JSON object that contains the following attributes:

NameTypeDescription
live_urlstringA URL of the real-time live logs. This URL may use either the https:// or wss:// protocols and will keep pushing live logs as they become available.
historic_urlsstring arrayA list of URLs to archived log files

Retrieve Deployment Logs

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/apps/{app_id}/deployments/{deployment_id}/components/{component_name}/logs"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 838
ratelimit-reset: 1415984218

Response Body

{
  "live_url": "https://logs-example/build.log",
  "historic_urls": [
    "https://logs-example/archive/build.log"
  ]
}

Retrieve Aggregate Deployment Logs

Retrieve the logs of a past, in-progress, or active deployment. If a component name is specified, the logs will be limited to only that component. The response will include links to either real-time logs of an in-progress or active deployment or archived logs of a past deployment.

To run this operation, send a GET request to /v2/apps/{app_id}/deployments/{deployment_id}/logs.

Request

The attribute values that may be set in the path of this request are:

NameTypeDescriptionRequired
app_idstringThe ID of the apprequired
deployment_idstringThe ID of the deploymentrequired

The attribute values that may be set in the query of this request are:

NameTypeDescription
component_namestringAn optional component name. If set, logs will be limited to this component only.
followbooleanWhether the logs should follow live updates.
typestringThe type of logs to retrieve - `BUILD`: Build-time logs - `DEPLOY`: Deploy-time logs - `RUN`: Live run-time logs
pod_connection_timeoutstringAn optional time duration to wait if the underlying component instance is not immediately available. Default: `3m`.

Response

The response will be a JSON object that contains the following attributes:

NameTypeDescription
live_urlstringA URL of the real-time live logs. This URL may use either the https:// or wss:// protocols and will keep pushing live logs as they become available.
historic_urlsstring arrayA list of URLs to archived log files

Retrieve Aggregate Deployment Logs

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/apps/{app_id}/deployments/{deployment_id}/logs"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 838
ratelimit-reset: 1415984218

Response Body

{
  "live_url": "https://logs-example/build.log",
  "historic_urls": [
    "https://logs-example/archive/build.log"
  ]
}

Balance

By sending requests to the /v2/customers/my/balance endpoint, you can retrieve the balance information for the requested customer account.

NameTypeDescription
month_to_date_balancestringBalance as of the generated_at time. This value includes the account_balance and month_to_date_usage.
account_balancestringCurrent balance of the customer's most recent billing activity. Does not reflect month_to_date_usage.
month_to_date_usagestringAmount used in the current billing period as of the generated_at time.
generated_atstringThe time at which balances were most recently generated.

Get Customer Balance

To retrieve the balances on a customer's account, send a GET request to /v2/customers/my/balance.

The response will be a JSON object that contains the following attributes:

NameTypeDescription
month_to_date_balancestringBalance as of the generated_at time. This value includes the account_balance and month_to_date_usage.
account_balancestringCurrent balance of the customer's most recent billing activity. Does not reflect month_to_date_usage.
month_to_date_usagestringAmount used in the current billing period as of the generated_at time.
generated_atstringThe time at which balances were most recently generated.

Get Customer Balance

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/customers/my/balance"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1137
ratelimit-reset: 1415984218

Response Body

{
  "month_to_date_balance": "23.44",
  "account_balance": "12.23",
  "month_to_date_usage": "11.21",
  "generated_at": "2019-07-09T15:01:12Z"
}

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 the billing history for an account, you will generally send requests to the billing history endpoint at /v2/customers/my/billing_history.

NameTypeDescription
descriptionstringDescription of the billing history entry.
amountstringAmount of the billing history entry.
invoice_idstringID of the invoice associated with the billing history entry, if applicable.
invoice_uuidstringUUID of the invoice associated with the billing history entry, if applicable.
datestringTime the billing history entry occured.
typestringType of billing history entry.

List Billing History

To retrieve a list of all billing history entries, send a GET request to /v2/customers/my/billing_history.

The response will be a JSON object contains that contains a list of the billing history under the billing_history key. Each element contains the following attributes:

NameTypeDescription
descriptionstringDescription of the billing history entry.
amountstringAmount of the billing history entry.
invoice_idstringID of the invoice associated with the billing history entry, if applicable.
invoice_uuidstringUUID of the invoice associated with the billing history entry, if applicable.
datestringTime the billing history entry occured.
typestringType of billing history entry.

List Billing History

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/customers/my/billing_history"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1137
ratelimit-reset: 1415984218

Response Body

{
  "billing_history": [
    {
      "description": "Invoice for May 2018",
      "amount": "12.34",
      "invoice_id": "123",
      "invoice_uuid": "example-uuid",
      "date": "2018-06-01T08:44:38Z",
      "type": "Invoice"
    },
    {
      "description": "Payment (MC 2018)",
      "amount": "-12.34",
      "date": "2018-06-02T08:44:38Z",
      "type": "Payment"
    }
  ],
  "links": {
    "pages": {
      "next": "https://api.digitalocean.com/v2/customers/my/billing_history?page=2&per_page=2",
      "last": "https://api.digitalocean.com/v2/customers/my/billing_history?page=3&per_page=2"
    }
  },
  "meta": {
    "total": 5
  }
}

Block Storage

DigitalOcean Block Storage 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.

NameTypeDescription
idstringThe unique identifier for the block storage volume.
regionobjectThe region that the block storage volume is located in. When setting a region, the value should be the slug identifier for the region. When you query a block storage volume, the entire region object will be returned.
droplet_idsarrayAn array containing the IDs of the Droplets the volume is attached to. Note that at this time, a volume can only be attached to a single Droplet.
namestringA human-readable name for the block storage volume. Must be lowercase and be composed only of numbers, letters and "-", up to a limit of 64 characters. The name must begin with a letter.
descriptionstringAn optional free-form text field to describe a block storage volume.
size_gigabytesintegerThe size of the block storage volume in GiB (1024^3).
created_atstringA time value given in ISO8601 combined date and time format that represents when the block storage volume was created.
filesystem_typestringThe type of filesystem currently in-use on the volume.
filesystem_labelstringThe label currently applied to the filesystem.
tagsarrayAn array of tags the volume has been tagged with

List All Block Storage Volumes

To list all of the block storage volumes available on your account, send a GET request to /v2/volumes.

The response will be a JSON object with a key called volumes. This will be set to an array of volume objects, each of which will contain the standard volume attributes.

The region may be provided as query paramater in order to restrict results to volumes available in a specific region. For example: /v2/volumes?region=nyc1

NameTypeDescription
idstringThe unique identifier for the block storage volume.
regionobjectThe region that the block storage volume is located in. When setting a region, the value should be the slug identifier for the region. When you query a block storage volume, the entire region object will be returned.
droplet_idsarrayAn array containing the IDs of the Droplets the volume is attached to. Note that at this time, a volume can only be attached to a single Droplet.
namestringA human-readable name for the block storage volume. Must be lowercase and be composed only of numbers, letters and "-", up to a limit of 64 characters. The name must begin with a letter.
descriptionstringAn optional free-form text field to describe a block storage volume.
size_gigabytesintegerThe size of the block storage volume in GiB (1024^3).
created_atstringA time value given in ISO8601 combined date and time format that represents when the block storage volume was created.
filesystem_typestringThe type of filesystem currently in-use on the volume.
filesystem_labelstringThe label currently applied to the filesystem.
tagsarrayAn array of tags the volume has been tagged with

List All Block Storage Volumes

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/volumes?region=nyc1"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

volumes = client.volumes.all
volumes.each

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

opt := &godo.ListOptions{
    Page:    1,
    PerPage: 200,
}

volumes, _, err := client.Storage.ListVolumes(ctx, opt)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Response Body

{
  "volumes": [
    {
      "id": "506f78a4-e098-11e5-ad9f-000f53306ae1",
      "region": {
        "name": "New York 1",
        "slug": "nyc1",
        "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-192gb"
        ],
        "features": [
          "private_networking",
          "backups",
          "ipv6",
          "metadata"
        ],
        "available": true
      },
      "droplet_ids": [

      ],
      "name": "example",
      "description": "Block store for examples",
      "size_gigabytes": 10,
      "created_at": "2016-03-02T17:00:49Z",
      "filesystem_type": "ext4",
      "filesystem_label": "example",
      "tags": [
        "aninterestingtag"
      ]
    }
  ],
  "links": {
  },
  "meta": {
    "total": 1
  }
}

List Block Storage Volumes Filtered by Name

It is also possible to list volumes on your account that match a specified name. To do so, send a GET request with the volume's name as a query parameter to /v2/volumes?name=$VOLUME_NAME.

Note: You can only create one volume per region with the same name.

The response will be a JSON object with a key called volumes. This will be set to an array of volume objects, each of which will contain the standard volume attributes.

NameTypeDescription
idstringThe unique identifier for the block storage volume.
regionobjectThe region that the block storage volume is located in. When setting a region, the value should be the slug identifier for the region. When you query a block storage volume, the entire region object will be returned.
droplet_idsarrayAn array containing the IDs of the Droplets the volume is attached to. Note that at this time, a volume can only be attached to a single Droplet.
namestringA human-readable name for the block storage volume. Must be lowercase and be composed only of numbers, letters and "-", up to a limit of 64 characters. The name must begin with a letter.
descriptionstringAn optional free-form text field to describe a block storage volume.
size_gigabytesintegerThe size of the block storage volume in GiB (1024^3).
created_atstringA time value given in ISO8601 combined date and time format that represents when the block storage volume was created.
filesystem_typestringThe type of filesystem currently in-use on the volume.
filesystem_labelstringThe label currently applied to the filesystem.
tagsarrayAn array of tags the volume has been tagged with

List Block Storage Volumes Filtered by Name

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/volumes?name=example"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Response Body

{
  "volumes": [
    {
      "id": "506f78a4-e098-11e5-ad9f-000f53306ae1",
      "region": {
        "name": "New York 1",
        "slug": "nyc1",
        "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-192gb"
        ],
        "features": [
          "private_networking",
          "backups",
          "ipv6",
          "metadata"
        ],
        "available": true
      },
      "droplet_ids": [

      ],
      "name": "example",
      "description": "Block store for examples",
      "size_gigabytes": 10,
      "created_at": "2016-03-02T17:00:49Z",
      "filesystem_type": "ext4",
      "filesystem_label": "example",
      "tags": [
        "aninterestingtag"
      ]
    },
    {
      "id": "50663b09-a25a-11e9-9e21-000f53306ae1",
      "region": {
        "name": "Singapore 1",
        "slug": "sgp1",
        "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-192gb"
        ],
        "features": [
          "private_networking",
          "backups",
          "ipv6",
          "metadata"
        ],
        "available": true
      },
      "droplet_ids": [

      ],
      "name": "example",
      "description": "Block store for examples",
      "size_gigabytes": 5,
      "created_at": "2019-07-09T15:01:12Z",
      "filesystem_type": "ext4",
      "filesystem_label": "example",
      "tags": [

      ]
    }
  ],
  "links": {
  },
  "meta": {
    "total": 2
  }
}

Create a New Block Storage Volume

To create a new volume, send a POST request to /v2/volumes. Optionally, a filesystem_type attribute may be provided in order to automatically format the volume's filesystem. Pre-formatted volumes are automatically mounted when attached to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018. Attaching pre-formatted volumes to Droplets without support for auto-mounting is not recommended.

The attribute values that must be set to successfully create a volume are:

NameTypeDescriptionRequired
size_gigabytesintegerThe size of the block storage volume in GiB (1024^3).true
namestringA human-readable name for the block storage volume. Must be lowercase and be composed only of numbers, letters and "-", up to a limit of 64 characters.true
descriptionstringAn optional free-form text field to describe a block storage volume.
regionstringThe region where the block storage volume will be created. When setting a region, the value should be the slug identifier for the region. When you query a block storage volume, the entire region object will be returned.true
snapshot_idstringThe unique identifier for the volume snapshot from which to create the volume. Should not be specified with a region_id.
filesystem_typestringThe name of the filesystem type to be used on the volume. When provided, the volume will automatically be formatted to the specified filesystem type. Currently, the available options are "ext4" and "xfs". Pre-formatted volumes are automatically mounted when attached to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018. Attaching pre-formatted volumes to other Droplets is not recommended.
filesystem_labelstringThe label to be applied to the filesystem. Labels for ext4 type filesystems may contain 16 characters while lables for xfs type filesystems are limited to 12 characters. May only be used in conjunction with filesystem_type.
tagsarrayA flat array of tag names as strings to apply to the Volume after it is created. Tag names can either be existing or new tags.

The response will be a array called volume containing an object with the standard attributes associated with a volume:

NameTypeDescription
idstringThe unique identifier for the block storage volume.
regionobjectThe region that the block storage volume is located in. When setting a region, the value should be the slug identifier for the region. When you query a block storage volume, the entire region object will be returned.
droplet_idsarrayAn array containing the IDs of the Droplets the volume is attached to. Note that at this time, a volume can only be attached to a single Droplet.
namestringA human-readable name for the block storage volume. Must be lowercase and be composed only of numbers, letters and "-", up to a limit of 64 characters. The name must begin with a letter.
descriptionstringAn optional free-form text field to describe a block storage volume.
size_gigabytesintegerThe size of the block storage volume in GiB (1024^3).
created_atstringA time value given in ISO8601 combined date and time format that represents when the block storage volume was created.
filesystem_typestringThe type of filesystem currently in-use on the volume.
filesystem_labelstringThe label currently applied to the filesystem.
tagsarrayAn array of tags the volume has been tagged with

Create a New Block Storage Volume

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"size_gigabytes":10, "name": "example", "description": "Block store for examples", "region": "nyc1", "filesystem_type": "ext4", "filesystem_label": "example"}' "https://api.digitalocean.com/v2/volumes"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

volume = DropletKit::Volume.new(
  size_gigabytes: 10,
  name: 'Example',
  description: 'Block store for examples',
  region: 'nyc1'
)
client.volumes.create(volume)

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

createRequest := &VolumeCreateRequest{
    Region:        "nyc1",
    Name:          "example",
    Description:   "Block store for examples",
    SizeGigaBytes: 10,
}

volume, _, err := client.Storage.CreateVolume(ctx, createRequest)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "size_gigabytes": 10,
  "name": "example",
  "description": "Block store for examples",
  "region": "nyc1",
  "filesystem_type": "ext4",
  "filesystem_label": "example"
}

Response Headers

content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 5000
ratelimit-remaining: 4821
ratelimit-reset: 1444931833

Response Body

{
  "volume": {
    "id": "506f78a4-e098-11e5-ad9f-000f53306ae1",
    "region": {
      "name": "New York 1",
      "slug": "nyc1",
      "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-192gb"
      ],
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata"
      ],
      "available": true
    },
    "droplet_ids": [

    ],
    "name": "example",
    "description": "Block store for examples",
    "size_gigabytes": 10,
    "filesystem_type": "ext4",
    "filesystem_label": "example",
    "created_at": "2016-03-02T17:00:49Z"
  }
}

Retrieve an Existing Block Storage Volume

To show information about a block storage volume, send a GET request to /v2/volumes/$VOLUME_ID.

The response will be a JSON object with a key called volume. The value of this will be an object that contains the standard attributes associated with a volume:

NameTypeDescription
idstringThe unique identifier for the block storage volume.
regionobjectThe region that the block storage volume is located in. When setting a region, the value should be the slug identifier for the region. When you query a block storage volume, the entire region object will be returned.
droplet_idsarrayAn array containing the IDs of the Droplets the volume is attached to. Note that at this time, a volume can only be attached to a single Droplet.
namestringA human-readable name for the block storage volume. Must be lowercase and be composed only of numbers, letters and "-", up to a limit of 64 characters. The name must begin with a letter.
descriptionstringAn optional free-form text field to describe a block storage volume.
size_gigabytesintegerThe size of the block storage volume in GiB (1024^3).
created_atstringA time value given in ISO8601 combined date and time format that represents when the block storage volume was created.
filesystem_typestringThe type of filesystem currently in-use on the volume.
filesystem_labelstringThe label currently applied to the filesystem.
tagsarrayAn array of tags the volume has been tagged with

Retrieve an Existing Block Storage Volume

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/volumes/7724db7c-e098-11e5-b522-000f53304e51"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.volumes.find(id: '7724db7c-e098-11e5-b522-000f53304e51')

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

volume, _, err := client.Storage.GetVolume(ctx, "7724db7c-e098-11e5-b522-000f53304e51")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4820
ratelimit-reset: 1444931833

Response Body

{
  "volume": {
    "id": "506f78a4-e098-11e5-ad9f-000f53306ae1",
    "region": {
      "name": "New York 1",
      "slug": "nyc1",
      "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-192gb"
      ],
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata"
      ],
      "available": true
    },
    "droplet_ids": [

    ],
    "name": "example",
    "description": "Block store for examples",
    "size_gigabytes": 10,
    "created_at": "2016-03-02T17:00:49Z",
    "filesystem_type": "ext4",
    "filesystem_label": "example",
    "tags": [
      "aninterestingtag"
    ]
  }
}

Retrieve an Existing Block Storage Volume by Name

It is also possible to retrieve information about a block storage volume by name. To do so, send a GET request with the volume's name and the region slug for the region it is located in as query parameters to /v2/volumes?name=$VOLUME_NAME&region=nyc1.

The response will be a JSON object with a key called volumes. This will be set to an array containing a volume object with the standard volume attributes:

NameTypeDescription
idstringThe unique identifier for the block storage volume.
regionobjectThe region that the block storage volume is located in. When setting a region, the value should be the slug identifier for the region. When you query a block storage volume, the entire region object will be returned.
droplet_idsarrayAn array containing the IDs of the Droplets the volume is attached to. Note that at this time, a volume can only be attached to a single Droplet.
namestringA human-readable name for the block storage volume. Must be lowercase and be composed only of numbers, letters and "-", up to a limit of 64 characters. The name must begin with a letter.
descriptionstringAn optional free-form text field to describe a block storage volume.
size_gigabytesintegerThe size of the block storage volume in GiB (1024^3).
created_atstringA time value given in ISO8601 combined date and time format that represents when the block storage volume was created.
filesystem_typestringThe type of filesystem currently in-use on the volume.
filesystem_labelstringThe label currently applied to the filesystem.
tagsarrayAn array of tags the volume has been tagged with

Retrieve an Existing Block Storage Volume by Name

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/volumes?name=example&region=nyc1"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4820
ratelimit-reset: 1444931833

Response Body

{
  "volumes": [
    {
      "id": "506f78a4-e098-11e5-ad9f-000f53306ae1",
      "region": {
        "name": "New York 1",
        "slug": "nyc1",
        "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-192gb"
        ],
        "features": [
          "private_networking",
          "backups",
          "ipv6",
          "metadata"
        ],
        "available": true
      },
      "droplet_ids": [

      ],
      "name": "example",
      "description": "Block store for examples",
      "size_gigabytes": 10,
      "created_at": "2016-03-02T17:00:49Z",
      "filesystem_type": "ext4",
      "filesystem_label": "example",
      "tags": [
        "aninterestingtag"
      ]
    }
  ],
  "links": {
  },
  "meta": {
    "total": 1
  }
}

List Snapshots for a Volume

To retrieve the snapshots that have been created from a volume, send a GET request to /v2/volumes/$VOLUME_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 snapshot attributes:

NameTypeDescription
idstringThe unique identifier for the snapshot.
namestringA human-readable name for the snapshot.
created_atstringA time value given in ISO8601 combined date and time format that represents when the snapshot was created.
regionsarrayAn array of the regions that the image is available in. The regions are represented by their identifying slug values.
resource_idstringA unique identifier for the resource that the action is associated with.
resource_typestringThe type of resource that the action is associated with.
min_disk_sizeintegerThe minimum size in GB required for a volume or Droplet to use this snapshot.
size_gigabytesfloatThe billable size of the snapshot in gigabytes.

List Snapshots for a Volume

cURL Example

curl -X GET -H 'Content-Type: application/json' -H 'Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582' "https://api.digitalocean.com/v2/volumes/82a48a18-873f-11e6-96bf-000f53315a41/snapshots?page=1&per_page=1"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

snapshots = client.volumes.snapshots(id: '82a48a18-873f-11e6-96bf-000f53315a41')
snapshots.each

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

opt := &godo.ListOptions{
    Page:    1,
    PerPage: 200,
}

volumes, _, err := client.Storage.ListSnapshots(ctx, '82a48a18-873f-11e6-96bf-000f53315a41', opt)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4982
ratelimit-reset: 1475263694

Response Body

{
  "snapshots": [
    {
      "id": "8eb4d51a-873f-11e6-96bf-000f53315a41",
      "name": "big-data-snapshot1475261752",
      "regions": [
        "nyc1"
      ],
      "created_at": "2016-09-30T18:56:12Z",
      "resource_id": "82a48a18-873f-11e6-96bf-000f53315a41",
      "resource_type": "volume",
      "min_disk_size": 10,
      "size_gigabytes": 0
    }
  ],
  "links": {
  },
  "meta": {
    "total": 1
  }
}

Create Snapshot from a Volume

To create a snapshot from a volume, sent a POST request to /v2/volumes/$VOLUME_ID/snapshots.

NameTypeDescriptionRequired
namestringA human-readable name for the volume snapshot.true
tagsarrayA flat array of tag names as strings to apply to the volume snapshot after it is created. Tag names can either be existing or new tags.

You will get back a JSON object that has a snapshot key. This will contain the standard snapshot attributes:

NameTypeDescription
idstringThe unique identifier for the snapshot.
namestringA human-readable name for the snapshot.
created_atstringA time value given in ISO8601 combined date and time format that represents when the snapshot was created.
regionsarrayAn array of the regions that the image is available in. The regions are represented by their identifying slug values.
resource_idstringA unique identifier for the resource that the action is associated with.
resource_typestringThe type of resource that the action is associated with.
min_disk_sizeintegerThe minimum size in GB required for a volume or Droplet to use this snapshot.
size_gigabytesfloatThe billable size of the snapshot in gigabytes.

Create Snapshot from a Volume

cURL Example

curl -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582' -d '{"name":"big-data-snapshot1475261774", "tags":["aninterestingtag"]}' "https://api.digitalocean.com/v2/volumes/82a48a18-873f-11e6-96bf-000f53315a41/snapshots"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.volumes.create_snapshot(id: "82a48a18-873f-11e6-96bf-000f53315a41", name: "big-data-snapshot1475261774")

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

snapshot, _, err := client.Storage.CreateSnapshot(ctx, "82a48a18-873f-11e6-96bf-000f53315a41")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "name": "big-data-snapshot1475261774"
}

Response Headers

content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 5000
ratelimit-remaining: 4981
ratelimit-reset: 1475263694

Response Body

{
  "snapshot": {
    "id": "8fa70202-873f-11e6-8b68-000f533176b1",
    "name": "big-data-snapshot1475261774",
    "regions": [
      "nyc1"
    ],
    "created_at": "2016-09-30T18:56:14Z",
    "resource_id": "82a48a18-873f-11e6-96bf-000f53315a41",
    "resource_type": "volume",
    "min_disk_size": 10,
    "size_gigabytes": 0,
    "tags": [
      "aninterestingtag"
    ]
  }
}

Delete a Block Storage Volume

To delete a block storage volume, destroying all data and removing it from your account, send a DELETE request to /v2/volumes/$VOLUME_ID.

No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

Delete a Block Storage Volume

cURL Example

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/volumes/7724db7c-e098-11e5-b522-000f53304e51"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.volumes.delete(id: '7724db7c-e098-11e5-b522-000f53304e51')

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

_, err := client.Storage.DeleteVolume(ctx, "7724db7c-e098-11e5-b522-000f53304e51")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

status: 204 No Content
ratelimit-limit: 5000
ratelimit-remaining: 4815
ratelimit-reset: 1444931833

Delete a Block Storage Volume by Name

Block storage volumes may also be deleted by name by sending a DELETE request with the volume's name and the region slug for the region it is located in as query parameters to /v2/volumes?name=$VOLUME_NAME&region=nyc1.

No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

Delete a Block Storage Volume by Name

cURL Example

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/volumes?name=example&region=nyc1"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

status: 204 No Content
ratelimit-limit: 5000
ratelimit-remaining: 4815
ratelimit-reset: 1444931833

Delete a Block Storage Volume Snapshot

Both Droplet and volume snapshots are managed through the /v2/snapshots/ endpoint. To delete a volume snapshot, send a DELETE request to /v2/snapshots/$SNAPSHOT_ID.

A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.

Delete a Block Storage Volume Snapshot

cURL Example

curl -X DELETE -H 'Content-Type: application/json' -H 'Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582' "https://api.digitalocean.com/v2/snapshots/fbe805e8-866b-11e6-96bf-000f53315a41"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.snapshots.delete(id: "fbe805e8-866b-11e6-96bf-000f53315a41")

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

_, err := client.Storage.DeleteSnapshot(ctx, "82a48a18-873f-11e6-96bf-000f53315a41")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

status: 204 No Content
ratelimit-limit: 5000
ratelimit-remaining: 4985
ratelimit-reset: 1475174402

Block Storage Actions

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.

NameTypeDescription
idintegerA unique numeric ID that can be used to identify and reference an action.
statusstringThe current status of the action. This can be "in-progress", "completed", or "errored".
typestringThis is the type of action that the object represents. For example, this could be "attach_volume" to represent the state of a volume attach action.
started_atstringA time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_atstringA time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_idnullable integerA unique identifier for the resource that the action is associated with.
resource_typestringThe type of resource that the action is associated with.
regionobjectThe region where the resources acted upon are located.
region_slugnullable stringA slug representing the region where the action occurred.

Attach a Block Storage Volume to a Droplet

To attach a block storage volume to a Droplet, send a POST request to /v2/volumes/$VOLUME_ID/actions. In the body, set the "type" attribute to attach and the "droplet_id" attribute to the Droplet's ID.

Each volume may only be attached to a single Droplet. However, up to five volumes may be attached to a Droplet at a time. Pre-formatted volumes will be automatically mounted to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018 when attched. On older Droplets, additional configuration is required.

NameTypeDescriptionRequired
typestringThis must be "attach"true
droplet_idintegerThe unique identifier for the Droplet the volume will be attached or detached from.true
regionstringThe slug identifier for the region the volume is located in.

The response will be a JSON object with a key called action. The value of this will be an object that contains the standard attributes associated with an action:

NameTypeDescription
idintegerA unique numeric ID that can be used to identify and reference an action.
statusstringThe current status of the action. This can be "in-progress", "completed", or "errored".
typestringThis is the type of action that the object represents. For example, this could be "attach_volume" to represent the state of a volume attach action.
started_atstringA time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_atstringA time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_idnullable integerA unique identifier for the resource that the action is associated with.
resource_typestringThe type of resource that the action is associated with.
regionobjectThe region where the resources acted upon are located.
region_slugnullable stringA slug representing the region where the action occurred.

Attach a Block Storage Volume to a Droplet

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type": "attach", "droplet_id": 11612190, "region": "nyc1", "tags":["aninterestingtag"]}' "https://api.digitalocean.com/v2/volumes/7724db7c-e098-11e5-b522-000f53304e51/actions"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.volume_actions.attach(volume_id:'7724db7c-e098-11e5-b522-000f53304e51', droplet_id: 11612190, region: 'nyc1'

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

action, _, err := client.StorageActions.Attach(ctx, "7724db7c-e098-11e5-b522-000f53304e51", 11612190)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "type": "attach",
  "droplet_id": 11612190,
  "region": "nyc1",
  "tags": [
    "aninterestingtag"
  ]
}

Response Headers

content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Response Body

{
  "action": {
    "id": 72531856,
    "status": "completed",
    "type": "attach_volume",
    "started_at": "2015-11-12T17:51:03Z",
    "completed_at": "2015-11-12T17:51:14Z",
    "resource_id": null,
    "resource_type": "volume",
    "region": {
      "name": "New York 1",
      "slug": "nyc1",
      "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-192gb"
      ],
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata"
      ],
      "available": true
    },
    "region_slug": "nyc1"
  }
}

Attach a Block Storage Volume to a Droplet by Name

To attach a block storage volume to a Droplet using its name, send a POST request to /v2/volumes/actions. In the body, set the "type" attribute to attach, the "droplet_id" attribute to the Droplet's ID, and the "volume_name" attribute to the volume's name.

Each volume may only be attached to a single Droplet. However, up to 7 volumes may be attached to a Droplet at a time. Pre-formatted volumes will be automatically mounted to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018 when attched. On older Droplets, additional configuration is required.

NameTypeDescriptionRequired
typestringThis must be "attach"true
droplet_idintegerThe unique identifier for the Droplet the volume will be attached or detached from.true
volume_namestringThe name of the block storage volume.true
regionstringThe slug identifier for the region the volume is located in.

The response will be a JSON object with a key called action. The value of this will be an object that contains the standard attributes associated with an action:

NameTypeDescription
idintegerA unique numeric ID that can be used to identify and reference an action.
statusstringThe current status of the action. This can be "in-progress", "completed", or "errored".
typestringThis is the type of action that the object represents. For example, this could be "attach_volume" to represent the state of a volume attach action.
started_atstringA time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_atstringA time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_idnullable integerA unique identifier for the resource that the action is associated with.
resource_typestringThe type of resource that the action is associated with.
regionobjectThe region where the resources acted upon are located.
region_slugnullable stringA slug representing the region where the action occurred.

Attach a Block Storage Volume to a Droplet by Name

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type": "attach", "volume_name": "example", "region": "nyc1", "droplet_id": "11612190","tags":["aninterestingtag"] }' "https://api.digitalocean.com/v2/volumes/actions"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "type": "attach",
  "volume_name": "example",
  "region": "nyc1",
  "droplet_id": "11612190",
  "tags": [
    "aninterestingname"
  ]
}

Response Headers

content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Response Body

{
  "action": {
    "id": 72531856,
    "status": "completed",
    "type": "attach_volume",
    "started_at": "2015-11-12T17:51:03Z",
    "completed_at": "2015-11-12T17:51:14Z",
    "resource_id": null,
    "resource_type": "volume",
    "region": {
      "name": "New York 1",
      "slug": "nyc1",
      "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-192gb"
      ],
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata"
      ],
      "available": true
    },
    "region_slug": "nyc1"
  }
}

Remove a Block Storage Volume from a Droplet

To detach a block storage volume from a Droplet, send a POST request to /v2/volumes/$VOLUME_ID/actions. In the body, set the "type" attribute to detach and the "droplet_id" attribute to the Droplet's ID.

NameTypeDescriptionRequired
typestringThis must be "detach"true
droplet_idintegerThe unique identifier for the Droplet the volume will be attached or detached from.true
regionstringThe slug identifier for the region the volume is located in.

The response will be a JSON object with a key called action. The value of this will be an object that contains the standard attributes associated with an action:

NameTypeDescription
idintegerA unique numeric ID that can be used to identify and reference an action.
statusstringThe current status of the action. This can be "in-progress", "completed", or "errored".
typestringThis is the type of action that the object represents. For example, this could be "attach_volume" to represent the state of a volume attach action.
started_atstringA time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_atstringA time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_idnullable integerA unique identifier for the resource that the action is associated with.
resource_typestringThe type of resource that the action is associated with.
regionobjectThe region where the resources acted upon are located.
region_slugnullable stringA slug representing the region where the action occurred.

Remove a Block Storage Volume from a Droplet

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type": "detach", "droplet_id": "11612190", "region": "nyc1"}' "https://api.digitalocean.com/v2/volumes/7724db7c-e098-11e5-b522-000f53304e51/actions"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.volume_actions.detach(volume_id:'7724db7c-e098-11e5-b522-000f53304e51', droplet_id: 11612190, region: 'nyc1'

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

action, _, err := client.StorageActions.Detach(ctx, "7724db7c-e098-11e5-b522-000f53304e51")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "type": "detach",
  "droplet_id": "11612190",
  "region": "nyc1"
}

Response Headers

content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 5000
ratelimit-remaining: 4816
ratelimit-reset: 1444931833

Response Body

{
  "action": {
    "id": 68212773,
    "status": "in-progress",
    "type": "detach_volume",
    "started_at": "2015-10-15T17:46:15Z",
    "completed_at": null,
    "resource_id": null,
    "resource_type": "backend",
    "region": {
      "name": "New York 1",
      "slug": "nyc1",
      "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-192gb"
      ],
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata"
      ],
      "available": true
    },
    "region_slug": "nyc1"
  }
}

Remove a Block Storage Volume from a Droplet by Name

To detach a block storage volume from a Droplet using its name, send a POST request to /v2/volumes/actions. In the body, set the "type" attribute to detach, the "droplet_id" attribute to the Droplet's ID, and the "volume_name" attribute to the volume's name.

NameTypeDescriptionRequired
typestringThis must be "detach"true
droplet_idintegerThe unique identifier for the Droplet the volume will be attached or detached from.true
volume_namestringThe name of the block storage volume.true
regionstringThe slug identifier for the region the volume is located in.

The response will be a JSON object with a key called action. The value of this will be an object that contains the standard attributes associated with an action:

NameTypeDescription
idintegerA unique numeric ID that can be used to identify and reference an action.
statusstringThe current status of the action. This can be "in-progress", "completed", or "errored".
typestringThis is the type of action that the object represents. For example, this could be "attach_volume" to represent the state of a volume attach action.
started_atstringA time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_atstringA time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_idnullable integerA unique identifier for the resource that the action is associated with.
resource_typestringThe type of resource that the action is associated with.
regionobjectThe region where the resources acted upon are located.
region_slugnullable stringA slug representing the region where the action occurred.

Remove a Block Storage Volume from a Droplet by Name

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type": "detach", "droplet_id": "11612190", "volume_name": "example", "region": "nyc1"}' "https://api.digitalocean.com/v2/volumes/actions"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "type": "detach",
  "droplet_id": "11612190",
  "volume_name": "example",
  "region": "nyc1"
}

Response Headers

content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 5000
ratelimit-remaining: 4816
ratelimit-reset: 1444931833

Resize a Volume

To resize a block storage volume, send a POST request to /v2/volumes/$VOLUME_ID/actions. Set the "type" attribute to resize, the "size_gigabytes" attribute to the new size of the volume in GiB (1024^3), and the "region" attribute to the slug representing the region where the volume is located. Volumes may only be resized upwards. The maximum size for a volume is 16TiB.

NameTypeDescriptionRequired
typestringThis must be "resize"true
size_gigabytesintegerThe new size of the block storage volume in GiB (1024^3).true
regionstringThe slug identifier for the region the volume is located in.

The response will be an object with a key called action. The value of this will be an object that contains the standard volume action attributes:

NameTypeDescription
idintegerA unique numeric ID that can be used to identify and reference an action.
statusstringThe current status of the action. This can be "in-progress", "completed", or "errored".
typestringThis is the type of action that the object represents. For example, this could be "attach_volume" to represent the state of a volume attach action.
started_atstringA time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_atstringA time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_idnullable integerA unique identifier for the resource that the action is associated with.
resource_typestringThe type of resource that the action is associated with.
regionobjectThe region where the resources acted upon are located.
region_slugnullable stringA slug representing the region where the action occurred.

Resize a Volume

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"resize","size_gigabytes": 100, "region":"nyc1"}' "https://api.digitalocean.com/v2/volumes/7724db7c-e098-11e5-b522-000f53304e51/actions"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

action, _, err := client.StorageActions.Resize(ctx, "7724db7c-e098-11e5-b522-000f53304e51", 100, "nyc1")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "type": "resize",
  "size_gigabytes": 100,
  "region": "nyc1"
}

Response Headers

content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 1200
ratelimit-remaining: 1046
ratelimit-reset: 1415984218

Response Body

{
  "action": {
    "id": 72531856,
    "status": "in-progress",
    "type": "resize",
    "started_at": "2015-11-12T17:51:03Z",
    "completed_at": "2015-11-12T17:51:14Z",
    "resource_id": null,
    "resource_type": "volume",
    "region": {
      "name": "New York 1",
      "slug": "nyc1",
      "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-192gb"
      ],
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata"
      ],
      "available": true
    },
    "region_slug": "nyc1"
  }
}

List All Actions for a Volume

To retrieve all actions that have been executed on a volume, send a GET request to /v2/volumes/$VOLUME_ID/actions.

The results will be returned as a JSON object with an actions key. This will be set to an array filled with action objects containing the standard volume action attributes:

NameTypeDescription
idintegerA unique numeric ID that can be used to identify and reference an action.
statusstringThe current status of the action. This can be "in-progress", "completed", or "errored".
typestringThis is the type of action that the object represents. For example, this could be "attach_volume" to represent the state of a volume attach action.
started_atstringA time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_atstringA time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_idnullable integerA unique identifier for the resource that the action is associated with.
resource_typestringThe type of resource that the action is associated with.
regionobjectThe region where the resources acted upon are located.
region_slugnullable stringA slug representing the region where the action occurred.

List All Actions for a Volume

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/volumes/7724db7c-e098-11e5-b522-000f53304e51/actions?page=1&per_page=1"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

actions = client.volume.actions(id: '7724db7c-e098-11e5-b522-000f53304e51')
actions.each

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

opt := &godo.ListOptions{
    Page:    1,
    PerPage: 200,
}

actions, _, err := client.StorageActions(ctx, "7724db7c-e098-11e5-b522-000f53304e51", opt)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 903
ratelimit-reset: 1415984218

Response Body

{
  "actions": [
    {
      "id": 72531856,
      "status": "completed",
      "type": "attach_volume",
      "started_at": "2015-11-21T21:51:09Z",
      "completed_at": "2015-11-21T21:51:09Z",
      "resource_id": null,
      "resource_type": "volume",
      "region": {
        "name": "New York 1",
        "slug": "nyc1",
        "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-192gb"
        ],
        "features": [
          "private_networking",
          "backups",
          "ipv6",
          "metadata"
        ],
        "available": true
      },
      "region_slug": "nyc1"
    }
  ],
  "links": {
  },
  "meta": {
    "total": 1
  }
}

Retrieve an Existing Volume Action

To retrieve the status of a volume action, send a GET request to /v2/volumes/$VOLUME_ID/actions/$ACTION_ID.

The response will be an object with a key called action. The value of this will be an object that contains the standard volume action attributes:

NameTypeDescription
idintegerA unique numeric ID that can be used to identify and reference an action.
statusstringThe current status of the action. This can be "in-progress", "completed", or "errored".
typestringThis is the type of action that the object represents. For example, this could be "attach_volume" to represent the state of a volume attach action.
started_atstringA time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_atstringA time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_idnullable integerA unique identifier for the resource that the action is associated with.
resource_typestringThe type of resource that the action is associated with.
regionobjectThe region where the resources acted upon are located.
region_slugnullable stringA slug representing the region where the action occurred.

Retrieve an Existing Volume Action

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/volumes/7724db7c-e098-11e5-b522-000f53304e51/actions/72531856"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.volume.actions.find(volume_id: '7724db7c-e098-11e5-b522-000f53304e51', id: 72531856)

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

action, _, err := client.StorageActions.Get(ctx, "7724db7c-e098-11e5-b522-000f53304e51", 72531856)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 837
ratelimit-reset: 1415984218

Response Body

{
  "action": {
    "id": 72531856,
    "status": "completed",
    "type": "attach_volume",
    "started_at": "2015-11-12T17:51:03Z",
    "completed_at": "2015-11-12T17:51:14Z",
    "resource_id": null,
    "resource_type": "volume",
    "region": {
      "name": "New York 1",
      "slug": "nyc1",
      "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-192gb"
      ],
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata"
      ],
      "available": true
    },
    "region_slug": "nyc1"
  }
}

CDN Endpoints

Content hosted in DigitalOcean's object storage solution, 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.

NameTypeDescription
idstringA unique ID that can be used to identify and reference a CDN endpoint.
originstringThe fully qualified domain name (FQDN) for the origin server which the provides the content for the CDN. This is currently restricted to a Space.
endpointstringThe fully qualified domain name (FQDN) from which the CDN-backed content is served.
created_atstringA time value given in ISO8601 combined date and time format that represents when the CDN endpoint was created.
ttlintegerThe amount of time the content is cached by the CDN's edge servers in seconds.
certificate_idstringThe ID of a DigitalOcean managed TLS certificate used for SSL when a custom subdomain is provided.
custom_domainstringThe fully qualified domain name (FQDN) of the custom subdomain used with the CDN Endpoint.

Create a New CDN Endpoint

To create a new CDN endpoint, send a POST request to /v2/cdn/endpoints. The origin attribute must be set to the fully qualified domain name (FQDN) of a DigitalOcean Space. Optionally, the TTL may be configured by setting the ttl attribute.

A custom subdomain may be configured by specifying the custom_domain and certificate_id attributes.

NameTypeDescriptionRequired
originstringThe fully qualified domain name (FQDN) for the origin server which the provides the content for the CDN. This is currently restricted to a Space.true
ttlintegerThe amount of time the content is cached by the CDN's edge servers in seconds. Defaults to 3600 (one hour) when excluded.
certificate_idstringThe ID of a DigitalOcean managed TLS certificate used for SSL when a custom subdomain is provided.
custom_domainstringThe fully qualified domain name (FQDN) of the custom subdomain to be used with the CDN Endpoint. When used, a certificate_id must be provided as well.

The response will be a JSON object with a key called endpoint. The value of this will be an object that contains the standard attributes associated with a CDN endpoint:

NameTypeDescription
idstringA unique ID that can be used to identify and reference a CDN endpoint.
originstringThe fully qualified domain name (FQDN) for the origin server which the provides the content for the CDN. This is currently restricted to a Space.
endpointstringThe fully qualified domain name (FQDN) from which the CDN-backed content is served.
created_atstringA time value given in ISO8601 combined date and time format that represents when the CDN endpoint was created.
ttlintegerThe amount of time the content is cached by the CDN's edge servers in seconds.
certificate_idstringThe ID of a DigitalOcean managed TLS certificate used for SSL when a custom subdomain is provided.
custom_domainstringThe fully qualified domain name (FQDN) of the custom subdomain used with the CDN Endpoint.

Create a New CDN Endpoint

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"origin": "static-images.nyc3.digitaloceanspaces.com","certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf","custom_domain": "static.example.com","ttl": 3600}' "https://api.digitalocean.com/v2/cdn/endpoints"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

cdn = DropletKit::CDN.new(
  origin: 'static-images.nyc3.digitaloceanspaces.com',
  custom_domain: 'static.example.com',
  certificate_id: '892071a0-bb95-49bc-8021-3afd67a210bf',
  ttl: 3600
)

client.cdns.create(cdn)

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

createRequest := &godo.CDNCreateRequest{
    Origin:        "static-images.nyc3.digitaloceanspaces.com",
    TTL:           3600,
    CustomDomain:  "static.example.com",
    CertificateID: "892071a0-bb95-49bc-8021-3afd67a210b",
}

cdn, _, err := client.CDNs.Create(ctx, createRequest)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "origin": "static-images.nyc3.digitaloceanspaces.com",
  "certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf",
  "custom_domain": "static.example.com",
  "ttl": 3600
}

Response Headers

content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Response Body

{
  "endpoint": {
    "id": "19f06b6a-3ace-4315-b086-499a0e521b76",
    "origin": "static-images.nyc3.digitaloceanspaces.com",
    "endpoint": "static-images.nyc3.cdn.digitaloceanspaces.com",
    "created_at": "2018-07-19T15:04:16Z",
    "certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf",
    "custom_domain": "static.example.com",
    "ttl": 3600
  }
}

Retrieve an Existing CDN Endpoint

To show information about an existing CDN endpoint, send a GET request to /v2/cdn/endpoints/$ENDPOINT_ID.

The response will be a JSON object with a endpoint key. This will be set to an object containing the standard CDN endpoint attributes:

NameTypeDescription
idstringA unique ID that can be used to identify and reference a CDN endpoint.
originstringThe fully qualified domain name (FQDN) for the origin server which the provides the content for the CDN. This is currently restricted to a Space.
endpointstringThe fully qualified domain name (FQDN) from which the CDN-backed content is served.
created_atstringA time value given in ISO8601 combined date and time format that represents when the CDN endpoint was created.
ttlintegerThe amount of time the content is cached by the CDN's edge servers in seconds.
certificate_idstringThe ID of a DigitalOcean managed TLS certificate used for SSL when a custom subdomain is provided.
custom_domainstringThe fully qualified domain name (FQDN) of the custom subdomain used with the CDN Endpoint.

Retrieve an Existing CDN Endpoint

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/cdn/endpoints/19f06b6a-3ace-4315-b086-499a0e521b76"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.cdns.find(id: '19f06b6a-3ace-4315-b086-499a0e521b76')

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

cdn, _, err := client.CDNs.Get(ctx, "19f06b6a-3ace-4315-b086-499a0e521b76")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1123
ratelimit-reset: 1415984218

Response Body

{
  "endpoint": {
    "id": "19f06b6a-3ace-4315-b086-499a0e521b76",
    "origin": "static-images.nyc3.digitaloceanspaces.com",
    "endpoint": "static-images.nyc3.cdn.digitaloceanspaces.com",
    "created_at": "2018-07-19T15:04:16Z",
    "certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf",
    "custom_domain": "static.example.com",
    "ttl": 3600
  }
}

List All CDN Endpoints

To list all of the CDN endpoints available on your account, send a GET request to /v2/cdn/endpoints.

The result will be a JSON object with a endpoints key. This will be set to an array of endpoint objects, each of which will contain the standard CDN endpoint attributes:

NameTypeDescription
idstringA unique ID that can be used to identify and reference a CDN endpoint.
originstringThe fully qualified domain name (FQDN) for the origin server which the provides the content for the CDN. This is currently restricted to a Space.
endpointstringThe fully qualified domain name (FQDN) from which the CDN-backed content is served.
created_atstringA time value given in ISO8601 combined date and time format that represents when the CDN endpoint was created.
ttlintegerThe amount of time the content is cached by the CDN's edge servers in seconds.
certificate_idstringThe ID of a DigitalOcean managed TLS certificate used for SSL when a custom subdomain is provided.
custom_domainstringThe fully qualified domain name (FQDN) of the custom subdomain used with the CDN Endpoint.

List All CDN Endpoints

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/cdn/endpoints"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

cdns = client.cdns.all
cdns.each

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

opt := &godo.ListOptions{
    Page:    1,
    PerPage: 200,
}

cdns, _, err := client.CDNs.List(ctx, opt)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4816
ratelimit-reset: 1444931833

Response Body

{
  "endpoints": [
    {
      "id": "19f06b6a-3ace-4315-b086-499a0e521b76",
      "origin": "static-images.nyc3.digitaloceanspaces.com",
      "endpoint": "static-images.nyc3.cdn.digitaloceanspaces.com",
      "created_at": "2018-07-19T15:04:16Z",
      "certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf",
      "custom_domain": "static.example.com",
      "ttl": 3600
    }
  ],
  "meta": {
    "total": 1
  },
  "links": {
  }
}

Update an Existing CDN Endpoint

To update the TTL, certificate ID, or the FQDN of the custom subdomain for an existing CDN endpoint, send a PUT request to /v2/cdn/endpoints/$ENDPOINT_ID.

NameTypeDescription
ttlintegerThe amount of time the content is cached by the CDN's edge servers in seconds.
certificate_idstringThe ID of a DigitalOcean managed TLS certificate used for SSL when a custom subdomain is provided.
custom_domainstringThe fully qualified domain name (FQDN) of the custom subdomain to be used with the CDN Endpoint. When used, a certificate_id must be provided as well.

The response will be a JSON object with a key called endpoint. The value of this will be an object that contains the standard attributes associated with a CDN endpoint:

NameTypeDescription
idstringA unique ID that can be used to identify and reference a CDN endpoint.
originstringThe fully qualified domain name (FQDN) for the origin server which the provides the content for the CDN. This is currently restricted to a Space.
endpointstringThe fully qualified domain name (FQDN) from which the CDN-backed content is served.
created_atstringA time value given in ISO8601 combined date and time format that represents when the CDN endpoint was created.
ttlintegerThe amount of time the content is cached by the CDN's edge servers in seconds.
certificate_idstringThe ID of a DigitalOcean managed TLS certificate used for SSL when a custom subdomain is provided.
custom_domainstringThe fully qualified domain name (FQDN) of the custom subdomain used with the CDN Endpoint.

Update an Existing CDN Endpoint

cURL Example

curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"ttl": 1800}' "https://api.digitalocean.com/v2/cdn/endpoints/19f06b6a-3ace-4315-b086-499a0e521b76"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.cdns.update_ttl(id: '19f06b6a-3ace-4315-b086-499a0e521b76', ttl: 1800)

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

updateRequest := &godo.CDNUpdateTTLRequest{TTL: 1800}
cdn, _, err := client.CDNs.UpdateTTL(ctx, "19f06b6a-3ace-4315-b086-499a0e521b76", updateRequest)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "ttl": 1800
}

Response Headers

content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Response Body

{
  "endpoint": {
    "id": "19f06b6a-3ace-4315-b086-499a0e521b76",
    "origin": "static-images.nyc3.digitaloceanspaces.com",
    "endpoint": "static-images.nyc3.cdn.digitaloceanspaces.com",
    "created_at": "2018-07-19T15:04:16Z",
    "ttl": 1800,
    "certificate_id": "892071a0-bb95-49bc-8021-3afd67a210bf",
    "custom_domain": "static.example.com"
  }
}

Delete a CDN Endpoint

To delete a specific CDN endpoint, send a DELETE request to /v2/cdn/endpoints/$ENDPOINT_ID.

A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.

Delete a CDN Endpoint

cURL Example

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/cdn/endpoints/19f06b6a-3ace-4315-b086-499a0e521b76"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.cdns.delete(id: '19f06b6a-3ace-4315-b086-499a0e521b76')

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

_, err := client.CDNs.Delete(ctx, "19f06b6a-3ace-4315-b086-499a0e521b76")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 204 No Content
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Purge the Cache for an Existing CDN Endpoint

To purge cached content from a CDN endpoint, send a DELETE request to /v2/cdn/endpoints/$ENDPOINT_ID/cache. The body of the request should include a files attribute containing a list of cached file paths to be purged. A path may be for a single file or may contain a wildcard (*) to recursively purge all files under a directory. When only a wildcard is provided, all cached files will be purged.

NameTypeDescriptionRequired
filesarray of stringsAn array of strings containing the path to the content to be purged from the CDN cache.true

A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.

Purge the Cache for an Existing CDN Endpoint

cURL Example

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"files": ["assets/img/hero.png","assets/css/*"]}' "https://api.digitalocean.com/v2/cdn/endpoints/19f06b6a-3ace-4315-b086-499a0e521b76/cache"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.cdns.flush_cache(
  id: '19f06b6a-3ace-4315-b086-499a0e521b76',
  files: ['assets/img/hero.png','assets/css/*']
)

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

flushRequest := &godo.CDNFlushCacheRequest{
    Files: []string{"assets/img/hero.png","assets/css/*"},
}

_, err := client.CDNs.FlushCache(ctx, "19f06b6a-3ace-4315-b086-499a0e521b76", flushRequest)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "files": [
    "assets/img/hero.png",
    "assets/css/*"
  ]
}

Response Headers

content-type: application/json; charset=utf-8
status: 204 No Content
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Certificates

In order to perform SSL termination on load balancers, DigitalOcean offers two types of SSL certificate management:

  • 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.
NameTypeDescription
idstringA unique ID that can be used to identify and reference a certificate.
namestringA unique human-readable name referring to a certificate.
not_afterstringA time value given in ISO8601 combined date and time format that represents the certificate's expiration date.
sha1_fingerprintstringA unique identifier generated from the SHA-1 fingerprint of the certificate.
created_atstringA time value given in ISO8601 combined date and time format that represents when the certificate was created.
dns_namesarray of stringsAn array of fully qualified domain names (FQDNs) for which the certificate was issued.
statestringA string representing the current state of the certificate. It may be "pending", "verified", or "error".
typestringA string representing the type of the certificate. The value will be "custom" for a user-uploaded certificate or "lets_encrypt" for one automatically generated with Let's Encrypt.

Create a New Custom Certificate

To upload new SSL certificate which you have previously generated, send a POST request to /v2/certificates. When uploading a user-generated certificate, the private_key, leaf_certificate, and optionally the certificate_chain attributes should be provided. The type must be set to "custom".

The available attributes and the conditions in which they are required are:

NameTypeDescriptionRequired
namestringA unique human-readable name referring to a certificate.Always
private_keystringThe contents of a PEM-formatted private-key corresponding to the SSL certificate.Custom
leaf_certificatestringThe contents of a PEM-formatted public SSL certificate.Custom
certificate_chainstringThe full PEM-formatted trust chain between the certificate authority's certificate and your domain's SSL certificate.
dns_namesarray of stringsAn array of fully qualified domain names (FQDNs) for which the certificate will be issued. The domains must be managed using DigitalOcean's DNS.Let's Encrypt
typestringA string representing the type of the certificate. The value should be "custom" for a user-uploaded certificate or "lets_encrypt" for one automatically generated with Let's Encrypt. If not provided, "custom" will be assumed by default.Always

The response will be a JSON object with a key called certificate. The value of this will be an object that contains the standard attributes associated with a certificate:

NameTypeDescription
idstringA unique ID that can be used to identify and reference a certificate.
namestringA unique human-readable name referring to a certificate.
not_afterstringA time value given in ISO8601 combined date and time format that represents the certificate's expiration date.
sha1_fingerprintstringA unique identifier generated from the SHA-1 fingerprint of the certificate.
created_atstringA time value given in ISO8601 combined date and time format that represents when the certificate was created.
dns_namesarray of stringsAn array of fully qualified domain names (FQDNs) for which the certificate was issued.
statestringA string representing the current state of the certificate. It may be "pending", "verified", or "error".
typestringA string representing the type of the certificate. The value will be "custom" for a user-uploaded certificate or "lets_encrypt" for one automatically generated with Let's Encrypt.

Create a New Custom Certificate

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name": "web-cert-01", "type": "custom", "private_key": "'"$(</path/to/privkey1.pem)"'","leaf_certificate": "'"$(</path/to/cert1.pem)"'","certificate_chain": "'"$(</path/to/fullchain1.pem)"'"}' "https://api.digitalocean.com/v2/certificates"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

key = File.open('/path/to/privkey1.pem', 'r'){ |file| file.read }
cert = File.open('/path/to/cert1.pem', 'r'){ |file| file.read }
chain = File.open('/path/to/fullchain1.pem', 'r'){ |file| file.read }

certificate = DropletKit::Certificate.new(
    name: 'web-cert-01',
    private_key: key,
    leaf_certificate: cert,
    certificate_chain: chain,
    type: 'custom'
)

client.certificates.create(certificate)

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

key, err := ioutil.ReadFile("/path/to/privkey1.pem")
if err != nil {
    fmt.Print(err)
}

cert, err := ioutil.ReadFile("/path/to/cert1.pem")
if err != nil {
    fmt.Print(err)
}

chain, err := ioutil.ReadFile("/path/to/fullchain1.pem")
if err != nil {
    fmt.Print(err)
}

createRequest := &godo.CertificateRequest{
    Name:             "web-cert-01",
    PrivateKey:       string(key),
    LeafCertificate:  string(cert),
    CertificateChain: string(chain),
    Type:             "custom",
}

certObj, _, err := client.Certificates.Create(ctx, createRequest)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "name": "web-cert-01",
  "type": "custom",
  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDBIZMz8pnK6V52\nSVf+CYssOfCQHAx5f0Ou5rYbq3xNh8VHAIYJCQ1QxQIxKSP6+uODSYrb2KWyurP1\nDwGb8OYm0J3syEDtCUQik1cpCzpeNlAZ2f8FzXyYQAqPopxdRpsFz8DtZnVvu86X\nwrE4oFPl9MReICmZfBNWylpV5qgFPoXyJ70ZAsTm3cEe3n+LBXEnY4YrVDRWxA3w\nZ2mzZ03HZ1hHrxK9CMnS829U+8sK+UneZpCO7yLRPuxwhmps0wpK/YuZZfRAKF1F\nZRnak/SIQ28rnWufmdg16YqqHgl5JOgnb3aslKRvL4dI2Gwnkd2IHtpZnTR0gxFX\nfqqbQwuRAgMBAAECggEBAILLmkW0JzOkmLTDNzR0giyRkLoIROqDpfLtjKdwm95l\n9NUBJcU4vCvXQITKt/NhtnNTexcowg8pInb0ksJpg3UGE+4oMNBXVi2UW5MQZ5cm\ncVkQqgXkBF2YAY8FMaB6EML+0En2+dGR/3gIAr221xsFiXe1kHbB8Nb2c/d5HpFt\neRpLVJnK+TxSr78PcZA8DDGlSgwvgimdAaFUNO2OqB9/0E9UPyKk2ycdff/Z6ldF\n0hkCLtdYTTl8Kf/OwjcuTgmA2O3Y8/CoQX/L+oP9Rvt9pWCEfuebiOmHJVPO6Y6xgtQVEXwmF1pDHH4Qtz/e6UZTdYeMl9G4aNO2CawwcaYECgYEA57imgSOG4XsJLRhK\nGGncV9R/xhy4AbDWLtAMzQRX4ktvKCaHWyQV2XK2we/cu29NLv2Y89WmerTNPOU+\nP8+pB31uty2ELySVn15QhKpQClVEAlxCnnNjXYrii5LOM80+lVmxvQwxVd8Yz8nj\nIntyioXNBEnYS7V2RxxFGgFun1cCgYEA1V3W+Uyamhq8JS5EY0FhyGcXdHd70K49\nW1ou7McIpncf9tM9acLS1hkI98rd2T69Zo8mKoV1V2hjFaKUYfNys6tTkYWeZCcJ\n3rW44j9DTD+FmmjcX6b8DzfybGLehfNbCw6n67/r45DXIV/fk6XZfkx6IEGO4ODt\nNfnvx4TuI1cCgYBACDiKqwSUvmkUuweOo4IuCxyb5Ee8v98P5JIE/VRDxlCbKbpx\npxEam6aBBQVcDi+n8o0H3WjjlKc6UqbW/01YMoMrvzotxNBLz8Y0QtQHZvR6KoCG\nRKCKstxTcWflzKuknbqN4RapAhNbKBDJ8PMSWfyDWNyaXzSmBdvaidbF1QKBgDI0\no4oD0Xkjg1QIYAUu9FBQmb9JAjRnW36saNBEQS/SZg4RRKknM683MtoDvVIKJk0E\nsAlfX+4SXQZRPDMUMtA+Jyrd0xhj6zmhbwClvDMr20crF3fWdgcqtft1BEFmsuyW\nJUMe5OWmRkjPI2+9ncDPRAllA7a8lnSV/Crph5N/AoGBAIK249temKrGe9pmsmAo\nQbNuYSmwpnMoAqdHTrl70HEmK7ob6SIVmsR8QFAkH7xkYZc4Bxbx4h1bdpozGB+/\nAangbiaYJcAOD1QyfiFbflvI1RFeHgrk7VIafeSeQv6qu0LLMi2zUbpgVzxt78Wg\neTuK2xNR0PIM8OI7pRpgyj1I\n-----END PRIVATE KEY-----",
  "leaf_certificate": "-----BEGIN CERTIFICATE-----\nMIIFFjCCA/6gAwIBAgISA0AznUJmXhu08/89ZuSPC/kRMA0GCSqGSIb3DQEBCwUA\nMEoxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MSMwIQYDVQQD\nExpMZXQncyBFbmNyeXB0IEF1dGhvcml0eSBYMzAeFw0xNjExMjQwMDIzMDBaFw0x\nNzAyMjIwMDIzMDBaMCQxIjAgBgNVBAMTGWNsb3VkLmFuZHJld3NvbWV0aGluZy5j\nb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDBIZMz8pnK6V52SVf+\nCYssOfCQHAx5f0Ou5rYbq3xNh8VWHIYJCQ1QxQIxKSP6+uODSYrb2KWyurP1DwGb\n8OYm0J3syEDtCUQik1cpCzpeNlAZ2f8FzXyYQAqPopxdRpsFz8DtZnVvu86XwrE4\noFPl9MReICmZfBNWylpV5qgFPoXyJ70ZAsTm3cEe3n+LBXEnY4YrVDRWxA3wZ2mz\nZ03HZ1hHrxK9CMnS829U+8sK+UneZpCO7yLRPuxwhmps0wpK/YuZZfRAKF1FZRna\nk/SIQ28rnWufmdg16YqqHgl5JOgnb3aslKRvL4dI2Gwnkd2IHtpZnTR0gxFXfqqb\nQwuRAgMBAAGjggIaMIICFjAOBgNVHQ8BAf8EBAMCBaAwHQYDVR0lBBYwFAYIKwYB\nBQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFLsAFcxAhFX1\nMbCnzr9hEO5rL4jqMB8GA1UdIwQYMBaAFKhKamMEfd265tE5t6ZFZe/zqOyhMHAG\nCCsGAQUFBwEBBGQwYjAvBggrBgEFBQcwAYYjaHR0cDovL29jc3AuaW50LXgzLmxl\ndHNlbmNyeXB0Lm9yZy8wLwYIKwYBBQUHMAKGI2h0dHA6Ly9jZXJ0LmludC14My5s\nZXRzZW5jcnlwdC5vcmcvMCQGA1UdEQQdMBuCGWNsb3VkLmFuZHJld3NvbWV0aGlu\nZy5jb20wgf4GA1UdIASB9jCB8zAIBgZngQwBAgWrgeYGCysGAQQBgt8TAQEBMIHW\nMCYGCCsGAQUFBwIBFhpodHRwOi8vY3BzLmxldHNlbmNyeXB0Lm9yZzCBqwYIKwYB\nBQUHAgIwgZ4MgZtUaGlzIENlcnRpZmljYXRlIG1heSBvbmx5IGJlIHJlbGllZCB1\ncG9uIGJ5IFJlbHlpbmcgUGFydGllcyBhbmQgb25seSQ2ziBhY2NvcmRhbmNlIHdp\ndGggdGhlIENlcnRpZmljYXRlIFBvbGljeSBmb3VuZCBhdCBodHRwczovL2xldHNl\nbmNyeXB0Lm9yZy9yZXBvc2l0b3J5LzANBgkqhkiG9w0BAQsFAAOCAQEAOZVQvrjM\nPKXLARTjB5XsgfyDN3/qwLl7SmwGkPe+B+9FJpfScYG1JzVuCj/SoaPaK34G4x/e\niXwlwOXtMOtqjQYzNu2Pr2C+I+rVmaxIrCUXFmC205IMuUBEeWXG9Y/HvXQLPabD\nD3Gdl5+Feink9SDRP7G0HaAwq13hI7ARxkL9p+UIY39X0dV3WOboW2Re8nrkFXJ7\nq9Z6shK5QgpBfsLjtjNsQzaGV3ve1gOg25aTJGearBWOvEjJNA1wGMoKVXOtYwm/\nWyWoVdCQ8HmconcbJB6xc0UZ1EjvzRr5ZIvSa5uHZD0L3m7/kpPWlAlFJ7hHASPu\nUlF1zblDmg2Iaw==\n-----END CERTIFICATE-----",
  "certificate_chain": "-----BEGIN CERTIFICATE-----\nMIIFFjCCA/6gAwIBAgISA0AznUJmXhu08/89ZuSPC/kRMA0GCSqGSIb3DQEBCwUA\nMEoxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MSMwIQYDVQQD\nExpMZXQncyBFbmNyeXB0IEF1dGhvcml0eSBYMzAeFw0xNjExMjQwMDIzMDBaFw0x\nNzAyMjIwMDIzMDBaMCQxIjAgBgNVBAMTGWNsb3VkLmFuZHJld3NvbWV0aGluZy5j\nb20wggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDBIZMz7tnK6V52SVf+\nCYssOfCQHAx5f0Ou5rYbq3xNh8VHAIYJCQ1QxQIxKSP6+uODSYrb2KWyurP1DwGb\n8OYm0J3syEDtCUQik1cpCzpeNlAZ2f8FzXyYQAqPopxdRpsFz8DtZnVvu86XwrE4\noFPl9MReICmZfBNWylpV5qgFPoXyJ70ZAsTm3cEe3n+LBXEnY4YrVDRWxA3wZ2mz\nZ03HZ1hHrxK9CMnS829U+8sK+UneZpCO7yLRPuxwhmps0wpK/YuZZfRAKF1FZRna\nk/SIQ28rnWufmdg16YqqHgl5JOgnb3aslKRvL4dI2Gwnkd2IHtpZnTR0gxFXfqqb\nQwuRAgMBAAGjggIaMIICFjAOBgNVHQ8BAf8EBAMCBaAwHQYDVR0lBBYwFAYIKwYB\nBQUHAwEGCCsGAQUFBwMCMAwGA1UdEwEB/wQCMAAwHQYDVR0OBBYEFLsAFcxAhFX1\nMbCnzr9hEO5rL4jqMB8GA1UdIwQYMBaAFKhKamMEfd265tE5t6ZFZe/zqOyhMHAG\nCCsGAQUFBwEBBGQwYjAvBggrBgEFBQcwAYYjaHR0cDovL29jc3AuaW50LXgzLmxl\ndHNlbmNyeXB0Lm9yZy8wLwYIKwYBBQUHMAKGI2h0dHA6Ly9jZXJ0LmludC14My5s\nZXRzZW5jcnlwdC5vcmcvMCQGA1UdEQQdMBuCGWNsb3VkLmFuZHJld3NvbWV0aGlu\nZy5jb20wgf4GA1UdIASB9jCB8zAIBgZngQwBAgEwgeWECysGAQQBgt8TAQEBMIHW\nMCYGCCsGAQUFBwIBFhpodHRwOi8vY3BzLmxldHNlbmNyeXB0Lm9yZzCBqwYIKwYB\nBQUHAgIwgZ4MgZtUaGlzIENlcnRpZmljYXRlIG1heSBvbmx5IGJlIHJlbGllZCB1\ncG9uIGJ5IFJlbHlpbmcgUGFydGllcyBhbmQgb25seSQ2ziBhY2NvcmRhbmNlIHdp\ndGggdGhlIENlcnRpZmljYXRlIFBvbGljeSBmb3VuZCBhdCBsdHRwczovL2xldHNl\nbmNyeXB0Lm9yZy9yZXBvc2l0b3J5LzANBgkqhkiG9w0BAQsFAAOCAQEAOZVQvrjM\nPKXLARTjB5XsgfyDN3/qwLl7SmwGkPe+B+9FJpfScYG1JzVuCj/SoaPaK34G4x/e\niXwlwOXtMOtqjQYzNu2Pr2C+I+rVmaxIrCUXFmC205IMuUBEeWXG9Y/HvXQLPabD\nD3Gdl5+Feink9SDRP7G0HaAwq13hI7ARxkL3o+UIY39X0dV3WOboW2Re8nrkFXJ7\nq9Z6shK5QgpBfsLjtjNsQzaGV3ve1gOg25aTJGearBWOvEjJNA1wGMoKVXOtYwm/\nWyWoVdCQ8HmconcbJB6xc0UZ1EjvzRr5ZIvSa5uHZD0L3m7/kpPWlAlFJ7hHASPu\nUlF1zblDmg2Iaw==\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIEkjCCA3qgAwIBAgIQCgFBQgAAAVOFc2oLheynCDANBgkqhkiG9w0BAQsFADA/\nMSQwIgYDVQQKExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMT\nDkRTVCBSb290IENBIFgzMB4XDTE2MDMxNzE2NDA0NloXDTIxMDMxNzE2NDA0Nlow\nSjELMAkGA1UEBhMCVVMxFjAUBgNVBAoTDUxldCdzIEVuY3J5cHQxIzAhBgNVBAMT\nGkxldCdzIEVuY3J5cHQgQXV0aG9yaXR5IFgzMIIBIjANBgkqhkiG9w0BAQEFAAOC\nAQ8AMIIBCgKCAQEAnNMM8FrlLsd3cl03g7NoYzDq1zUmGSXhvb418XCSL7e4S0EF\nq6meNQhY7LEqxGiHC6PjdeTm86dicbp5gWAf15Gan/PQeGdxyGkOlZHP/uaZ6WA8\nSMx+yk13EiSdRxta67nsHjcAHJyse6cF6s5K671B5TaYucv9bTyWaN8jKkKQDIZ0\nZ8h/pZq4UmEUEz9l6YKHy9v6Dlb2honzhT+Xhq+w3Brvaw2VFn3EK6BlspkENnWA\na6xK8xuQSXgvopZPKiAlKQTGdMDQMc2PMTiVFrqoM7hD8bEfwzB/onkxEz0tNvjj\n/PIzark5McWvxI0NHWQWM6r6hCm21AvA2H3DkwIPOIUo4IBfTCCAXkwEgYDVR0T\nAQH/BAgwBgEB/wIBADAOBgNVHQ8BAf8EBAMCAYYwfwYIKwYBBQUHAQEEczBxMDIG\nCCsGAQUFBzABhiZodHRwOi8vaXNyZy50cnVzdGlkLm9jc3AuaWRlbnRydXN0LmNv\nbTA7BggrBgEFBQcwAoYvaHR0cDovL2FwcHMuaWRlbnRydXN0LmNvbS9yb290cy9k\nc3Ryb290Y2F4My5wN2MwHwYDVR0jBBgwFoAUxKexpHsscfrb4UuQdf/EFWCFiRAw\nVAYDVR0gBE0wSzAIBgZngQwBAgEwPwYLKwYBBAGC3xMBAQEwMDAuBggrBgEFBQcC\nARYiaHR0cDovL2Nwcy5yb290LXgxLmxldHNlbmNyeXB0Lm9yZzA8BgNVHR8ENTAz\nMDGgL6AthitodHRwOi8vY3JsLmlkZW50cnVzdC5jb20vRFNUUk9PVENBWDNDUkwu\nY3JsMB0GA1UdDgQWBBSoSmpjBH3duubRObemRWXv86jsoTANBgkqhkiG9w0BAQsF\nAAOCAQEA3TPXEfNjWDjdGBX7CVW+dla5cEilaUcne8IkCJLxWh9KEik3JHRRHGJo\nuM2VcGfl96S8TihRzZvoroed6ti6WqEBmtzw3Wodatg+VyOeph4EYpr/1wXKtx8/\nwApIvJSwtmVi4MFU5aMqrSDE6ea73Mj2tcMyo5jMd6jmeWUHK8so/joWUoHOUgwu\nX4Po1QYz+3dszkDqMp4fklxBwXRsW10KXzPMTZ+sOPAveyxindmjkW8lGy+QsRlG\nPfZ+G6Z6h7mjem0Y+iWlkYcV4PIWL1iwBi8saCbGS5jN2p8M+X+Q7UNKEkROb3N6\nKOqkqm57TH2H3eDJAkSnh6/DNFu0Qg==\n-----END CERTIFICATE-----"
}

Response Headers

content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Response Body

{
  "certificate": {
    "id": "892071a0-bb95-49bc-8021-3afd67a210bf",
    "name": "web-cert-01",
    "not_after": "2017-02-22T00:23:00Z",
    "sha1_fingerprint": "dfcc9f57d86bf58e321c2c6c31c7a971be244ac7",
    "created_at": "2017-02-08T16:02:37Z",
    "dns_names": [
      ""
    ],
    "state": "verified",
    "type": "custom"
  }
}

Create a New Let's Encrypt Certificate

To generate a new SSL certificate using Let's Encrypt, send a POST request to /v2/certificates. When using Let's Encrypt to create a certificate, the dns_names attribute must be provided, and the type must be set to "lets_encrypt".

The available attributes and the conditions in which they are required are:

NameTypeDescriptionRequired
namestringA unique human-readable name referring to a certificate.Always
private_keystringThe contents of a PEM-formatted private-key corresponding to the SSL certificate.Custom
leaf_certificatestringThe contents of a PEM-formatted public SSL certificate.Custom
certificate_chainstringThe full PEM-formatted trust chain between the certificate authority's certificate and your domain's SSL certificate.
dns_namesarray of stringsAn array of fully qualified domain names (FQDNs) for which the certificate will be issued. The domains must be managed using DigitalOcean's DNS.Let's Encrypt
typestringA string representing the type of the certificate. The value should be "custom" for a user-uploaded certificate or "lets_encrypt" for one automatically generated with Let's Encrypt. If not provided, "custom" will be assumed by default.Always

The response will be a JSON object with a key called certificate. The value of this will be an object that contains the standard attributes associated with a certificate. The initial value of the certificate's state attribute will be "pending". When the certificate has been successfully issued by Let's Encrypt, this will transition to "verified" and be ready for use.

NameTypeDescription
idstringA unique ID that can be used to identify and reference a certificate.
namestringA unique human-readable name referring to a certificate.
not_afterstringA time value given in ISO8601 combined date and time format that represents the certificate's expiration date.
sha1_fingerprintstringA unique identifier generated from the SHA-1 fingerprint of the certificate.
created_atstringA time value given in ISO8601 combined date and time format that represents when the certificate was created.
dns_namesarray of stringsAn array of fully qualified domain names (FQDNs) for which the certificate was issued.
statestringA string representing the current state of the certificate. It may be "pending", "verified", or "error".
typestringA string representing the type of the certificate. The value will be "custom" for a user-uploaded certificate or "lets_encrypt" for one automatically generated with Let's Encrypt.

Create a New Let's Encrypt Certificate

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name": "le-cert-01", "type": "lets_encrypt", "dns_names": ["www.example.com","example.com"]}' "https://api.digitalocean.com/v2/certificates"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

certificate = DropletKit::Certificate.new(
    name: 'le-cert-01',
    dns_names: ['somedomain.com', 'www.somedomain.com'],
    type: 'lets_encrypt'
)

client.certificates.create(certificate)

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

createRequest := &godo.CertificateRequest{
    Name:     "le-cert-01",
    Type:     "lets_encrypt",
    DNSNames: []string{"example.com", "www.example.com"},
}

certObj, _, err := client.Certificates.Create(ctx, createRequest)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "name": "le-cert-01",
  "type": "lets_encrypt",
  "dns_names": [
    "www.example.com",
    "example.com"
  ]
}

Response Headers

content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Response Body

{
  "certificate": {
    "id": "3d2ead39-0a07-452a-be56-d9c5d1cd432c",
    "name": "le-cert-01",
    "not_after": "0001-01-01T00:00:00Z",
    "sha1_fingerprint": "",
    "created_at": "2019-05-01T19:11:39Z",
    "dns_names": [
      "www.example.com",
      "example.com"
    ],
    "state": "pending",
    "type": "lets_encrypt"
  }
}

Retrieve an Existing Certificate

To show information about an existing certificate, send a GET request to /v2/certificates/$CERTIFICATE_ID.

The response will be a JSON object with a certificate key. This will be set to an object containing the standard certificate attributes:

NameTypeDescription
idstringA unique ID that can be used to identify and reference a certificate.
namestringA unique human-readable name referring to a certificate.
not_afterstringA time value given in ISO8601 combined date and time format that represents the certificate's expiration date.
sha1_fingerprintstringA unique identifier generated from the SHA-1 fingerprint of the certificate.
created_atstringA time value given in ISO8601 combined date and time format that represents when the certificate was created.
dns_namesarray of stringsAn array of fully qualified domain names (FQDNs) for which the certificate was issued.
statestringA string representing the current state of the certificate. It may be "pending", "verified", or "error".
typestringA string representing the type of the certificate. The value will be "custom" for a user-uploaded certificate or "lets_encrypt" for one automatically generated with Let's Encrypt.

Retrieve an Existing Certificate

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/certificates/892071a0-bb95-49bc-8021-3afd67a210bf"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.certificates.find(id: '892071a0-bb95-49bc-8021-3afd67a210bf')

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

cert, _, err := client.Certificates.Get(ctx, "892071a0-bb95-49bc-8021-3afd67a210bf")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1123
ratelimit-reset: 1415984218

Response Body

{
  "certificate": {
    "id": "892071a0-bb95-49bc-8021-3afd67a210bf",
    "name": "web-cert-01",
    "not_after": "2017-02-22T00:23:00Z",
    "sha1_fingerprint": "dfcc9f57d86bf58e321c2c6c31c7a971be244ac7",
    "created_at": "2017-02-08T16:02:37Z",
    "dns_names": [
      ""
    ],
    "state": "verified",
    "type": "custom"
  }
}

List All Certificates

To list all of the certificates available on your account, send a GET request to /v2/certificates.

The result will be a JSON object with a certificates key. This will be set to an array of certificate objects, each of which will contain the standard certificate attributes:

NameTypeDescription
idstringA unique ID that can be used to identify and reference a certificate.
namestringA unique human-readable name referring to a certificate.
not_afterstringA time value given in ISO8601 combined date and time format that represents the certificate's expiration date.
sha1_fingerprintstringA unique identifier generated from the SHA-1 fingerprint of the certificate.
created_atstringA time value given in ISO8601 combined date and time format that represents when the certificate was created.
dns_namesarray of stringsAn array of fully qualified domain names (FQDNs) for which the certificate was issued.
statestringA string representing the current state of the certificate. It may be "pending", "verified", or "error".
typestringA string representing the type of the certificate. The value will be "custom" for a user-uploaded certificate or "lets_encrypt" for one automatically generated with Let's Encrypt.

List All Certificates

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/certificates"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

certificates = client.certificates.all
certificates.each

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

opt := &godo.ListOptions{
    Page:    1,
    PerPage: 200,
}

certs, _, err := client.Certificates.List(ctx, opt)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4816
ratelimit-reset: 1444931833

Response Body

{
  "certificates": [
    {
      "id": "892071a0-bb95-49bc-8021-3afd67a210bf",
      "name": "web-cert-01",
      "not_after": "2017-02-22T00:23:00Z",
      "sha1_fingerprint": "dfcc9f57d86bf58e321c2c6c31c7a971be244ac7",
      "created_at": "2017-02-08T16:02:37Z",
      "dns_names": [
        ""
      ],
      "state": "verified",
      "type": "custom"
    },
    {
      "id": "ba9b9c18-6c59-46c2-99df-70da170a42ba",
      "name": "web-cert-02",
      "not_after": "2018-06-07T17:44:12Z",
      "sha1_fingerprint": "479c82b5c63cb6d3e6fac4624d58a33b267e166c",
      "created_at": "2018-03-09T18:44:11Z",
      "dns_names": [
        "www.example.com",
        "example.com"
      ],
      "state": "verified",
      "type": "lets_encrypt"
    }
  ],
  "links": {
  },
  "meta": {
    "total": 2
  }
}

Delete a Certificate

To delete a specific certificate, send a DELETE request to /v2/certificates/$CERTIFICATE_ID.

A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.

Delete a Certificate

cURL Example

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/certificates/892071a0-bb95-49bc-8021-3afd67a210bf"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.certificates.delete(id: '892071a0-bb95-49bc-8021-3afd67a210bf')

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

_, err := client.Certificates.Delete(ctx, "892071a0-bb95-49bc-8021-3afd67a210bf")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 204 No Content
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Container Registry

DigitalOcean offers you the ability to create a private container registry to store your Docker images. This container registry runs inside the same datacenters as Kubernetes clusters and droplets, ensuring reliable and performant rollout of image deployments.

A subscription is required to use registry. You can create one registry per DigitalOcean account, but each registry can contain multiple image repositories. The number of image repositories allowed depends on the subscription tier selected.

The standard attributes of a container registry are:

NameTypeDescription
namestringThe name of the container registry to validate.
created_atstringA time value given in ISO8601 combined date and time format that represents when the registry was created.
storage_usage_bytesintegerThe amount of storage used in the registry.
storage_usage_bytes_updated_atstringThe time at which the storage usage was updated. Storage usage is calculated asynchronously, and may not immediately reflect pushes to the registry.

The standard attributes of a subscription are:

NameTypeDescription
tierobjectThe subscription tier.
created_atstringThe time at which the subscription was created.
updated_atstringThe time at which the subscription was last updated.

A Container Registry contains one or more repositories that represent a logical grouping of your container tags.

The standard attributes of a container repository are:

NameTypeDescription
registry_namestringThe name of the container registry.
namestringThe name of the repository.
latest_tagobjectThe latest tag of the repository.
tag_countintegerThe number of tags in the repository.

The repository latest_tag attribute is an object made up of the following attributes:

NameTypeDescription
registry_namestringThe name of the container registry.
repository_namestringThe name of the repository.
tagstringThe name of the tag.
manifest_digeststringThe digest of the manifest associated with the tag.
compressed_size_bytesintegerThe compressed size of the tag in bytes.
size_bytesintegerThe uncompressed size of the tag in bytes (this size is calculated asynchronously so it may not be immediately available).
updated_atstringThe time the tag was last updated.

Configure Container Registry

To configure your container registry, send a POST request to /v2/registry.

The attribute values that must be set to configure your registry are:

NameTypeDescriptionRequired
namestringA globally unique name for the container registry. Must be lowercase and be composed only of numbers, letters and "-", up to a limit of 63 characters.true
subscription_tier_slugstringThe slug of the subscription tier to sign up for. Valid values can be retrieved using the options endpoint.true

The name becomes part of the URL for images stored in the registry. For example, if your registry is called example, an image in it will have the URL registry.digitalocean.com/example/image:tag.

The response will be a JSON object containing information about your registry:

NameTypeDescription
namestringThe name of the container registry to validate.
created_atstringA time value given in ISO8601 combined date and time format that represents when the registry was created.
storage_usage_bytesintegerThe amount of storage used in the registry.
storage_usage_bytes_updated_atstringThe time at which the storage usage was updated. Storage usage is calculated asynchronously, and may not immediately reflect pushes to the registry.

A subscription is also created for you when you create a registry. Its details are included as a separate JSON object in the response:

NameTypeDescription
tierobjectThe subscription tier.
created_atstringThe time at which the subscription was created.
updated_atstringThe time at which the subscription was last updated.

Configure Container Registry

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name": "example", "subscription_tier_slug": "basic"}' "https://api.digitalocean.com/v2/registry"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "name": "example",
  "subscription_tier_slug": "basic"
}

Response Headers

content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 5000
ratelimit-remaining: 4821
ratelimit-reset: 1444931833

Response Body

{
  "registry": {
    "name": "example",
    "created_at": "2020-11-04T21:39:49.530562231Z",
    "storage_usage_bytes": 0,
    "storage_usage_updated_at": "2020-11-04T21:39:49.530562231Z"
  },
  "subscription": {
    "tier": {
      "name": "Basic",
      "slug": "basic",
      "included_repositories": 5,
      "included_storage_bytes": 5368709120,
      "allow_storage_overage": true,
      "included_bandwidth_bytes": 5368709120,
      "monthly_price_in_cents": 500
    },
    "created_at": "2020-11-04T21:39:49.530562231Z",
    "updated_at": "2020-11-04T21:39:49.530562231Z"
  }
}

Get Container Registry Information

To get information about your container registry, send a GET request to /v2/registry.

The response will be a JSON object containing information about your registry:

NameTypeDescription
namestringThe name of the container registry to validate.
created_atstringA time value given in ISO8601 combined date and time format that represents when the registry was created.
storage_usage_bytesintegerThe amount of storage used in the registry.
storage_usage_bytes_updated_atstringThe time at which the storage usage was updated. Storage usage is calculated asynchronously, and may not immediately reflect pushes to the registry.

Get Container Registry Information

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/registry"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4821
ratelimit-reset: 1444931833

Response Body

{
  "registry": {
    "name": "example"
  }
}

Get Docker Credentials for Container Registry

In order to access your container registry with the Docker client or from a Kubernetes cluster, you will need to configure authentication. The necessary JSON configuration can be retrieved by sending a GET request to /v2/registry/docker-credentials.

The response will be in the format of a Docker config.json file. To use the config in your Kubernetes cluster, create a Secret with:

kubectl create secret generic docr \
  --from-file=.dockerconfigjson=config.json \
  --type=kubernetes.io/dockerconfigjson

By default, the returned credentials have read-only access to your registry and cannot be used to push images. This is appropriate for most Kubernetes clusters. To retrieve read/write credentials, suitable for use with the Docker client or in a CI system, read_write may be provided as query parameter. For example: /v2/registry/docker-credentials?read_write=true

By default, the returned credentials will not expire. To retrieve credentials with an expiry set, expiry_seconds may be provided as a query paremeter. For example: /v2/registry/docker-credentials?expiry_seconds=3600 will return credentials that expire after one hour.

Get Docker Credentials for Container Registry

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/registry/docker-credentials

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4821
ratelimit-reset: 1444931833

Response Body

{
  "auths": {
    "registry.digitalocean.com": {
      "auth": "YjdkMDNhNjk0N2IyMTdlZmI2ZjNlYzNiZDM1MDQ1ODI6YjdkMDNhNjk0N2IyMTdlZmI2ZjNlYzNiZDM1MDQ1ODIK"
    }
  }
}

Get Subscription Information

A subscription is automatically created when you configure your container registry. To get information about your subscription, send a GET request to /v2/registry/subscription.

The response will be a JSON object containing information about your subscription:

NameTypeDescription
tierobjectThe subscription tier.
created_atstringThe time at which the subscription was created.
updated_atstringThe time at which the subscription was last updated.

Get Subscription Information

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/registry/subscription"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4821
ratelimit-reset: 1444931833

Response Body

{
  "subscription": {
    "tier": {
      "name": "Basic",
      "slug": "basic",
      "included_repositories": 5,
      "included_storage_bytes": 5368709120,
      "allow_storage_overage": true,
      "included_bandwidth_bytes": 5368709120,
      "monthly_price_in_cents": 500
    },
    "created_at": "2020-11-04T21:39:50Z",
    "updated_at": "2020-11-04T21:39:50Z"
  }
}

Update Subscription Tier

After creating your registry, you can switch to a different subscription tier to better suit your needs. To do this, send a POST request to /v2/registry/subscription

.

The attribute values that must be set to update your subscription tier are:

NameTypeDescription
tier_slugstringThe slug of the new tier for the subscription. Valid values can be retrieved using the options endpoint.

The response will be a JSON object containing updated information about your subscription:

NameTypeDescription
tierobjectThe subscription tier.
created_atstringThe time at which the subscription was created.
updated_atstringThe time at which the subscription was last updated.

Update Subscription Tier

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"tier_slug": "professional"}' "https://api.digitalocean.com/v2/registry/subscription"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "tier_slug": "professional"
}

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4821
ratelimit-reset: 1444931833

Response Body

{
  "subscription": {
    "tier": {
      "name": "Professional",
      "slug": "professional",
      "included_repositories": 0,
      "included_storage_bytes": 107374182400,
      "allow_storage_overage": true,
      "included_bandwidth_bytes": 107374182400,
      "monthly_price_in_cents": 2000
    },
    "created_at": "2020-11-04T21:39:50Z",
    "updated_at": "2020-11-04T21:39:50Z"
  }
}

Delete Container Registry

To delete your container registry, destroying all container image data stored in it, send a DELETE request to /v2/registry.

No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

Delete Container Registry

cURL Example

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/registry"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 204 No Content
ratelimit-limit: 5000
ratelimit-remaining: 4821
ratelimit-reset: 1444931833

Validate a Container Registry Name

To validate a container registry name, send a POST request to /v2/registry/validate-name.

The attribute values that must be set to validate a registry name are:

NameTypeDescriptionRequired
namestringA globally unique name for the container registry. Must be lowercase and be composed only of numbers, letters and "-", up to a limit of 63 characters.true
subscription_tier_slugstringThe slug of the subscription tier to sign up for. Valid values can be retrieved using the options endpoint.true

No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

Validate a Container Registry Name

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/registry/validate-name"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "name": "example"
}

Response Headers

content-type: application/json; charset=utf-8
status: 204 No Content
ratelimit-limit: 5000
ratelimit-remaining: 4821
ratelimit-reset: 1444931833

List All Container Registry Repositories

To list all repositories in your container registry, send a GET request to /v2/registry/$REGISTRY_NAME/repositories.

The response body will be a JSON object with a key of repositories. This will be set to an array containing objects representing each Repository. These will contain the standard Repository attributes:

NameTypeDescription
registry_namestringThe name of the container registry.
namestringThe name of the repository.
latest_tagobjectThe latest tag of the repository.
tag_countintegerThe number of tags in the repository.

The repository latest_tag attribute is an object made up of the following attributes:

NameTypeDescription
registry_namestringThe name of the container registry.
repository_namestringThe name of the repository.
tagstringThe name of the tag.
manifest_digeststringThe digest of the manifest associated with the tag.
compressed_size_bytesintegerThe compressed size of the tag in bytes.
size_bytesintegerThe uncompressed size of the tag in bytes (this size is calculated asynchronously so it may not be immediately available).
updated_atstringThe time the tag was last updated.

List All Container Registry Repositories

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/registry/example/repositories"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4821
ratelimit-reset: 1444931833

Response Body

{
  "repositories": [
    {
      "registry_name": "example",
      "name": "repo-1",
      "latest_tag": {
        "registry_name": "example",
        "repository": "repo-1",
        "tag": "latest",
        "manifest_digest": "sha256:cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221",
        "compressed_size_bytes": 2803255,
        "size_bytes": 5861888,
        "updated_at": "2020-04-09T23:54:25Z"
      },
      "tag_count": 1
    }
  ],
  "meta": {
    "total": 1
  }
}

List All Container Registry Repository Tags

To list all tags in your container registry repository, send a GET request to /v2/registry/$REGISTRY_NAME/repositories/$REPOSITORY_NAME/tags.

The response body will be a JSON object with a key of tags. This will be set to an array containing objects representing each Tag. These will contain the standard Tag attributes:

NameTypeDescription
registry_namestringThe name of the container registry.
repository_namestringThe name of the repository.
tagstringThe name of the tag.
manifest_digeststringThe digest of the manifest associated with the tag.
compressed_size_bytesintegerThe compressed size of the tag in bytes.
size_bytesintegerThe uncompressed size of the tag in bytes (this size is calculated asynchronously so it may not be immediately available).
updated_atstringThe time the tag was last updated.

Note that if your repository name contains / characters, it must be URL-encoded in the request URL. For example, to list tags for registry.digitalocean.com/example/my/repo, the path would be /v2/registry/example/repositories/my%2Frepo/tags.

List All Container Registry Repository Tags

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/registry/example/repositories/repo-1/tags"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4821
ratelimit-reset: 1444931833

Response Body

{
  "tags": [
    {
      "registry_name": "example",
      "repository": "repo-1",
      "tag": "latest",
      "manifest_digest": "sha256:cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221",
      "compressed_size_bytes": 2803255,
      "size_bytes": 5861888,
      "updated_at": "2020-04-09T23:54:25Z"
    }
  ],
  "meta": {
    "total": 1
  }
}

Delete Container Registry Repository Tag

To delete a container repository tag, send a DELETE request to /v2/registry/$REGISTRY_NAME/repositories/$REPOSITORY_NAME/tags/$TAG.

No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

Note that if your repository name contains / characters, it must be URL-encoded in the request URL. For example, to delete registry.digitalocean.com/example/my/repo:mytag, the path would be /v2/registry/example/repositories/my%2Frepo/tags/mytag.

Delete Container Registry Repository Tag

cURL Example

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/registry/example/repositories/repo-1/tags/mytag"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 204 No Content
ratelimit-limit: 5000
ratelimit-remaining: 4821
ratelimit-reset: 1444931833

Delete Container Registry Repository Manifest

To delete a container repository manifest by digest, send a DELETE request to /v2/registry/$REGISTRY_NAME/repositories/$REPOSITORY_NAME/digests/$MANIFEST_DIGEST.

No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.

Note that if your repository name contains / characters, it must be URL-encoded in the request URL. For example, to delete registry.digitalocean.com/example/my/repo@sha256:abcd, the path would be /v2/registry/example/repositories/my%2Frepo/digests/sha256:abcd.

Delete Container Registry Repository Manifest

cURL Example

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/registry/example/repositories/repo-1/digests/sha256:cb8a924afdf0229ef7515d9e5b3024e23b3eb03ddbba287f4a19c6ac90b8d221"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 204 No Content
ratelimit-limit: 5000
ratelimit-remaining: 4821
ratelimit-reset: 1444931833

Start Garbage Collection

Garbage collection enables users to clear out unreferenced blobs (layer & manifest data) after deleting one or more manifests from a repository. If there are no unreferenced blobs resulting from the deletion of one or more manifests, garbage collection is effectively a noop. See here for more information about how and why you should clean up your container registry periodically.

To request a garbage collection run on your registry, send a POST request to /v2/registry/$REGISTRY_NAME/garbage-collection. This will initiate the following sequence of events on your registry.

  • Set the registry to read-only mode, meaning no further write-scoped JWTs will be issued to registry clients. Existing write-scoped JWTs will continue to work until they expire which can take up to 15 minutes.
  • Wait until all existing write-scoped JWTs have expired.
  • Scan all registry manifests to determine which blobs are unreferenced.
  • Delete all unreferenced blobs from the registry.
  • Record the number of blobs deleted and bytes freed, mark the garbage collection status as "success".
  • Remove the read-only mode restriction from the registry, meaning write-scoped JWTs will once again be issued to registry clients.

Start Garbage Collection

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/registry/example/garbage-collection"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

gc, resp, err := client.Registry.StartGarbageCollection(ctx, "example")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 5000
ratelimit-remaining: 4821
ratelimit-reset: 1444931833

Response Body

{
  "garbage_collection": {
    "uuid": "example-gc-uuid",
    "registry_name": "example",
    "blobs_deleted": 42,
    "status": "requested",
    "created_at": "2020-07-28T18:00:00Z",
    "updated_at": "2020-07-28T18:00:00Z",
    "freed_bytes": 666
  }
}

Get Active Garbage Collection

To get information about the currently-active garbage collection for a registry, send a GET request to /v2/registry/$REGISTRY_NAME/garbage-collection.

The response will be a JSON object with a key of garbage_collection. This will be a json object with attributes representing the currently-active garbage collection:

NameTypeDescription
uuidstringA string specifying the UUID of the garbage collection.
registry_namestringThe name of the container registry.
statusstringThe current status of this garbage collection. Valid values include: 'requested','waiting for write JWTs to expire','scanning manifests','deleting unreferenced blobs''cancelling','failed','succeeded','cancelled'
created_atstringThe time the garbage collection was created.
updated_atstringThe time the garbage collection was last updated.
blobs_deletedintegerThe number of blobs deleted as a result of this garbage collection.
freed_bytesintegerThe number of bytes freed as a result of this garbage collection.

Get Active Garbage Collection

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/registry/example/garbage-collection"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

gc, resp, err := client.Registry.GetGarbageCollection(ctx, "example")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4821
ratelimit-reset: 1444931833

Response Body

{
  "garbage_collection": {
    "uuid": "example-gc-uuid",
    "registry_name": "example",
    "blobs_deleted": 42,
    "status": "scanning_manifests",
    "created_at": "2020-07-28T18:00:00Z",
    "updated_at": "2020-07-28T18:00:00Z",
    "freed_bytes": 666
  }
}

List Garbage Collections

To get information about past garbage collections for a registry, send a GET request to /v2/registry/$REGISTRY_NAME/garbage-collections.

The response will be a JSON object with a key of garbage_collections. This will be set to an array containing objects representing each past garbage collection. Each will contain the standard Garbage Collection attributes:

NameTypeDescription
uuidstringA string specifying the UUID of the garbage collection.
registry_namestringThe name of the container registry.
statusstringThe current status of this garbage collection. Valid values include: 'requested','waiting for write JWTs to expire','scanning manifests','deleting unreferenced blobs''cancelling','failed','succeeded','cancelled'
created_atstringThe time the garbage collection was created.
updated_atstringThe time the garbage collection was last updated.
blobs_deletedintegerThe number of blobs deleted as a result of this garbage collection.
freed_bytesintegerThe number of bytes freed as a result of this garbage collection.

List Garbage Collections

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/registry/example/garbage-collections"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

gcs, resp, err := client.Registry.GetGarbageCollection(ctx, "example", &godo.ListOptions{
  Page:    1,
  PerPage: 200,
})

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4821
ratelimit-reset: 1444931833

Response Body

{
  "garbage_collections": [
    {
      "uuid": "example-gc-uuid",
      "registry_name": "example",
      "blobs_deleted": 42,
      "status": "cancelled",
      "created_at": "2020-07-28T18:00:00Z",
      "updated_at": "2020-07-28T18:00:00Z",
      "freed_bytes": 666
    }
  ],
  "meta": {
    "total": 1
  }
}

Update Garbage Collection

To cancel the currently-active garbage collection for a registry, send a PUT request to /v2/registry/$REGISTRY_NAME/garbage-collection/$GC_UUID and specify one or more of the attributes below.

NameTypeDescription
cancelboolA boolean value indicating that the garbage collection should be cancelled.

The response will be a JSON object with a key of garbage_collection. This will be a json object with attributes representing the currently-active garbage collection:

NameTypeDescription
uuidstringA string specifying the UUID of the garbage collection.
registry_namestringThe name of the container registry.
statusstringThe current status of this garbage collection. Valid values include: 'requested','waiting for write JWTs to expire','scanning manifests','deleting unreferenced blobs''cancelling','failed','succeeded','cancelled'
created_atstringThe time the garbage collection was created.
updated_atstringThe time the garbage collection was last updated.
blobs_deletedintegerThe number of blobs deleted as a result of this garbage collection.
freed_bytesintegerThe number of bytes freed as a result of this garbage collection.

Update Garbage Collection

cURL Example

curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/registry/example/garbage-collection/example-gc-uuid"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

gc, _, err := client.Registry.UpdateGarbageCollection(rs.ctx, "example", "example-gc-uuid",
  &godo.UpdateGarbageCollectionRequest{
   Cancel: true,
})

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "cancel": true
}

Response Headers

content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 5000
ratelimit-remaining: 4821
ratelimit-reset: 1444931833

Response Body

{
  "garbage_collection": {
    "uuid": "example-gc-uuid",
    "registry_name": "example",
    "blobs_deleted": 42,
    "status": "cancelled",
    "created_at": "2020-07-28T18:00:00Z",
    "updated_at": "2020-07-28T18:00:00Z",
    "freed_bytes": 666
  }
}

List Available Subscription Tiers

There are multiple subscription tiers available for container registry. Each tier allows a different number of image repositories to be created in your registry, and has a different amount of storage and transfer included.

To list the available subscription tiers, send a GET request to /v2/registry/options.

The response will be a JSON object with a key called subscription_tiers listing the available tiers.

NameTypeDescription
subscription_tiersarray of objectsThe available subscription tiers.

The subscription_tiers attribute will contain an array of objects with the following attributes:

NameTypeDescription
namestringThe human-readable name of the tier.
slugstringThe slug used in the API to request the tier.
included_repositoriesintegerThe number of repositories that can be created in a registry with the tier.
included_storage_bytesintegerThe amount of storage, in bytes, included in the tier.
allow_storage_overageboolA boolean value indicating whether the included storage for the tier can be exceeded. If true, any storage overage is billable.
included_bandwidth_bytesintegerThe amount of monthly transfer, in bytes, included in the tier. Unlimited transfer within DigitalOcean's network is included in all tiers.
monthly_price_in_centsintegerThe monthly price of subscriptions using the tier in US cents.
eligibleboolA boolean value indicating whether an existing subscription can be updated to use this tier. Present only in tiers returned as part of the options endpoint.
eligibility_reasonsarray of stringsWhen `eligibility` is false, a list of reasons why the tier is not available for selection. Valid values include: 'OverRepositoryLimit','OverStorageLimit'.

List Available Subscription Tiers

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/registry/options"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 838
ratelimit-reset: 1415984218

Response Body

{
  "options": {
    "subscription_tiers": [
      {
        "name": "Starter",
        "slug": "starter",
        "included_repositories": 1,
        "included_storage_bytes": 524288000,
        "allow_storage_overage": false,
        "included_bandwidth_bytes": 524288000,
        "monthly_price_in_cents": 0,
        "eligible": false,
        "eligibility_reasons": [
          "OverRepositoryLimit",
          "OverStorageLimit"
        ]
      },
      {
        "name": "Basic",
        "slug": "basic",
        "included_repositories": 5,
        "included_storage_bytes": 5368709120,
        "allow_storage_overage": true,
        "included_bandwidth_bytes": 5368709120,
        "monthly_price_in_cents": 500,
        "eligible": true
      },
      {
        "name": "Professional",
        "slug": "professional",
        "included_repositories": 0,
        "included_storage_bytes": 107374182400,
        "allow_storage_overage": true,
        "included_bandwidth_bytes": 107374182400,
        "monthly_price_in_cents": 2000,
        "eligible": true
      }
    ]
  }
}

Databases

DigitalOcean's managed database service simplifies the creation and management of highly available database clusters. Currently, it offers support for PostgreSQL, Redis, and MySQL.

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.

The size of individual nodes in a database cluster is represented by a human-readable slug. These slugs denote the underlying Droplet class, amount of RAM, and CPU count for the node. Database clusters may be deployed in a multi-node, highly available configuration. In addition to the primary node, up to two standby nodes may be added to a cluster with one exception. High availability configurations are not available when using the smallest node size. The currently available sizes and their corresponding slugs are:

Size Slug RAM CPU Storage High Availability Plans
db-s-1vcpu-1gb 1 GB 1 vCPU 10 GB False
db-s-1vcpu-2gb 2 GB 1 vCPU 25 GB True
db-s-2vcpu-4gb 4 GB 2 vCPU 38 GB True
db-s-4vcpu-8gb 8 GB 4 vCPU 115 GB True
db-s-6vcpu-16gb 16 GB 6 vCPU 270 GB True
db-s-8vcpu-32gb 32 GB 8 vCPU 580 GB True
db-s-16vcpu-64gb 64 GB 16 vCPU 1.12 TB True

The standard attributes of a database cluster are:

NameTypeDescription
idstringA unique ID that can be used to identify and reference a database cluster.
namestringA unique, human-readable name referring to a database cluster.
enginestringA slug representing the database engine used for the cluster. The possible values are: "pg" for PostgreSQL, "mysql" for MySQL, and "redis" for Redis.
versionstringA string representing the version of the database engine in use for the cluster.
connectionobjectAn object containing the information required to connect to the database (see below).
private_connectionobjectAn object containing the information required to connect to the database via the private network (see below).
usersarray of objectsAn array containing objects describing the database's users (see below).
db_namesarray of stringsAn array of strings containing the names of databases created in the database cluster.
num_nodesintegerThe number of nodes in the database cluster.
sizestringThe slug identifier representing the size of the nodes in the database cluster.
regionstringThe slug identifier for the region where the database cluster is located.
statusstringA string representing the current status of the database cluster. Possible values include creating, online, resizing, and migrating.
maintenance_windowobjectAn object containing information about any pending maintenance for the database cluster and when it will occur (see below).
created_atstringA time value given in ISO8601 combined date and time format that represents when the database cluster was created.
tagsarrayAn array of tags that have been applied to the database cluster.
private_network_uuidstringA string specifying the UUID of the VPC to which the database cluster is assigned.

The embedded connection and private_connection objects contain the information needed to access the database cluster. Their attributes are identical, but the values for private_connection.uri and private_connection.host will contain FQDNs only accessible from resources (e.g. Droplets or Kubernetes clusters) within your account and in the same region.

NameTypeDescription
uristringA connection string in the format accepted by the psql command. This is provided as a convenience and should be able to be constructed by the other attributes.
databasestringThe name of the default database.
hoststringThe FQDN pointing to the database cluster's current primary node.
portintegerThe port on which the database cluster is listening.
userstringThe default user for the database.
passwordstringThe randomly generated password for the default user.
sslbooleanA boolean value indicating if the connection should be made over SSL.

Create a New Database Cluster

To create a database cluster, send a POST request to /v2/databases specifying the following attributes in the JSON body:

NameTypeDescriptionRequired
namestringA unique, human-readable name for the database cluster.true
enginestringA slug representing the database engine to be used for the cluster. The possible values are: "pg" for PostgreSQL, "mysql" for MySQL, and "redis" for Redis. true
versionstringA string representing the version of the database engine to use for the cluster. If excluded, the specified engine's default version is used. The available versions for PostgreSQL are "10" and "11" defaulting to the later. For MySQL, the only available version is "8". For Redis, the only available version is "5".
sizestringA slug identifier representing the size of the nodes in the database cluster.true
regionstringA slug identifier for the region where the database cluster will be created.true
num_nodesintegerThe number of nodes in the database cluster. Valid values are are 1-3. In addition to the primary node, up to two standby nodes may be added for highly available configurations. The value is inclusive of the primary node. For example, setting the value to 2 will provision a database cluster with a primary node and one standby node.true
tagsarrayA flat array of tag names as strings to apply to the database cluster after it is created. Tag names can either be existing or new tags.
private_network_uuidstringA string specifying the UUID of the VPC to which the database cluster will be assigned. If excluded, the cluster will be assigned to your account's default VPC for the region.

The response will be a JSON object with a key called database. The value of this will be an object that contains the standard attributes associated with a database cluster. The initial value of the database cluster's status attribute will be creating. When the cluster is ready to receive traffic, this will transition to online.

NameTypeDescription
idstringA unique ID that can be used to identify and reference a database cluster.
namestringA unique, human-readable name referring to a database cluster.
enginestringA slug representing the database engine used for the cluster. The possible values are: "pg" for PostgreSQL, "mysql" for MySQL, and "redis" for Redis.
versionstringA string representing the version of the database engine in use for the cluster.
connectionobjectAn object containing the information required to connect to the database (see below).
private_connectionobjectAn object containing the information required to connect to the database via the private network (see below).
usersarray of objectsAn array containing objects describing the database's users (see below).
db_namesarray of stringsAn array of strings containing the names of databases created in the database cluster.
num_nodesintegerThe number of nodes in the database cluster.
sizestringThe slug identifier representing the size of the nodes in the database cluster.
regionstringThe slug identifier for the region where the database cluster is located.
statusstringA string representing the current status of the database cluster. Possible values include creating, online, resizing, and migrating.
maintenance_windowobjectAn object containing information about any pending maintenance for the database cluster and when it will occur (see below).
created_atstringA time value given in ISO8601 combined date and time format that represents when the database cluster was created.
tagsarrayAn array of tags that have been applied to the database cluster.
private_network_uuidstringA string specifying the UUID of the VPC to which the database cluster is assigned.

The embedded connection and private_connection objects will contain the information needed to access the database cluster:

NameTypeDescription
uristringA connection string in the format accepted by the psql command. This is provided as a convenience and should be able to be constructed by the other attributes.
databasestringThe name of the default database.
hoststringThe FQDN pointing to the database cluster's current primary node.
portintegerThe port on which the database cluster is listening.
userstringThe default user for the database.
passwordstringThe randomly generated password for the default user.
sslbooleanA boolean value indicating if the connection should be made over SSL.

Create a New Database Cluster

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name": "backend", "engine": "pg", "version": "10", "region": "nyc3", "size": "db-s-2vcpu-4gb", "num_nodes": 2, "tags": ["production"]}' "https://api.digitalocean.com/v2/databases"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

createRequest := &godo.DatabaseCreateRequest{
    Name:       "backend",
    EngineSlug: "pg",
    Version:    "10",
    Region:     "nyc3",
    SizeSlug:   "db-s-2vcpu-4gb",
    NumNodes:   2,
}

cluster, _, err := client.Databases.Create(ctx, createRequest)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "name": "backend",
  "engine": "pg",
  "version": "10",
  "region": "nyc3",
  "size": "db-s-2vcpu-4gb",
  "num_nodes": 2,
  "tags": [
    "production"
  ]
}

Response Headers

content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Response Body

{
  "database": {
    "id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
    "name": "backend",
    "engine": "pg",
    "version": "10",
    "connection": {
      "uri": "postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require",
      "database": "",
      "host": "backend-do-user-19081923-0.db.ondigitalocean.com",
      "port": 25060,
      "user": "doadmin",
      "password": "wv78n3zpz42xezdk",
      "ssl": true
    },
    "private_connection": {
      "uri": "postgres://doadmin:wv78n3zpz42xezdk@private-backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require",
      "database": "",
      "host": "private-backend-do-user-19081923-0.db.ondigitalocean.com",
      "port": 25060,
      "user": "doadmin",
      "password": "wv78n3zpz42xezdk",
      "ssl": true
    },
    "users": null,
    "db_names": null,
    "num_nodes": 2,
    "region": "nyc3",
    "status": "creating",
    "created_at": "2019-01-11T18:37:36Z",
    "maintenance_window": null,
    "size": "db-s-2vcpu-4gb",
    "tags": [
      "production"
    ],
    "private_network_uuid": "d455e75d-4858-4eec-8c95-da2f0a5f93a7"
  }
}

Retrieve an Existing Database Cluster

To show information about an existing database cluster, send a GET request to /v2/databases/$DATABASE_ID.

The response will be a JSON object with a database key. This will be set to an object containing the standard database cluster attributes:

NameTypeDescription
idstringA unique ID that can be used to identify and reference a database cluster.
namestringA unique, human-readable name referring to a database cluster.
enginestringA slug representing the database engine used for the cluster. The possible values are: "pg" for PostgreSQL, "mysql" for MySQL, and "redis" for Redis.
versionstringA string representing the version of the database engine in use for the cluster.
connectionobjectAn object containing the information required to connect to the database (see below).
private_connectionobjectAn object containing the information required to connect to the database via the private network (see below).
usersarray of objectsAn array containing objects describing the database's users (see below).
db_namesarray of stringsAn array of strings containing the names of databases created in the database cluster.
num_nodesintegerThe number of nodes in the database cluster.
sizestringThe slug identifier representing the size of the nodes in the database cluster.
regionstringThe slug identifier for the region where the database cluster is located.
statusstringA string representing the current status of the database cluster. Possible values include creating, online, resizing, and migrating.
maintenance_windowobjectAn object containing information about any pending maintenance for the database cluster and when it will occur (see below).
created_atstringA time value given in ISO8601 combined date and time format that represents when the database cluster was created.
tagsarrayAn array of tags that have been applied to the database cluster.
private_network_uuidstringA string specifying the UUID of the VPC to which the database cluster is assigned.

The embedded connection and private_connection objects will contain the information needed to access the database cluster:

NameTypeDescription
uristringA connection string in the format accepted by the psql command. This is provided as a convenience and should be able to be constructed by the other attributes.
databasestringThe name of the default database.
hoststringThe FQDN pointing to the database cluster's current primary node.
portintegerThe port on which the database cluster is listening.
userstringThe default user for the database.
passwordstringThe randomly generated password for the default user.
sslbooleanA boolean value indicating if the connection should be made over SSL.

The users attribute will contain an array of objects with the following attributes:

NameTypeDescription
namestringThe name of a database user.
rolestringA string representing the database user's role. The value will be either "primary" or "normal".
passwordstringA randomly generated password for the database user.
mysql_settingsobjectAn object containing addition configuration details for MySQL clusters (see below).

The embedded maintenance_window object will contain information about any scheduled maintenance for the database cluster:

NameTypeDescription
daystringThe day of the week on which to apply maintenance updates (e.g. "tuesday").
hourstringThe hour in UTC at which maintenance updates will be applied in 24 hour format (e.g. "16:00:00").
pendingbooleanA boolean value indicating whether any maintenance is scheduled to be performed in the next window.
descriptionarray of stringsA list of strings, each containing information about a pending maintenance update.

Retrieve an Existing Database Cluster

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

cluster, _, err := client.Databases.Get(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1123
ratelimit-reset: 1415984218

Response Body

{
  "database": {
    "id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
    "name": "backend",
    "engine": "pg",
    "version": "10",
    "connection": {
      "uri": "postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require",
      "database": "",
      "host": "backend-do-user-19081923-0.db.ondigitalocean.com",
      "port": 25060,
      "user": "doadmin",
      "password": "wv78n3zpz42xezdk",
      "ssl": true
    },
    "private_connection": {
      "uri": "postgres://doadmin:wv78n3zpz42xezdk@private-backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require",
      "database": "",
      "host": "private-backend-do-user-19081923-0.db.ondigitalocean.com",
      "port": 25060,
      "user": "doadmin",
      "password": "wv78n3zpz42xezdk",
      "ssl": true
    },
    "users": [
      {
        "name": "doadmin",
        "role": "primary",
        "password": "wv78n3zpz42xezdk"
      }
    ],
    "db_names": [
      "defaultdb"
    ],
    "num_nodes": 1,
    "region": "nyc3",
    "status": "online",
    "created_at": "2019-01-11T18:37:36Z",
    "maintenance_window": {
      "day": "saturday",
      "hour": "08:45:12",
      "pending": true,
      "description": [
        "Update TimescaleDB to version 1.2.1",
        "Upgrade to PostgreSQL 11.2 and 10.7 bugfix releases"
      ]
    },
    "size": "db-s-2vcpu-4gb",
    "tags": [
      "production"
    ],
    "private_network_uuid": "d455e75d-4858-4eec-8c95-da2f0a5f93a7"
  }
}

List All Database Clusters

To list all of the database clusters available on your account, send a GET request to /v2/databases. To limit the results to database clusters with a specific tag, include the tag_name query parameter set to the name of the tag. For example, /v2/databases?tag_name=$TAG_NAME.

The result will be a JSON object with a databases key. This will be set to an array of database objects, each of which will contain the standard database attributes:

NameTypeDescription
idstringA unique ID that can be used to identify and reference a database cluster.
namestringA unique, human-readable name referring to a database cluster.
enginestringA slug representing the database engine used for the cluster. The possible values are: "pg" for PostgreSQL, "mysql" for MySQL, and "redis" for Redis.
versionstringA string representing the version of the database engine in use for the cluster.
connectionobjectAn object containing the information required to connect to the database (see below).
private_connectionobjectAn object containing the information required to connect to the database via the private network (see below).
usersarray of objectsAn array containing objects describing the database's users (see below).
db_namesarray of stringsAn array of strings containing the names of databases created in the database cluster.
num_nodesintegerThe number of nodes in the database cluster.
sizestringThe slug identifier representing the size of the nodes in the database cluster.
regionstringThe slug identifier for the region where the database cluster is located.
statusstringA string representing the current status of the database cluster. Possible values include creating, online, resizing, and migrating.
maintenance_windowobjectAn object containing information about any pending maintenance for the database cluster and when it will occur (see below).
created_atstringA time value given in ISO8601 combined date and time format that represents when the database cluster was created.
tagsarrayAn array of tags that have been applied to the database cluster.
private_network_uuidstringA string specifying the UUID of the VPC to which the database cluster is assigned.

The embedded connection and private_connection objects will contain the information needed to access the database cluster:

NameTypeDescription
uristringA connection string in the format accepted by the psql command. This is provided as a convenience and should be able to be constructed by the other attributes.
databasestringThe name of the default database.
hoststringThe FQDN pointing to the database cluster's current primary node.
portintegerThe port on which the database cluster is listening.
userstringThe default user for the database.
passwordstringThe randomly generated password for the default user.
sslbooleanA boolean value indicating if the connection should be made over SSL.

The users attribute will contain an array of objects with the following attributes:

NameTypeDescription
namestringThe name of a database user.
rolestringA string representing the database user's role. The value will be either "primary" or "normal".
passwordstringA randomly generated password for the database user.
mysql_settingsobjectAn object containing addition configuration details for MySQL clusters (see below).

The embedded maintenance_window object will contain information about any scheduled maintenance for the database cluster:

NameTypeDescription
daystringThe day of the week on which to apply maintenance updates (e.g. "tuesday").
hourstringThe hour in UTC at which maintenance updates will be applied in 24 hour format (e.g. "16:00:00").
pendingbooleanA boolean value indicating whether any maintenance is scheduled to be performed in the next window.
descriptionarray of stringsA list of strings, each containing information about a pending maintenance update.

List All Database Clusters

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/databases"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

opt := &godo.ListOptions{
    Page:    1,
    PerPage: 200,
}

clusters, _, err := client.Databases.List(ctx, opt)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4816
ratelimit-reset: 1444931833

Response Body

{
  "databases": [
    {
      "id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
      "name": "backend",
      "engine": "pg",
      "version": "10",
      "connection": {
        "uri": "postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require",
        "database": "",
        "host": "backend-do-user-19081923-0.db.ondigitalocean.com",
        "port": 25060,
        "user": "doadmin",
        "password": "wv78n3zpz42xezdk",
        "ssl": true
      },
      "private_connection": {
        "uri": "postgres://doadmin:wv78n3zpz42xezdk@private-backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require",
        "database": "",
        "host": "private-backend-do-user-19081923-0.db.ondigitalocean.com",
        "port": 25060,
        "user": "doadmin",
        "password": "wv78n3zpz42xezdk",
        "ssl": true
      },
      "users": [
        {
          "name": "doadmin",
          "role": "primary",
          "password": "wv78n3zpz42xezdk"
        }
      ],
      "db_names": [
        "defaultdb"
      ],
      "num_nodes": 1,
      "region": "nyc3",
      "status": "online",
      "created_at": "2019-01-11T18:37:36Z",
      "maintenance_window": {
        "day": "saturday",
        "hour": "08:45:12",
        "pending": true,
        "description": [
          "Update TimescaleDB to version 1.2.1",
          "Upgrade to PostgreSQL 11.2 and 10.7 bugfix releases"
        ]
      },
      "size": "db-s-2vcpu-4gb",
      "tags": [
        "production"
      ],
      "private_network_uuid": "d455e75d-4858-4eec-8c95-da2f0a5f93a7"
    }
  ]
}

Resize a Database Cluster

To resize a database cluster, send a PUT request to /v2/databases/$DATABASE_ID/resize. The body of the request must specify both the size and num_nodes attributes.

NameTypeDescriptionRequired
sizestringA slug identifier representing desired the size of the nodes in the database cluster.true
num_nodesintegerThe number of nodes in the database cluster. Valid values are are 1-3. In addition to the primary node, up to two standby nodes may be added for highly available configurations.true

A successful request will receive a 202 Accepted status code with no body in response. Querying the database cluster will show that its status attribute will now be set to resizing. This will transition back to online when the resize operation has completed.

Resize a Database Cluster

cURL Example

curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"size":"db-s-4vcpu-8gb", "num_nodes":3}' "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/resize"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example


resizeRequest := &godo.DatabaseResizeRequest{
    SizeSlug: "db-s-4vcpu-8gb",
    NumNodes: 3,
}

_, err := client.Databases.Resize(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", resizeRequest)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "size": "db-s-4vcpu-8gb",
  "num_nodes": 3
}

Response Headers

content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 1200
ratelimit-remaining: 838
ratelimit-reset: 1415984218

Migrate a Database Cluster to a New Region

To migrate a database cluster to a new region, send a PUT request to /v2/databases/$DATABASE_ID/migrate. The body of the request must specify a region attribute.

NameTypeDescriptionRequired
regionstringA slug identifier for the region to which the database cluster will be migrated.true

A successful request will receive a 202 Accepted status code with no body in response. Querying the database cluster will show that its status attribute will now be set to migrating. This will transition back to online when the migration has completed.

Migrate a Database Cluster to a New Region

cURL Example

curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"region":"lon1"}' "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/migrate"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

migrateRequest := &godo.DatabaseMigrateRequest{
    Region: "lon1",
}

_, err := client.Databases.Migrate(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", migrateRequest)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "region": "lon1"
}

Response Headers

content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 1200
ratelimit-remaining: 838
ratelimit-reset: 1415984218

Update Firewall Rules (Trusted Sources) for a Database cluster

To update a database cluster's firewall rules (known as "trusted sources" in the control panel), send a PUT request to /v2/databases/$DATABASE_ID/firewall specifying which resources should be able to open connections to the database. You may limit connections to specific Droplets, Kubernetes clusters, or IP addresses. When a tag is provided, any Droplet or Kubernetes node with that tag applied to it will have access. The firewall is limited to 100 rules (or trusted sources). When possible, we recommend placing your databases into a VPC network to limit access to them instead of using a firewall.

The request body may contain the following attributes:

NameTypeDescriptionRequired
typestringThe type of resource that the firewall rule allows to access the database cluster. The possible values are: 'droplet', 'k8s', 'ip_addr', or 'tag'. true
valuestringThe ID of the specific resource, the name of a tag applied to a group of resources, or the IP address that the firewall rule allows to access the database cluster.true
uuidstringA unique ID for the firewall rule itself when updating an existing rule.
cluster_uuidstringA unique ID for the database cluster to which the rule is applied.

A successful request will receive a 204 No Content status code with no body in response.

Update Firewall Rules (Trusted Sources) for a Database cluster

cURL Example

curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"rules": [{"type": "ip_addr","value": "192.168.1.1"},{"type": "droplet","value": "163973392"},{"type": "k8s","value": "ff2a6c52-5a44-4b63-b99c-0e98e7a63d61"},{"type": "tag","value": "backend"]}' "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/firewall"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

req := godo.DatabaseUpdateFirewallRulesRequest{
  Rules: []*godo.DatabaseFirewallRule{
    {
     Type:  "ip_addr",
     Value: "192.168.1.1",
   },
    {
     Type:  "droplet",
     Value: "163973392",
   },
    {
     Type:  "k8s",
     Value: "ff2a6c52-5a44-4b63-b99c-0e98e7a63d61",
    },
  },
}
_, err := client.Databases.UpdateFirewallRules(ctx, dbID, &req)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "rules": [
    {
      "type": "ip_addr",
      "value": "192.168.1.1"
    },
    {
      "type": "droplet",
      "value": "163973392"
    },
    {
      "type": "k8s",
      "value": "ff2a6c52-5a44-4b63-b99c-0e98e7a63d61"
    },
    {
      "type": "tag",
      "value": "backend"
    }
  ]
}

Response Headers

content-type: application/json; charset=utf-8
status: 204 No Content
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

List Firewall Rules (Trusted Sources) for a Database Cluster

To list all of a database cluster's firewall rules (known as "trusted sources" in the control panel), send a GET request to /v2/databases/$DATABASE_ID/firewall.

The result will be a JSON object with a rules key. This will be set to an array of objects with the following attributes:

NameTypeDescription
uuidstringA unique ID for the firewall rule itself.
cluster_uuidstringA unique ID for the database cluster to which the rule is applied.
typestringThe type of resource that the firewall rule allows to access the database cluster. The possible values are: 'droplet', 'k8s', 'ip_addr', or 'tag'
valuestringThe ID of the specific resource, the name of a tag applied to a group of resources, or the IP address that the firewall rule allows to access the database cluster.
created_atstringA time value given in ISO8601 combined date and time format that represents when the firewall rule was created.

List Firewall Rules (Trusted Sources) for a Database Cluster

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/firewall"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

rules, _, err := client.Databases.GetFirewallRules(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4816
ratelimit-reset: 1444931833

Response Body

{
  "rules": [
    {
      "uuid": "79f26d28-ea8a-41f2-8ad8-8cfcdd020095",
      "cluster_uuid": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
      "type": "k8s",
      "value": "ff2a6c52-5a44-4b63-b99c-0e98e7a63d61",
      "created_at": "2019-11-14T20:30:28Z"
    },
    {
      "uuid": "adfe81a8-0fa1-4e2d-973f-06aa5af19b44",
      "cluster_uuid": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
      "type": "ip_addr",
      "value": "192.168.1.1",
      "created_at": "2019-11-14T20:30:28Z"
    },
    {
      "uuid": "b9b42276-8295-4313-b40f-74173a7f46e6",
      "cluster_uuid": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
      "type": "droplet",
      "value": "163973392",
      "created_at": "2019-11-14T20:30:28Z"
    },
    {
      "uuid": "718d23e0-13d7-4129-8a00-47fb72ee0deb",
      "cluster_uuid": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30",
      "type": "tag",
      "value": "backend",
      "created_at": "2019-11-14T20:30:28Z"
    }
  ]
}

Configure a Database Cluster's Maintenance Window

To configure the window when automatic maintenance should be performed for a database cluster, send a PUT request to /v2/databases/$DATABASE_ID/maintenance with the following attributes:

NameTypeDescriptionRequired
daystringThe day of the week on which to apply maintenance updates (e.g. "tuesday").true
hourstringThe hour in UTC at which maintenance updates will be applied in 24 hour format (e.g. "16:00").true

A successful request will receive a 204 No Content status code with no body in response.

Configure a Database Cluster's Maintenance Window

cURL Example

curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"day": "tuesday", "hour": "14:00"}' "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/maintenance"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

maintenanceRequest := &godo.DatabaseUpdateMaintenanceRequest{
    Day:  "thursday",
    Hour: "16:00",
}

_, err := client.Databases.UpdateMaintenance(ctx, "88055188-9e54-4f21-ab11-8a918ed79ee2", maintenanceRequest)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "day": "tuesday",
  "hour": "14:00"
}

Response Headers

content-type: application/json; charset=utf-8
status: 204 No Content
ratelimit-limit: 1200
ratelimit-remaining: 838
ratelimit-reset: 1415984218

List Backups for a Database Cluster

To list all of the available backups of a PostgreSQL or MySQL database cluster, send a GET request to /v2/databases/$DATABASE_ID/backups.

Note: Backups are not supported for Redis clusters.

The result will be a JSON object with a backups key. This will be set to an array of backup objects, each of which will contain the size of the backup and the timestamp at which it was created.

NameTypeDescription
created_atstringA time value given in ISO8601 combined date and time format at which the backup was created.
size_gigabytesfloatThe size of the database backup in GBs.

List Backups for a Database Cluster

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/backups"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

backups, _, err := client.Databases.ListBackups(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", nil)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4816
ratelimit-reset: 1444931833

Response Body

{
  "backups": [
    {
      "created_at": "2019-01-11T18:42:27Z",
      "size_gigabytes": 0.03357696
    },
    {
      "created_at": "2019-01-12T18:42:29Z",
      "size_gigabytes": 0.03364864
    }
  ]
}

Restore from a Database Cluster Backup

DigitalOcean managed PostgreSQL and MySQL database clusters take automated daily backups. To create a new database cluster based on a backup of an exising cluster, send a POST request to /v2/databases. In addition to the standard database cluster attributes, the JSON body must include a key named backup_restore with the name of the original database cluster and the timestamp of the backup to be restored.

Note: Backups are not supported for Redis clusters.

NameTypeDescriptionRequired
namestringA unique, human-readable name for the database cluster.true
enginestringA slug representing the database engine to be used for the cluster. The possible values are: "pg" for PostgreSQL, "mysql" for MySQL, and "redis" for Redis. true
versionstringA string representing the version of the database engine to use for the cluster. If excluded, the specified engine's default version is used. The available versions for PostgreSQL are "10" and "11" defaulting to the later. For MySQL, the only available version is "8". For Redis, the only available version is "5".
sizestringA slug identifier representing the size of the nodes in the database cluster.true
regionstringA slug identifier for the region where the database cluster will be created.true
num_nodesintegerThe number of nodes in the database cluster. Valid values are are 1-3. In addition to the primary node, up to two standby nodes may be added for highly available configurations. The value is inclusive of the primary node. For example, setting the value to 2 will provision a database cluster with a primary node and one standby node.true
tagsarrayA flat array of tag names as strings to apply to the database cluster after it is created. Tag names can either be existing or new tags.
private_network_uuidstringA string specifying the UUID of the VPC to which the database cluster will be assigned. If excluded, the cluster will be assigned to your account's default VPC for the region.
backup_restoreobjectAn embedded object containing two attributes specifying the name of the original database cluster and the timestamp of the backup to restore (see below).true

The embedded backup_restore object requires these attributes to be set:

NameTypeDescriptionRequired
database_namestringThe name of an existing database cluster from which the backup will be restored.true
backup_created_atstringThe timestamp of an existing database cluster backup in ISO8601 combined date and time format. The most recent backup will be used if excluded.

The response will be a JSON object with a key called database. The value of this will be an object that contains the standard attributes associated with a database cluster. The initial value of the database cluster's status attribute will be forking. When the cluster is ready to receive traffic, this will transition to online.

NameTypeDescription
idstringA unique ID that can be used to identify and reference a database cluster.
namestringA unique, human-readable name referring to a database cluster.
enginestringA slug representing the database engine used for the cluster. The possible values are: "pg" for PostgreSQL, "mysql" for MySQL, and "redis" for Redis.
versionstringA string representing the version of the database engine in use for the cluster.
connectionobjectAn object containing the information required to connect to the database (see below).
private_connectionobjectAn object containing the information required to connect to the database via the private network (see below).
usersarray of objectsAn array containing objects describing the database's users (see below).
db_namesarray of stringsAn array of strings containing the names of databases created in the database cluster.
num_nodesintegerThe number of nodes in the database cluster.
sizestringThe slug identifier representing the size of the nodes in the database cluster.
regionstringThe slug identifier for the region where the database cluster is located.
statusstringA string representing the current status of the database cluster. Possible values include creating, online, resizing, and migrating.
maintenance_windowobjectAn object containing information about any pending maintenance for the database cluster and when it will occur (see below).
created_atstringA time value given in ISO8601 combined date and time format that represents when the database cluster was created.
tagsarrayAn array of tags that have been applied to the database cluster.
private_network_uuidstringA string specifying the UUID of the VPC to which the database cluster is assigned.

The embedded connection and private_connection objects will contain the information needed to access the database cluster:

NameTypeDescription
uristringA connection string in the format accepted by the psql command. This is provided as a convenience and should be able to be constructed by the other attributes.
databasestringThe name of the default database.
hoststringThe FQDN pointing to the database cluster's current primary node.
portintegerThe port on which the database cluster is listening.
userstringThe default user for the database.
passwordstringThe randomly generated password for the default user.
sslbooleanA boolean value indicating if the connection should be made over SSL.

Restore from a Database Cluster Backup

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name": "backend-restored", "backup_restore": {"database_name":"backend", "backup_created_at":"2019-01-31T19:25:22Z"}, "engine": "pg", "version": "10", "region": "nyc3", "size": "db-s-2vcpu-4gb", "num_nodes": 2}' "https://api.digitalocean.com/v2/databases"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "name": "backend-restored",
  "backup_restore": {
    "database_name": "backend",
    "backup_created_at": "2019-01-31T19:25:22Z"
  },
  "engine": "pg",
  "version": "10",
  "region": "nyc3",
  "size": "db-s-2vcpu-4gb",
  "num_nodes": 2
}

Response Headers

content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Response Body

{
  "database": {
    "id": "9423cbad-9211-442f-820b-ef6915e99b5f",
    "name": "backend-restored",
    "engine": "pg",
    "version": "10",
    "connection": {
      "uri": "postgres://doadmin:wv78n3zpz42xezdk@backend-restored-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require",
      "database": "",
      "host": "backend-restored-do-user-19081923-0.db.ondigitalocean.com",
      "port": 25060,
      "user": "doadmin",
      "password": "wv78n3zpz42xezdk",
      "ssl": true
    },
    "private_connection": {
      "uri": "postgres://doadmin:wv78n3zpz42xezdk@private-backend-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require",
      "database": "",
      "host": "private-backend-do-user-19081923-0.db.ondigitalocean.com",
      "port": 25060,
      "user": "doadmin",
      "password": "wv78n3zpz42xezdk",
      "ssl": true
    },
    "users": null,
    "db_names": null,
    "num_nodes": 1,
    "region": "nyc3",
    "status": "forking",
    "created_at": "2019-01-11T18:37:36Z",
    "maintenance_window": null,
    "size": "db-s-2vcpu-4gb",
    "tags": null
  }
}

Destroy a Database Cluster

To destroy a specific database, send a DELETE request to /v2/databases/$DATABASE_ID.

A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.

Destroy a Database Cluster

cURL Example

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

_, err := client.Databases.Delete(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 204 No Content
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Create a Read-only Replica

To create a read-only replica for a PostgreSQL or MySQL database cluster, send a POST request to /v2/databases/$DATABASE_ID/replicas specifying the name it should be given, the size of the node to be used, and the region where it will be located.

Note: Read-only replicas are not supported for Redis clusters.

NameTypeDescriptionRequired
namestringThe name to give the read-only replica.true
regionstringA slug identifier for the region where the read-only replica will be located. If excluded, the replica will be placed in the same region as the cluster.
sizestringA slug identifier representing the size of the node for the read-only replica. The size of the replica must be at least as large as the node size for the database cluster from which it is replicating.true
tagsarrayA flat array of tag names as strings to apply to the read-only replica after it is created. Tag names can either be existing or new tags.
private_network_uuidstringA string specifying the UUID of the VPC to which the read-only replica will be assigned. If excluded, the replica will be assigned to your account's default VPC for the region.

The response will be a JSON object with a key called replica. The value of this will be an object that contains the standard attributes associated with a database replica. The initial value of the read-only replica's status attribute will be forking. When the replica is ready to receive traffic, this will transition to active.

NameTypeDescription
namestringA unique, human-readable name referring to a read-only replica.
connectionobjectAn object containing the information required to connect to the read-only replica (see below).
private_connectionobjectAn object containing the information required to connect to the read-only replica via the private network (see below).
regionstringThe slug identifier for the region where the read-only replica is located.
statusstringA string representing the current status of the read-only replica. Possible values include forking and active.
created_atstringA time value given in ISO8601 combined date and time format that represents when the read-only replica was created.
tagsarrayAn array of tags that have been applied to the read-only replica.
private_network_uuidstringA string specifying the UUID of the VPC to which the read-only replica is assigned.

The embedded connection and private_connection objects will contain the information needed to access the read-only replica:

NameTypeDescription
uristringA connection string in the format accepted by the psql command. This is provided as a convenience and should be able to be constructed by the other attributes.
databasestringThe name of the default database.
hoststringThe FQDN pointing to the read-only replica node.
portintegerThe port on which the read-only replica is listening.
userstringThe default user for the database.
passwordstringThe randomly generated password for the default user.
sslbooleanA boolean value indicating if the connection should be made over SSL.

Create a Read-only Replica

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name":"read-nyc3-01", "region":"nyc3", "size": "db-s-2vcpu-4gb"}' "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/replicas"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

replicaRequest := &godo.DatabaseCreateReplicaRequest{

    Name:   "read-nyc3-01",
    Region: "nyc3",
    Size:   "db-s-2vcpu-4gb",
}

replica, _, err := client.Databases.CreateReplica(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", replicaRequest)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "name": "read-nyc3-01",
  "region": "nyc3",
  "size": "db-s-2vcpu-4gb"
}

Response Headers

content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Response Body

{
  "replica": {
    "name": "read-nyc3-01",
    "connection": {
      "uri": "postgres://doadmin:wv78n3zpz42xezdk@read-nyc3-01-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require",
      "database": "",
      "host": "read-nyc3-01-do-user-19081923-0.db.ondigitalocean.com",
      "port": 25060,
      "user": "doadmin",
      "password": "wv78n3zpz42xezdk",
      "ssl": true
    },
    "private_connection": {
      "uri": "postgres://doadmin:wv78n3zpz42xezdk@private-read-nyc3-01-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require",
      "database": "",
      "host": "private-read-nyc3-01-do-user-19081923-0.db.ondigitalocean.com",
      "port": 25060,
      "user": "doadmin",
      "password": "wv78n3zpz42xezdk",
      "ssl": true
    },
    "region": "nyc3",
    "status": "forking",
    "created_at": "2019-01-31T19:57:32Z"
  }
}

Retrieve an Existing Read-only Replica

To show information about an existing database replica, send a GET request to /v2/databases/$DATABASE_ID/replicas/$REPLICA_NAME.

Note: Read-only replicas are not supported for Redis clusters.

The response will be a JSON object with a replica key. This will be set to an object containing the standard database replica attributes:

NameTypeDescription
namestringA unique, human-readable name referring to a read-only replica.
connectionobjectAn object containing the information required to connect to the read-only replica (see below).
private_connectionobjectAn object containing the information required to connect to the read-only replica via the private network (see below).
regionstringThe slug identifier for the region where the read-only replica is located.
statusstringA string representing the current status of the read-only replica. Possible values include forking and active.
created_atstringA time value given in ISO8601 combined date and time format that represents when the read-only replica was created.
tagsarrayAn array of tags that have been applied to the read-only replica.
private_network_uuidstringA string specifying the UUID of the VPC to which the read-only replica is assigned.

The embedded connection and private_connection objects will contain the information needed to access the read-only replica:

NameTypeDescription
uristringA connection string in the format accepted by the psql command. This is provided as a convenience and should be able to be constructed by the other attributes.
databasestringThe name of the default database.
hoststringThe FQDN pointing to the read-only replica node.
portintegerThe port on which the read-only replica is listening.
userstringThe default user for the database.
passwordstringThe randomly generated password for the default user.
sslbooleanA boolean value indicating if the connection should be made over SSL.

Retrieve an Existing Read-only Replica

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/replicas/read-nyc3-01"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

replica, _, err := client.Databases.GetReplica(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "read-nyc3-01")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1123
ratelimit-reset: 1415984218

Response Body

{
  "replica": {
    "name": "read-nyc3-01",
    "connection": {
      "uri": "",
      "database": "defaultdb",
      "host": "read-nyc3-01-do-user-19081923-0.db.ondigitalocean.com",
      "port": 25060,
      "user": "doadmin",
      "password": "wv78n3zpz42xezdk",
      "ssl": true
    },
    "private_connection": {
      "uri": "postgres://doadmin:wv78n3zpz42xezdk@private-read-nyc3-01-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require",
      "database": "",
      "host": "private-read-nyc3-01-do-user-19081923-0.db.ondigitalocean.com",
      "port": 25060,
      "user": "doadmin",
      "password": "wv78n3zpz42xezdk",
      "ssl": true
    },
    "region": "nyc3",
    "status": "active",
    "created_at": "0001-01-01T00:00:00Z"
  }
}

List All Read-only Replicas

To list all of the read-only replicas associated with a database cluster, send a GET request to /v2/databases/$DATABASE_ID/replicas.

Note: Read-only replicas are not supported for Redis clusters.

The result will be a JSON object with a replicas key. This will be set to an array of database replica objects, each of which will contain the standard database replica attributes:

NameTypeDescription
namestringA unique, human-readable name referring to a read-only replica.
connectionobjectAn object containing the information required to connect to the read-only replica (see below).
private_connectionobjectAn object containing the information required to connect to the read-only replica via the private network (see below).
regionstringThe slug identifier for the region where the read-only replica is located.
statusstringA string representing the current status of the read-only replica. Possible values include forking and active.
created_atstringA time value given in ISO8601 combined date and time format that represents when the read-only replica was created.
tagsarrayAn array of tags that have been applied to the read-only replica.
private_network_uuidstringA string specifying the UUID of the VPC to which the read-only replica is assigned.

The embedded connection and private_connection objects will contain the information needed to access the read-only replica:

NameTypeDescription
uristringA connection string in the format accepted by the psql command. This is provided as a convenience and should be able to be constructed by the other attributes.
databasestringThe name of the default database.
hoststringThe FQDN pointing to the read-only replica node.
portintegerThe port on which the read-only replica is listening.
userstringThe default user for the database.
passwordstringThe randomly generated password for the default user.
sslbooleanA boolean value indicating if the connection should be made over SSL.

List All Read-only Replicas

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/replicas"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

replicas, _, err := client.Databases.ListReplicas(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", nil)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4816
ratelimit-reset: 1444931833

Response Body

{
  "replicas": [
    {
      "name": "read-nyc3-01",
      "connection": {
        "uri": "",
        "database": "defaultdb",
        "host": "read-nyc3-01-do-user-19081923-0.db.ondigitalocean.com",
        "port": 25060,
        "user": "doadmin",
        "password": "wv78n3zpz42xezdk",
        "ssl": true
      },
      "private_connection": {
        "uri": "postgres://doadmin:wv78n3zpz42xezdk@private-read-nyc3-01-do-user-19081923-0.db.ondigitalocean.com:25060/defaultdb?sslmode=require",
        "database": "",
        "host": "private-read-nyc3-01-do-user-19081923-0.db.ondigitalocean.com",
        "port": 25060,
        "user": "doadmin",
        "password": "wv78n3zpz42xezdk",
        "ssl": true
      },
      "region": "nyc3",
      "status": "active",
      "created_at": "0001-01-01T00:00:00Z"
    }
  ]
}

Destroy a Read-only Replica

To destroy a specific read-only replica, send a DELETE request to /v2/databases/$DATABASE_ID/replicas/$REPLICA_NAME.

Note: Read-only replicas are not supported for Redis clusters.

A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.

Destroy a Read-only Replica

cURL Example

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/replicas/read-nyc3-01"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

_, err := client.Databases.DeleteReplica(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "read-nyc3-01")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 204 No Content
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Add a Database User

To add a new database user, send a POST request to /v2/databases/$DATABASE_ID/users with the desired username.

Note: User management is not supported for Redis clusters.

NameTypeDescriptionRequired
namestringThe name to give the database user.true
mysql_settingsobjectAn object containing addition configuration details for MySQL clusters (see below).

When adding a user to a MySQL cluster, additional options can be configured in the mysql_settings object:

NameTypeDescriptionRequired
auth_pluginstringA string specifying the authentication method to be used for connections to the MySQL user account. The valid values are "mysql_native_password" or "caching_sha2_password". If excluded when creating a new user, the default for the version of MySQL in use will be used. As of MySQL 8.0, the default is "caching_sha2_password." true

The response will be a JSON object with a key called user. The value of this will be an object that contains the standard attributes associated with a database user including its randomly generated password:

NameTypeDescription
namestringThe name of a database user.
rolestringA string representing the database user's role. The value will be either "primary" or "normal".
passwordstringA randomly generated password for the database user.
mysql_settingsobjectAn object containing addition configuration details for MySQL clusters (see below).

For MySQL clusters, additional options will be contained in the mysql_settings object:

NameTypeDescription
auth_pluginstringA string specifying the authentication method in use for connections to the MySQL user account. The valid values are "mysql_native_password" or "caching_sha2_password".

Add a Database User

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name": "app-01"}' "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/users"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

addUserRequest := &godo.DatabaseCreateUserRequest{
    Name: "app-01",
}

user, _, err := client.Databases.CreateUser(ctx, "88055188-9e54-4f21-ab11-8a918ed79ee2", addUserRequest)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "name": "app-01"
}

Response Headers

content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Response Body

{
  "user": {
    "name": "app-01",
    "role": "normal",
    "password": "jge5lfxtzhx42iff"
  }
}

Retrieve an Existing Database User

To show information about an existing database user, send a GET request to /v2/databases/$DATABASE_ID/users/$USERNAME.

Note: User management is not supported for Redis clusters.

The response will be a JSON object with a user key. This will be set to an object containing the standard database user attributes:

NameTypeDescription
namestringThe name of a database user.
rolestringA string representing the database user's role. The value will be either "primary" or "normal".
passwordstringA randomly generated password for the database user.
mysql_settingsobjectAn object containing addition configuration details for MySQL clusters (see below).

For MySQL clusters, additional options will be contained in the mysql_settings object:

NameTypeDescription
auth_pluginstringA string specifying the authentication method in use for connections to the MySQL user account. The valid values are "mysql_native_password" or "caching_sha2_password".

Retrieve an Existing Database User

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/users/app-01"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

user, _, err := client.Databases.GetUser(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "app-01")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1123
ratelimit-reset: 1415984218

Response Body

{
  "user": {
    "name": "app-01",
    "role": "normal",
    "password": "jge5lfxtzhx42iff"
  }
}

Reset a Database User's MySQL Authentication Method

Note: Resetting user authentication is not supported for PostgreSQL and Redis clusters.

To reset the MySQL authentication method for a user, send a POST request to /v2/databases/$DATABASE_ID/users/$USERNAME/reset_auth. The JSON body must include a key called mysql_settings containing:

NameTypeDescriptionRequired
auth_pluginstringA string specifying the authentication method to be used for connections to the MySQL user account. The valid values are "mysql_native_password" or "caching_sha2_password". If excluded when creating a new user, the default for the version of MySQL in use will be used. As of MySQL 8.0, the default is "caching_sha2_password." true

The response will be a JSON object with a user key. This will be set to an object containing the standard database user attributes:

NameTypeDescription
namestringThe name of a database user.
rolestringA string representing the database user's role. The value will be either "primary" or "normal".
passwordstringA randomly generated password for the database user.
mysql_settingsobjectAn object containing addition configuration details for MySQL clusters (see below).

Reset a Database User's MySQL Authentication Method

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"mysql_settings":{"auth_plugin": "caching_sha2_password"}}' "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/users/app-01/reset_auth"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

resetUserAuthRequest := &godo.DatabaseResetUserAuthRequest{
    MySQLSettings: &DatabaseMySQLUserSettings{
        AuthPlugin: "caching_sha2_password",
     },
}
user, _, err := client.Databases.ResetUserAuth(ctx, "88055188-9e54-4f21-ab11-8a918ed79ee2", "app-01", resetuserAuthRequest)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "mysql_settings": {
    "auth_plugin": "caching_sha2_password"
  }
}

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1123
ratelimit-reset: 1415984218

Response Body

{
  "user": {
    "name": "app-01",
    "role": "normal",
    "password": "jge5lfxtzhx42iff"
  }
}

List all Database Users

To list all of the users for your database cluster, send a GET request to /v2/databases/$DATABASE_ID/users.

Note: User management is not supported for Redis clusters.

The result will be a JSON object with a users key. This will be set to an array of database user objects, each of which will contain the standard database user attributes:

NameTypeDescription
namestringThe name of a database user.
rolestringA string representing the database user's role. The value will be either "primary" or "normal".
passwordstringA randomly generated password for the database user.
mysql_settingsobjectAn object containing addition configuration details for MySQL clusters (see below).

For MySQL clusters, additional options will be contained in the mysql_settings object:

NameTypeDescription
auth_pluginstringA string specifying the authentication method in use for connections to the MySQL user account. The valid values are "mysql_native_password" or "caching_sha2_password".

List all Database Users

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/users"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

users, _, err := client.Databases.ListUsers(ctx, "88055188-9e54-4f21-ab11-8a918ed79ee2", nil)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4816
ratelimit-reset: 1444931833

Response Body

{
  "users": [
    {
      "name": "app-01",
      "role": "normal",
      "password": "jge5lfxtzhx42iff"
    },
    {
      "name": "doadmin",
      "role": "primary",
      "password": "wv78n3zpz42xezdk"
    }
  ]
}

Remove a Database User

To remove a specific database user, send a DELETE request to /v2/databases/$DATABASE_ID/users/$USERNAME.

A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.

Note: User management is not supported for Redis clusters.

Remove a Database User

cURL Example

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/users/app-01"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

_, err := client.Databases.DeleteUser(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "app-01")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 204 No Content
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Add a New Database

To add a new database to an existing cluster, send a POST request to /v2/databases/$DATABASE_ID/dbs.

Note: Database management is not supported for Redis clusters.

NameTypeDescriptionRequired
namestringThe name to give the database.true

The response will be a JSON object with a key called db. The value of this will be an object that contains the standard attributes associated with a database:

NameTypeDescription
namestringThe name of the database.

Add a New Database

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name": "alpha"}' "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/dbs"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

createDBReq := &godo.DatabaseCreateDBRequest{
    Name: "alpha",
}

db, _, err := client.Databases.CreateDB(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", createDBReq)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Response Body

{
  "db": {
    "name": "alpha"
  }
}

Retrieve an Existing Database

To show information about an existing database cluster, send a GET request to /v2/databases/$DATABASE_ID/dbs/$DB_NAME.

Note: Database management is not supported for Redis clusters.

The response will be a JSON object with a db key. This will be set to an object containing the standard database attributes:

NameTypeDescription
namestringThe name of the database.

Retrieve an Existing Database

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/dbs/alpha"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

db, _, err := client.Databases.GetDB(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "alpha")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1123
ratelimit-reset: 1415984218

Response Body

{
  "db": {
    "name": "alpha"
  }
}

List All Databases

To list all of the databases in a clusters, send a GET request to /v2/databases/$DATABASE_ID/dbs.

The result will be a JSON object with a dbs key. This will be set to an array of database objects, each of which will contain the standard database attributes.

Note: Database management is not supported for Redis clusters.

NameTypeDescription
namestringThe name of the database.

List All Databases

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/dbs"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

dbs, _, err := client.Databases.ListDBs(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", nil)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4816
ratelimit-reset: 1444931833

Response Body

{
  "dbs": [
    {
      "name": "alpha"
    },
    {
      "name": "defaultdb"
    }
  ]
}

Delete a Database

To delete a specific database, send a DELETE request to /v2/databases/$DATABASE_ID/dbs/$DB_NAME.

A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.

Note: Database management is not supported for Redis clusters.

Delete a Database

cURL Example

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/dbs/alpha"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

_, err := client.Databases.DeleteDB(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "alpha")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 204 No Content
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Add a New Connection Pool

For PostgreSQL database clusters, connection pools can be used to allow a database to share its idle connections. The popular PostgreSQL connection pooling utility PgBouncer is used to provide this service. See here for more information about how and why to use PgBouncer connection pooling including details about the available transaction modes.

To add a new connection pool to a PostgreSQL database cluster, send a POST request to /v2/databases/$DATABASE_ID/pools specifying a name for the pool, the user to connect with, the database to connect to, as well as its desired size and transaction mode.

NameTypeDescriptionRequired
namestringA unique name for the connection pool. Must be between 3 and 60 characters.true
modestringThe PGBouncer transaction mode for the connection pool. The allowed values are session, transaction, and statement.true
sizeintegerThe desired size of the PGBouncer connection pool. The maximum allowed size is determined by the size of the cluster's primary node. 25 backend server connections are allowed for every 1GB of RAM. Three are reserved for maintenance. For example, a primary node with 1 GB of RAM allows for a maximum of 22 backend server connections while one with 4 GB would allow for 97. Note that these are shared across all connection pools in a cluster.true
dbstringThe database for use with the connection pool.true
userstringThe name of the user for use with the connection pool.true

The response will be a JSON object with a key called pool. The value of this will be an object that contains the standard attributes associated with a connection pool:

NameTypeDescription
namestringThe name for the connection pool.
modestringThe PGBouncer pool mode for the connection pool. The allowed values are session, transaction, and statement.
sizeintegerThe size of the PGBouncer connection pool.
dbstringThe database for use with the connection pool.
userstringThe name of the user for use with the connection pool.
connectionobjectAn object containing the information required to access the database using the connection pool (see below).
private_connectionobjectAn object containing the information required to connect to the database using the connection pool via the private network (see below).

The embedded connection and private_connection objects will contain the information needed to access the connection pool:

NameTypeDescription
uristringA connection string in the format accepted by the psql command. This is provided as a convenience and should be able to be constructed by the other attributes.
databasestringThe name of the database used by the connection pool.
hoststringThe FQDN pointing to the PGBouncer connection pool.
portintegerThe port on which PGBouncer is listening.
userstringThe user used by the connection pool.
passwordstringThe randomly generated password for the user used by the connection pool.
sslbooleanA boolean value indicating if the connection should be made over SSL.

Add a New Connection Pool

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name": "backend-pool","mode": "transaction","size": 10,"db": "defaultdb","user": "doadmin"}' "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/pools"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

createPoolReq := &godo.DatabaseCreatePoolRequest{
    Name:     "backend-pool",
    Database: "defaultdb",
    Size:     10,
    User:     "doadmin",
    Mode:     "transaction",
}

pool, _, err := client.Databases.CreatePool(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", createPoolReq)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "name": "backend-pool",
  "mode": "transaction",
  "size": 10,
  "db": "defaultdb",
  "user": "doadmin"
}

Response Headers

content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Response Body

{
  "pool": {
    "user": "doadmin",
    "name": "backend-pool",
    "size": 10,
    "db": "defaultdb",
    "mode": "transaction",
    "connection": {
      "uri": "postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25061/backend-pool?sslmode=require",
      "database": "backend-pool",
      "host": "backend-do-user-19081923-0.db.ondigitalocean.com",
      "port": 25061,
      "user": "doadmin",
      "password": "wv78n3zpz42xezdk",
      "ssl": true
    }
  }
}

List All Connection Pools

To list all of the connection pools available to a PostgreSQL database cluster, send a GET request to /v2/databases/$DATABASE_ID/pools.

The result will be a JSON object with a pools key. This will be set to an array of connection pool objects, each of which will contain the standard connection pool attributes:

NameTypeDescription
namestringThe name for the connection pool.
modestringThe PGBouncer pool mode for the connection pool. The allowed values are session, transaction, and statement.
sizeintegerThe size of the PGBouncer connection pool.
dbstringThe database for use with the connection pool.
userstringThe name of the user for use with the connection pool.
connectionobjectAn object containing the information required to access the database using the connection pool (see below).
private_connectionobjectAn object containing the information required to connect to the database using the connection pool via the private network (see below).

The embedded connection and private_connection objects will contain the information needed to access the connection pool:

NameTypeDescription
uristringA connection string in the format accepted by the psql command. This is provided as a convenience and should be able to be constructed by the other attributes.
databasestringThe name of the database used by the connection pool.
hoststringThe FQDN pointing to the PGBouncer connection pool.
portintegerThe port on which PGBouncer is listening.
userstringThe user used by the connection pool.
passwordstringThe randomly generated password for the user used by the connection pool.
sslbooleanA boolean value indicating if the connection should be made over SSL.

List All Connection Pools

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/pools"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

pools, _, err := client.Databases.ListPools(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", nil)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4816
ratelimit-reset: 1444931833

Response Body

{
  "pools": [
    {
      "user": "doadmin",
      "name": "reporting-pool",
      "size": 10,
      "db": "defaultdb",
      "mode": "session",
      "connection": {
        "uri": "postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25061/foo?sslmode=require",
        "database": "foo",
        "host": "backend-do-user-19081923-0.db.ondigitalocean.com",
        "port": 25061,
        "user": "doadmin",
        "password": "wv78n3zpz42xezdk",
        "ssl": true
      }
    },
    {
      "user": "doadmin",
      "name": "backend-pool",
      "size": 10,
      "db": "defaultdb",
      "mode": "transaction",
      "connection": {
        "uri": "postgres://doadmin:wv78n3zpz42xezdk@backend-do-user-19081923-0.db.ondigitalocean.com:25061/backend-pool?sslmode=require",
        "database": "backend-pool",
        "host": "backend-do-user-19081923-0.db.ondigitalocean.com",
        "port": 25061,
        "user": "doadmin",
        "password": "wv78n3zpz42xezdk",
        "ssl": true
      }
    }
  ]
}

Retrieve an Existing Connection Pool

To show information about an existing connection pool for a PostgreSQL database cluster, send a GET request to /v2/databases/$DATABASE_ID/pools/$POOL_NAME.

The response will be a JSON object with a pool key. This will be set to an object containing the standard connection pool attributes:

NameTypeDescription
namestringThe name for the connection pool.
modestringThe PGBouncer pool mode for the connection pool. The allowed values are session, transaction, and statement.
sizeintegerThe size of the PGBouncer connection pool.
dbstringThe database for use with the connection pool.
userstringThe name of the user for use with the connection pool.
connectionobjectAn object containing the information required to access the database using the connection pool (see below).
private_connectionobjectAn object containing the information required to connect to the database using the connection pool via the private network (see below).

The embedded connection and private_connection objects will contain the information needed to access the connection pool:

NameTypeDescription
uristringA connection string in the format accepted by the psql command. This is provided as a convenience and should be able to be constructed by the other attributes.
databasestringThe name of the database used by the connection pool.
hoststringThe FQDN pointing to the PGBouncer connection pool.
portintegerThe port on which PGBouncer is listening.
userstringThe user used by the connection pool.
passwordstringThe randomly generated password for the user used by the connection pool.
sslbooleanA boolean value indicating if the connection should be made over SSL.

Retrieve an Existing Connection Pool

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/pools/backend-pool"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

pool, _, err := client.Databases.GetPool(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "backend-pool")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1123
ratelimit-reset: 1415984218

Response Body

{
  "pool": {
    "user": "doadmin",
    "name": "backend-pool",
    "size": 10,
    "db": "defaultdb",
    "mode": "transaction",
    "connection": {
      "uri": "postgres://doadmin:eja9o6sycf8e54yl@backend2-do-user-19081923-0.db.ondigitalocean.com:25061/backend-pool?sslmode=require",
      "database": "backend-pool",
      "host": "backend2-do-user-19081923-0.db.ondigitalocean.com",
      "port": 25061,
      "user": "doadmin",
      "password": "eja9o6sycf8e54yl",
      "ssl": true
    }
  }
}

Delete a Connection Pool

To delete a specific connection pool for a PostgreSQL database cluster, send a DELETE request to /v2/databases/$DATABASE_ID/pools/$POOL_NAME.

A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.

Delete a Connection Pool

cURL Example

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/pools/backend-pool"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

_, err := client.Databases.DeletePool(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "backend-pool")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 204 No Content
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833

Retrieve the Eviction Policy for a Redis Cluster

To retrieve the configured eviction policy for an existing Redis cluster, send a GET request to /v2/databases/$DATABASE_ID/eviction_policy.

The response will be a JSON object with a eviction_policy key. This will be set to a string representing the eviction policy:

NameTypeDescription
eviction_policystringA string specifying the desired eviction policy for the Redis cluster.

Retrieve the Eviction Policy for a Redis Cluster

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/databases/9cdb64e5-61e4-4b30-b711-11ef66d84558/eviction_policy"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

db, _, err := client.Databases.GetEvictionPolicy(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1123
ratelimit-reset: 1415984218

Response Body

{
  "eviction_policy": "noeviction"
}

Configure the Eviction Policy for a Redis Cluster

To configure an eviction policy for an existing Redis cluster, send a PUT request to /v2/databases/$DATABASE_ID/eviction_policy specifying the desired policy.

NameTypeDescriptionRequired
eviction_policystringA string specifying the desired eviction policy for the Redis cluster. Valid vaules are: noeviction, allkeys_lru, allkeys_random, volatile_lru, volatile_random, or volatile_ttl. true

A successful request will receive a 204 No Content status code with no body in response.

Configure the Eviction Policy for a Redis Cluster

cURL Example

curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"eviction_policy":"allkeys_lru"}' "https://api.digitalocean.com/v2/databases/9cdb64e5-61e4-4b30-b711-11ef66d84558/eviction_policy"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

db, _, err := client.Databases.SetEvictionPolicy(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "allkeys_lru")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "eviction_policy": "allkeys_lru"
}

Response Headers

content-type: application/json; charset=utf-8
status: 204 No Content
ratelimit-limit: 1200
ratelimit-remaining: 1123
ratelimit-reset: 1415984218

Retrieve the SQL Modes for a MySQL Cluster

To retrieve the configured SQL modes for an existing MySQL cluster, send a GET request to /v2/databases/$DATABASE_ID/sql_mode.

The response will be a JSON object with a sql_mode key. This will be set to a string representing the configured SQL modes:

NameTypeDescription
sql_modestringA string specifying the configured SQL modes for the MySQL cluster.

Retrieve the SQL Modes for a MySQL Cluster

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/databases/9cdb64e5-61e4-4b30-b711-11ef66d84558/sql_mode"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

sqlMode, _, err := client.Databases.GetSQLMode(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1123
ratelimit-reset: 1415984218

Response Body

{
  "sql_mode": "ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE,STRICT_ALL_TABLES"
}

Configure the SQL Modes for a MySQL Cluster

To configure the SQL modes for an existing MySQL cluster, send a PUT request to /v2/databases/$DATABASE_ID/sql_mode specifying the desired modes. See the official MySQL 8 documentation for a full list of supported SQL modes.

NameTypeDescriptionRequired
sql_modestringA single string specifying the desired SQL modes for the MySQL cluster separated by commas.true

A successful request will receive a 204 No Content status code with no body in response.

Configure the SQL Modes for a MySQL Cluster

cURL Example

curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"sql_mode":"ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE"}' "https://api.digitalocean.com/v2/databases/9cdb64e5-61e4-4b30-b711-11ef66d84558/sql_mode"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

sqlMode := "ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE"
_, err := client.Databases.SetSQLMode(ctx, "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", sqlMode)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "sql_mode": "ANSI,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION,NO_ZERO_DATE,NO_ZERO_IN_DATE"
}

Response Headers

content-type: application/json; charset=utf-8
status: 204 No Content
ratelimit-limit: 1200
ratelimit-remaining: 1123
ratelimit-reset: 1415984218

Domains

Domain resources are domain names that you have purchased from a domain name registrar that you are managing through the DigitalOcean DNS interface.

This resource establishes top-level control over each domain. Actions that affect individual domain records should be taken on the Domain Records resource.

NameTypeDescription
namestringThe name of the domain itself. This should follow the standard domain format of domain.TLD. For instance, example.com is a valid domain name.
ttlintegerThis value is the time to live for the records on this domain, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.
zone_filestringThis attribute contains the complete contents of the zone file for the selected domain. Individual domain record resources should be used to get more granular control over records. However, this attribute can also be used to get information about the SOA record, which is created automatically and is not accessible as an individual record resource.

List All Domains

To retrieve a list of all of the domains in your account, send a GET request to /v2/domains.

The response will be a JSON object with a key called domains. The value of this will be an array of Domain objects, each of which contain the standard domain attributes:

NameTypeDescription
namestringThe name of the domain itself. This should follow the standard domain format of domain.TLD. For instance, example.com is a valid domain name.
ttlintegerThis value is the time to live for the records on this domain, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.
zone_filestringThis attribute contains the complete contents of the zone file for the selected domain. Individual domain record resources should be used to get more granular control over records. However, this attribute can also be used to get information about the SOA record, which is created automatically and is not accessible as an individual record resource.

List All Domains

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/domains"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

domains = client.domains.all
domains.each

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

opt := &godo.ListOptions{
    Page:    1,
    PerPage: 200,
}

domains, _, err := client.Domains.List(ctx, opt)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1115
ratelimit-reset: 1415984218

Response Body

{
  "domains": [
    {
      "name": "example.com",
      "ttl": 1800,
      "zone_file": "$ORIGIN example.com.\n$TTL 1800\nexample.com. IN SOA ns1.digitalocean.com. hostmaster.example.com. 1415982609 10800 3600 604800 1800\nexample.com. 1800 IN NS ns1.digitalocean.com.\nexample.com. 1800 IN NS ns2.digitalocean.com.\nexample.com. 1800 IN NS ns3.digitalocean.com.\nexample.com. 1800 IN A 1.2.3.4\n"
    }
  ],
  "links": {
  },
  "meta": {
    "total": 1
  }
}

Create a New Domain

To create a new domain, send a POST request to /v2/domains. Set the "name" attribute to the domain name you are adding. Optionally, you may set the "ip_address" attribute, and an A record will be automatically created pointing to the apex domain.

NameTypeDescriptionRequired
namestringThe domain name to add to the DigitalOcean DNS management interface. The name must be unique in DigitalOcean's DNS system. The request will fail if the name has already been taken.true
ip_addressstringThis optional attribute may contain an IP address. When provided, an A record will be automatically created pointing to the apex domain.

The response will be a JSON object with a key called domain. The value of this will be an object that contains the standard attributes associated with a domain:

NameTypeDescription
namestringThe name of the domain itself. This should follow the standard domain format of domain.TLD. For instance, example.com is a valid domain name.
ttlintegerThis value is the time to live for the records on this domain, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.
zone_filestringThis attribute contains the complete contents of the zone file for the selected domain. Individual domain record resources should be used to get more granular control over records. However, this attribute can also be used to get information about the SOA record, which is created automatically and is not accessible as an individual record resource.

Keep in mind that, upon creation, the zone_file field will have a value of null until a zone file is generated and propagated through an automatic process on the DigitalOcean servers.

Create a New Domain

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name":"example.com","ip_address":"1.2.3.4"}' "https://api.digitalocean.com/v2/domains"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

domain = DropletKit::Domain.new(
  name: 'example.com',
  ip_address: '1.2.3.4'
)
client.domains.create(domain)

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

createRequest := &godo.DomainCreateRequest{
    Name:      "example.com",
    IPAddress: "1.2.3.4",
}

domain, _, err := client.Domains.Create(ctx, createRequest)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "name": "example.com",
  "ip_address": "1.2.3.4"
}

Response Headers

content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 1200
ratelimit-remaining: 1113
ratelimit-reset: 1415984218

Response Body

{
  "domain": {
    "name": "example.com",
    "ttl": 1800,
    "zone_file": null
  }
}

Retrieve an Existing Domain

To get details about a specific domain, send a GET request to /v2/domains/$DOMAIN_NAME.

The response will be a JSON object with a key called domain. The value of this will be an object that contains the standard attributes defined for a domain:

NameTypeDescription
namestringThe name of the domain itself. This should follow the standard domain format of domain.TLD. For instance, example.com is a valid domain name.
ttlintegerThis value is the time to live for the records on this domain, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.
zone_filestringThis attribute contains the complete contents of the zone file for the selected domain. Individual domain record resources should be used to get more granular control over records. However, this attribute can also be used to get information about the SOA record, which is created automatically and is not accessible as an individual record resource.

Retrieve an Existing Domain

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/domains/example.com"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.domains.find(name: 'example.com')

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

domain, _, err := client.Domains.Get(ctx, "example.com")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1112
ratelimit-reset: 1415984218

Response Body

{
  "domain": {
    "name": "example.com",
    "ttl": 1800,
    "zone_file": "$ORIGIN example.com.\n$TTL 1800\nexample.com. IN SOA ns1.digitalocean.com. hostmaster.example.com. 1415982611 10800 3600 604800 1800\nexample.com. 1800 IN NS ns1.digitalocean.com.\nexample.com. 1800 IN NS ns2.digitalocean.com.\nexample.com. 1800 IN NS ns3.digitalocean.com.\nexample.com. 1800 IN A 1.2.3.4\n"
  }
}

Delete a Domain

To delete a domain, send a DELETE request to /v2/domains/$DOMAIN_NAME.

The domain will be removed from your account and a response status of 204 will be returned. This indicates a successful request with no response body.

Delete a Domain

cURL Example

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/domains/example.com"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.domains.delete(name: 'example.com')

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

_, err := client.Domains.Delete(ctx, "example.com")

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

status: 204 No Content
ratelimit-limit: 1200
ratelimit-remaining: 1111
ratelimit-reset: 1415984218

Domain Records

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

The following table shows the standard domain record attributes. There is an id attribute that is auto-assigned for each record and used is as a unique identifier for requests. Each record contains all of these attribute types. For record types that do not utilize all fields, a value of null will be set for that record.

NameTypeDescription
idintegerA unique identifier for each domain record.
typestringThe type of the DNS record. For example: A, CNAME, TXT, ...
namestringThe host name, alias, or service being defined by the record.
datastringVariable data depending on record type. For example, the "data" value for an A record would be the IPv4 address to which the domain will be mapped. For a CAA record, it would contain the domain name of the CA being granted permission to issue certificates.
prioritynullable integerThe priority for SRV and MX records.
portnullable integerThe port for SRV records.
ttlintegerThis value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.
weightnullable integerThe weight for SRV records.
flagsintegerAn unsigned integer between 0-255 used for CAA records.
tagstringThe parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

List All Domain Records

To get a listing of all records configured for a domain, send a GET request to /v2/domains/$DOMAIN_NAME/records.

The list of records returned can be filtered by using the name and type query parameters. For example, to only include A records for a domain, send a GET request to /v2/domains/$DOMAIN_NAME/records?type=A. name must be a fully qualified record name. For example, to only include records matching sub.example.com, send a GET request to /v2/domains/$DOMAIN_NAME/records?name=sub.example.com. Both name and type may be used together.

The response will be a JSON object with a key called domain_records. The value of this will be an array of domain record objects, each of which contains the standard domain record attributes. For attributes that are not used by a specific record type, a value of null will be returned. For instance, all records other than SRV will have null for the weight and port attributes.

NameTypeDescription
idintegerA unique identifier for each domain record.
typestringThe type of the DNS record. For example: A, CNAME, TXT, ...
namestringThe host name, alias, or service being defined by the record.
datastringVariable data depending on record type. For example, the "data" value for an A record would be the IPv4 address to which the domain will be mapped. For a CAA record, it would contain the domain name of the CA being granted permission to issue certificates.
prioritynullable integerThe priority for SRV and MX records.
portnullable integerThe port for SRV records.
ttlintegerThis value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.
weightnullable integerThe weight for SRV records.
flagsintegerAn unsigned integer between 0-255 used for CAA records.
tagstringThe parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

List All Domain Records

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/domains/example.com/records"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

records = client.domain_records.all(for_domain: 'example.com')
records.each

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

opt := &godo.ListOptions{
    Page:    1,
    PerPage: 1,
}

records, _, err := client.Domains.Records(ctx, "example.com", opt)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1121
ratelimit-reset: 1415984218

Response Body

{
  "domain_records": [
    {
      "id": 28448429,
      "type": "NS",
      "name": "@",
      "data": "ns1.digitalocean.com",
      "priority": null,
      "port": null,
      "ttl": 1800,
      "weight": null,
      "flags": null,
      "tag": null
    },
    {
      "id": 28448430,
      "type": "NS",
      "name": "@",
      "data": "ns2.digitalocean.com",
      "priority": null,
      "port": null,
      "ttl": 1800,
      "weight": null,
      "flags": null,
      "tag": null
    },
    {
      "id": 28448431,
      "type": "NS",
      "name": "@",
      "data": "ns3.digitalocean.com",
      "priority": null,
      "port": null,
      "ttl": 1800,
      "weight": null,
      "flags": null,
      "tag": null
    },
    {
      "id": 28448432,
      "type": "A",
      "name": "@",
      "data": "1.2.3.4",
      "priority": null,
      "port": null,
      "ttl": 1800,
      "weight": null,
      "flags": null,
      "tag": null
    }
  ],
  "links": {
  },
  "meta": {
    "total": 4
  }
}

Create a New Domain Record

To create a new record to a domain, send a POST request to /v2/domains/$DOMAIN_NAME/records.

The request must include all of the required fields for the domain record type being added. The required attributes per domain record type:

NameTypeDescriptionRequired
typestringThe record type (A, MX, CNAME, etc).All Records
namestringThe host name, alias, or service being defined by the record.A, AAAA, CAA, CNAME, TXT, SRV
datastringVariable data depending on record type. For example, the "data" value for an A record would be the IPv4 address to which the domain will be mapped. For a CAA record, it would contain the domain name of the CA being granted permission to issue certificates.A, AAAA, CAA, CNAME, MX, TXT, SRV, NS
prioritynullable integerThe priority of the host (for SRV and MX records. null otherwise).MX, SRV
portnullable integerThe port that the service is accessible on (for SRV records only. null otherwise).SRV
ttlintegerThis value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested. There is a minimum ttl value of 30, unless it is not set. If not set, the default value is the value of the SOA record. For SOA records, defines the time to live for purposes of negative caching.SOA
weightnullable integerThe weight of records with the same priority (for SRV records only. null otherwise).SRV
flagsnullable integerAn unsigned integer between 0-255 used for CAA records.CAA
tagstringThe parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"CAA

The response body will be a JSON object with a key called domain_record. The value of this will be an object representing the new record. Attributes that are not applicable for the record type will be set to null. An id attribute is generated for each record as part of the object.

NameTypeDescription
idintegerA unique identifier for each domain record.
typestringThe type of the DNS record. For example: A, CNAME, TXT, ...
namestringThe host name, alias, or service being defined by the record.
datastringVariable data depending on record type. For example, the "data" value for an A record would be the IPv4 address to which the domain will be mapped. For a CAA record, it would contain the domain name of the CA being granted permission to issue certificates.
prioritynullable integerThe priority for SRV and MX records.
portnullable integerThe port for SRV records.
ttlintegerThis value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.
weightnullable integerThe weight for SRV records.
flagsintegerAn unsigned integer between 0-255 used for CAA records.
tagstringThe parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

Create a New Domain Record

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"A","name":"www","data":"162.10.66.0","priority":null,"port":null,"ttl":1800,"weight":null,"flags":null,"tag":null}' "https://api.digitalocean.com/v2/domains/example.com/records"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

record = DropletKit::DomainRecord.new(
  type: 'A',
  name: 'www',
  data: '162.10.66.0'
)
client.domain_records.create(record, for_domain: 'example.com')

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

createRequest := &godo.DomainRecordEditRequest{
    Type: "A",
    Name: "www",
    Data: "1.2.3.4",
}

domainRecord, _, err := client.Domains.CreateRecord(ctx, "example.com", createRequest)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "type": "A",
  "name": "www",
  "data": "162.10.66.0",
  "priority": null,
  "port": null,
  "ttl": 1800,
  "weight": null,
  "flags": null,
  "tag": null
}

Response Headers

content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 1200
ratelimit-remaining: 1120
ratelimit-reset: 1415984218

Response Body

{
  "domain_record": {
    "id": 28448433,
    "type": "A",
    "name": "www",
    "data": "162.10.66.0",
    "priority": null,
    "port": null,
    "ttl": 1800,
    "weight": null,
    "flags": null,
    "tag": null
  }
}

Retrieve an Existing Domain Record

To retrieve a specific domain record, send a GET request to /v2/domains/$DOMAIN_NAME/records/$RECORD_ID.

The response will be a JSON object with a key called domain_record. The value of this will be an object that contains all of the standard domain record attributes:

NameTypeDescription
idintegerA unique identifier for each domain record.
typestringThe type of the DNS record. For example: A, CNAME, TXT, ...
namestringThe host name, alias, or service being defined by the record.
datastringVariable data depending on record type. For example, the "data" value for an A record would be the IPv4 address to which the domain will be mapped. For a CAA record, it would contain the domain name of the CA being granted permission to issue certificates.
prioritynullable integerThe priority for SRV and MX records.
portnullable integerThe port for SRV records.
ttlintegerThis value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.
weightnullable integerThe weight for SRV records.
flagsintegerAn unsigned integer between 0-255 used for CAA records.
tagstringThe parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

Retrieve an Existing Domain Record

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/domains/example.com/records/3352896"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.domain_records.find(for_domain: 'example.com', id: 3352896)

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

record, _, err := client.Domains.Record(ctx, "example.com", 3352896)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1119
ratelimit-reset: 1415984218

Response Body

{
  "domain_record": {
    "id": 28448433,
    "type": "A",
    "name": "www",
    "data": "162.10.66.0",
    "priority": null,
    "port": null,
    "ttl": 1800,
    "weight": null,
    "flags": null,
    "tag": null
  }
}

Update a Domain Record

To update an existing record, send a PUT request to /v2/domains/$DOMAIN_NAME/records/$RECORD_ID. Any attribute valid for the record type can be set to a new value for the record.

NameTypeDescriptionRequired
typestringThe record type (A, MX, CNAME, etc).All Records
namestringThe host name, alias, or service being defined by the record.A, AAAA, CAA, CNAME, TXT, SRV
datastringVariable data depending on record type. For example, the "data" value for an A record would be the IPv4 address to which the domain will be mapped. For a CAA record, it would contain the domain name of the CA being granted permission to issue certificates.A, AAAA, CAA, CNAME, MX, TXT, SRV, NS
prioritynullable integerThe priority of the host (for SRV and MX records. null otherwise).MX, SRV
portnullable integerThe port that the service is accessible on (for SRV records only. null otherwise).SRV
ttlintegerThis value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested. There is a minimum ttl value of 30, unless it is not set. If not set, the default value is the value of the SOA record. For SOA records, defines the time to live for purposes of negative caching.SOA
weightnullable integerThe weight of records with the same priority (for SRV records only. null otherwise).SRV
flagsnullable integerAn unsigned integer between 0-255 used for CAA records.CAA
tagstringThe parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"CAA

The response will be a JSON object with a key called domain_record. The value of this will be a domain record object which contains the standard domain record attributes:

NameTypeDescription
idintegerA unique identifier for each domain record.
typestringThe type of the DNS record. For example: A, CNAME, TXT, ...
namestringThe host name, alias, or service being defined by the record.
datastringVariable data depending on record type. For example, the "data" value for an A record would be the IPv4 address to which the domain will be mapped. For a CAA record, it would contain the domain name of the CA being granted permission to issue certificates.
prioritynullable integerThe priority for SRV and MX records.
portnullable integerThe port for SRV records.
ttlintegerThis value is the time to live for the record, in seconds. This defines the time frame that clients can cache queried information before a refresh should be requested.
weightnullable integerThe weight for SRV records.
flagsintegerAn unsigned integer between 0-255 used for CAA records.
tagstringThe parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef"

Update a Domain Record

cURL Example

curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name":"blog"}' "https://api.digitalocean.com/v2/domains/example.com/records/3352896"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

record = DropletKit::DomainRecord.new(name: 'blog')
client.domain_records.update(record, for_domain: 'example.com', id: 3352896)

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

editRequest := &godo.DomainRecordEditRequest{
    Type: "A",
    Name: "blog",
}

domainRecord, _, err := client.Domains.EditRecord(ctx, "example.com", 3352896, editRequest)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "name": "blog"
}

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1118
ratelimit-reset: 1415984218

Response Body

{
  "domain_record": {
    "id": 3352896,
    "type": "A",
    "name": "blog",
    "data": "162.10.66.0",
    "priority": null,
    "port": null,
    "ttl": 1800,
    "weight": null,
    "flags": null,
    "tag": null
  }
}

Delete a Domain Record

To delete a record for a domain, send a DELETE request to /v2/domains/$DOMAIN_NAME/records/$RECORD_ID.

The record will be deleted and the response status will be a 204. This indicates a successful request with no body returned.

Delete a Domain Record

cURL Example

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/domains/example.com/records/3352896"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.domain_records.delete(for_domain: 'example.com', id: 3352896)

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

_, err := client.Domains.DeleteRecord(ctx, "example.com", 3352896)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/octet-stream
status: 204 No Content
ratelimit-limit: 1200
ratelimit-remaining: 1117
ratelimit-reset: 1415984218

Droplets

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.

NameTypeDescription
idintegerA unique identifier for each Droplet instance. This is automatically generated upon Droplet creation.
namestringThe human-readable name set for the Droplet instance.
memoryintegerMemory of the Droplet in megabytes.
vcpusintegerThe number of virtual CPUs.
diskintegerThe size of the Droplet's disk in gigabytes.
lockedbooleanA boolean value indicating whether the Droplet has been locked, preventing actions by users.
created_atstringA time value given in ISO8601 combined date and time format that represents when the Droplet was created.
statusstringA status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive".
backup_idsarrayAn 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.
snapshot_idsarrayAn array of snapshot IDs of any snapshots created from the Droplet instance.
featuresarrayAn array of features enabled on this Droplet.
regionobjectThe region that the Droplet instance is deployed in. When setting a region, the value should be the slug identifier for the region. When you query a Droplet, the entire region object will be returned.
imageobjectThe base image used to create the Droplet instance. When setting an image, the value is set to the image id or slug. When querying the Droplet, the entire image object will be returned.
sizeobjectThe current size object describing the Droplet. When setting a size, the value is set to the size slug. When querying the Droplet, the entire size object will be returned. Note that the disk volume of a Droplet may not match the size's disk due to Droplet resize actions. The disk attribute on the Droplet should always be referenced.
size_slugstringThe unique slug identifier for the size of this Droplet.
networksobjectThe 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.
kernelnullable objectThe current kernel. This will initially be set to the kernel of the base image when the Droplet is created.
next_backup_windownullable objectThe details of the Droplet's backups feature, if backups are configured for the Droplet. This object contains keys for the start and end times of the window during which the backup will start.
tagsarrayAn array of Tags the Droplet has been tagged with.
volume_idsarrayA flat array including the unique identifier for each Block Storage volume attached to the Droplet.
vpc_uuidstringA string specifying the UUID of the VPC to which the Droplet is assigned.

Create a New Droplet

To create a new Droplet, send a POST request to /v2/droplets.

The attribute values that must be set to successfully create a Droplet are:

NameTypeDescriptionRequired
nameStringThe 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.true
regionStringThe unique slug identifier for the region that you wish to deploy in.true
sizeStringThe unique slug identifier for the size that you wish to select for this Droplet.true
imageinteger (if using an image ID), or String (if using a public image slug)The image ID of a public or private image, or the unique slug identifier for a public image. This image will be the base image for your Droplet.true
ssh_keysArrayAn array containing the IDs or fingerprints of the SSH keys that you wish to embed in the Droplet's root account upon creation.
backupsBooleanA boolean indicating whether automated backups should be enabled for the Droplet. Automated backups can only be enabled when the Droplet is created.
ipv6BooleanA boolean indicating whether IPv6 is enabled on the Droplet.
private_networkingBooleanThis 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 the default VPC.
vpc_uuidstringA string specifying the UUID of the VPC to which the Droplet will be assigned. If excluded, beginning on April 7th, 2020, the Droplet will be assigned to your account's default VPC for the region.
user_dataStringA 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.
monitoringBooleanA boolean indicating whether to install the DigitalOcean agent for monitoring.
volumesArrayA flat array including the unique string identifier for each block storage volume to be attached to the Droplet. At the moment a volume can only be attached to a single Droplet.
tagsArrayA 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.

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.

NameTypeDescription
idintegerA unique identifier for each Droplet instance. This is automatically generated upon Droplet creation.
namestringThe human-readable name set for the Droplet instance.
memoryintegerMemory of the Droplet in megabytes.
vcpusintegerThe number of virtual CPUs.
diskintegerThe size of the Droplet's disk in gigabytes.
lockedbooleanA boolean value indicating whether the Droplet has been locked, preventing actions by users.
created_atstringA time value given in ISO8601 combined date and time format that represents when the Droplet was created.
statusstringA status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive".
backup_idsarrayAn 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.
snapshot_idsarrayAn array of snapshot IDs of any snapshots created from the Droplet instance.
featuresarrayAn array of features enabled on this Droplet.
regionobjectThe region that the Droplet instance is deployed in. When setting a region, the value should be the slug identifier for the region. When you query a Droplet, the entire region object will be returned.
imageobjectThe base image used to create the Droplet instance. When setting an image, the value is set to the image id or slug. When querying the Droplet, the entire image object will be returned.
sizeobjectThe current size object describing the Droplet. When setting a size, the value is set to the size slug. When querying the Droplet, the entire size object will be returned. Note that the disk volume of a Droplet may not match the size's disk due to Droplet resize actions. The disk attribute on the Droplet should always be referenced.
size_slugstringThe unique slug identifier for the size of this Droplet.
networksobjectThe 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.
kernelnullable objectThe current kernel. This will initially be set to the kernel of the base image when the Droplet is created.
next_backup_windownullable objectThe details of the Droplet's backups feature, if backups are configured for the Droplet. This object contains keys for the start and end times of the window during which the backup will start.
tagsarrayAn array of Tags the Droplet has been tagged with.
volume_idsarrayA flat array including the unique identifier for each Block Storage volume attached to the Droplet.
vpc_uuidstringA string specifying the UUID of the VPC to which the Droplet is assigned.

Create a New Droplet

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name":"example.com","region":"nyc3","size":"s-1vcpu-1gb","image":"ubuntu-16-04-x64","ssh_keys":[107149],"backups":false,"ipv6":true,"user_data":null,"private_networking":null,"volumes": null,"tags":["web"]}' "https://api.digitalocean.com/v2/droplets"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

droplet = DropletKit::Droplet.new(
  name: 'example.com',
  region: 'nyc3',
  size: 's-1vcpu-1gb',
  image: 'ubuntu-16-04-x64',
  ssh_keys: [107149],
  ipv6: true,
  tags: ["web"]
)
client.droplets.create(droplet)

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

createRequest := &godo.DropletCreateRequest{
    Name:   "example.com",
    Region: "nyc3",
    Size:   "s-1vcpu-1gb",
    Image: godo.DropletCreateImage{
        Slug: "ubuntu-16-04-x64",
    },
    SSHKeys: []godo.DropletCreateSSHKey{
        godo.DropletCreateSSHKey{ID: 107149},
    },
    IPv6: true,
    Tags: []string{"web"},
}

droplet, _, err := client.Droplets.Create(ctx, createRequest)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "name": "example.com",
  "region": "nyc3",
  "size": "s-1vcpu-1gb",
  "image": "ubuntu-16-04-x64",
  "ssh_keys": [
    107149
  ],
  "backups": false,
  "ipv6": true,
  "user_data": null,
  "private_networking": null,
  "volumes": null,
  "tags": [
    "web"
  ]
}

Response Headers

content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 1200
ratelimit-remaining: 965
ratelimit-reset: 1415984218

Response Body

{
  "droplet": {
    "id": 3164494,
    "name": "example.com",
    "memory": 1024,
    "vcpus": 1,
    "disk": 25,
    "locked": true,
    "status": "new",
    "kernel": {
      "id": 2233,
      "name": "Ubuntu 14.04 x64 vmlinuz-3.13.0-37-generic",
      "version": "3.13.0-37-generic"
    },
    "created_at": "2014-11-14T16:36:31Z",
    "features": [
      "virtio"
    ],
    "backup_ids": [

    ],
    "snapshot_ids": [

    ],
    "image": {
    },
    "volume_ids": [

    ],
    "size": {
    },
    "size_slug": "s-1vcpu-1gb",
    "networks": {
    },
    "region": {
    },
    "tags": [
      "web"
    ]
  },
  "links": {
    "actions": [
      {
        "id": 36805096,
        "rel": "create",
        "href": "https://api.digitalocean.com/v2/actions/36805096"
      }
    ]
  }
}

Create Multiple Droplets

To create multiple Droplets, send a POST request to /v2/droplets.

Creating multiple Droplets is very similar to creating a single Droplet, but 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 at a time. The possible fields are:

NameTypeDescriptionRequired
namesArrayAn 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.true
regionStringThe unique slug identifier for the region that you wish to deploy in.true
sizeStringThe unique slug identifier for the size that you wish to select for this Droplet.true
imageinteger (if using an image ID), or String (if using a public image slug)The image ID of a public or private image, or the unique slug identifier for a public image. This image will be the base image for your Droplet.true
ssh_keysArrayAn array containing the IDs or fingerprints of the SSH keys that you wish to embed in the Droplet's root account upon creation.
backupsBooleanA boolean indicating whether automated backups should be enabled for the Droplet. Automated backups can only be enabled when the Droplet is created.
ipv6BooleanA boolean indicating whether IPv6 is enabled on the Droplet.
private_networkingBooleanThis 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 the default VPC.
vpc_uuidstringA string specifying the UUID of the VPC to which the Droplet will be assigned. If excluded, beginning on April 7th, 2020, the Droplet will be assigned to your account's default VPC for the region.
user_dataStringA 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.
monitoringBooleanA boolean indicating whether to install the DigitalOcean agent for monitoring.
tagsArrayA 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.

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 arrary of actions returned as part of the response's links object can be used to check the status of each invividual Droplet create event.

NameTypeDescription
idintegerA unique identifier for each Droplet instance. This is automatically generated upon Droplet creation.
namestringThe human-readable name set for the Droplet instance.
memoryintegerMemory of the Droplet in megabytes.
vcpusintegerThe number of virtual CPUs.
diskintegerThe size of the Droplet's disk in gigabytes.
lockedbooleanA boolean value indicating whether the Droplet has been locked, preventing actions by users.
created_atstringA time value given in ISO8601 combined date and time format that represents when the Droplet was created.
statusstringA status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive".
backup_idsarrayAn 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.
snapshot_idsarrayAn array of snapshot IDs of any snapshots created from the Droplet instance.
featuresarrayAn array of features enabled on this Droplet.
regionobjectThe region that the Droplet instance is deployed in. When setting a region, the value should be the slug identifier for the region. When you query a Droplet, the entire region object will be returned.
imageobjectThe base image used to create the Droplet instance. When setting an image, the value is set to the image id or slug. When querying the Droplet, the entire image object will be returned.
sizeobjectThe current size object describing the Droplet. When setting a size, the value is set to the size slug. When querying the Droplet, the entire size object will be returned. Note that the disk volume of a Droplet may not match the size's disk due to Droplet resize actions. The disk attribute on the Droplet should always be referenced.
size_slugstringThe unique slug identifier for the size of this Droplet.
networksobjectThe 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.
kernelnullable objectThe current kernel. This will initially be set to the kernel of the base image when the Droplet is created.
next_backup_windownullable objectThe details of the Droplet's backups feature, if backups are configured for the Droplet. This object contains keys for the start and end times of the window during which the backup will start.
tagsarrayAn array of Tags the Droplet has been tagged with.
volume_idsarrayA flat array including the unique identifier for each Block Storage volume attached to the Droplet.
vpc_uuidstringA string specifying the UUID of the VPC to which the Droplet is assigned.

Create Multiple Droplets

cURL Example

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"names":["sub-01.example.com","sub-02.example.com"],"region":"nyc3","size":"s-1vcpu-1gb","image":"ubuntu-16-04-x64","ssh_keys":null,"backups":false,"ipv6":true,"user_data":null,"private_networking":null,"tags":["web"]}' "https://api.digitalocean.com/v2/droplets"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

droplet = DropletKit::Droplet.new(
  names: ['sub-01.example.com', 'sub-02.example.com'],
  region: 'nyc3',
  size: 's-1vcpu-1gb',
  image: 'ubuntu-16-04-x64',
  ipv6: true,
  tags: ["web"]
)
client.droplets.create_multiple(droplet)

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

createRequest := &godo.DropletMultiCreateRequest{
    Names:   []string{"sub-01.example.com","sub-02.example.com"},
    Region: "nyc3",
    Size:   "s-1vcpu-1gb",
    Image: godo.DropletCreateImage{
       Slug: "ubuntu-16-04-x64",
     },
    IPv6: true,
    Tags: []string{"web"},
}

droplet, _, err := client.Droplets.CreateMultiple(ctx, createRequest)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Request Body

{
  "names": [
    "sub-01.example.com",
    "sub-02.example.com"
  ],
  "region": "nyc3",
  "size": "s-1vcpu-1gb",
  "image": "ubuntu-16-04-x64",
  "ssh_keys": null,
  "backups": false,
  "ipv6": true,
  "user_data": null,
  "private_networking": null,
  "tags": [
    "web"
  ]
}

Response Headers

content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 1200
ratelimit-remaining: 965
ratelimit-reset: 1415984218

Response Body

{
  "droplets": [
    {
      "id": 3164494,
      "name": "sub-01.example.com",
      "memory": 1024,
      "vcpus": 1,
      "disk": 25,
      "locked": false,
      "status": "new",
      "kernel": {
        "id": 2233,
        "name": "Ubuntu 14.04 x64 vmlinuz-3.13.0-37-generic",
        "version": "3.13.0-37-generic"
      },
      "created_at": "2014-11-14T16:36:31Z",
      "features": [
        "virtio"
      ],
      "backup_ids": [

      ],
      "snapshot_ids": [

      ],
      "image": {
      },
      "volume_ids": [

      ],
      "size": {
      },
      "size_slug": "s-1vcpu-1gb",
      "networks": {
      },
      "region": {
      },
      "tags": [
        "web"
      ]
    },
    {
      "id": 3164495,
      "name": "sub-02.example.com",
      "memory": 1024,
      "vcpus": 1,
      "disk": 25,
      "locked": false,
      "status": "new",
      "kernel": {
        "id": 2233,
        "name": "Ubuntu 14.04 x64 vmlinuz-3.13.0-37-generic",
        "version": "3.13.0-37-generic"
      },
      "created_at": "2014-11-14T16:36:31Z",
      "features": [
        "virtio"
      ],
      "backup_ids": [

      ],
      "snapshot_ids": [

      ],
      "image": {
      },
      "volume_ids": [

      ],
      "size": {
      },
      "size_slug": "s-1vcpu-1gb",
      "networks": {
      },
      "region": {
      },
      "tags": [
        "web"
      ]
    }
  ],
  "links": {
    "actions": [
      {
        "id": 24404896,
        "rel": "create",
        "href": "https://api.digitalocean.com/v2/actions/24404896"
      },
      {
        "id": 24404897,
        "rel": "create",
        "href": "https://api.digitalocean.com/v2/actions/24404897"
      }
    ]
  }
}

Retrieve an Existing Droplet by ID

To show information about an individual Droplet, send a GET request to /v2/droplets/$DROPLET_ID.

The response will be a JSON object with a key called droplet. This will be set to a JSON object that contains the Droplet's attributes:

NameTypeDescription
idintegerA unique identifier for each Droplet instance. This is automatically generated upon Droplet creation.
namestringThe human-readable name set for the Droplet instance.
memoryintegerMemory of the Droplet in megabytes.
vcpusintegerThe number of virtual CPUs.
diskintegerThe size of the Droplet's disk in gigabytes.
lockedbooleanA boolean value indicating whether the Droplet has been locked, preventing actions by users.
created_atstringA time value given in ISO8601 combined date and time format that represents when the Droplet was created.
statusstringA status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive".
backup_idsarrayAn 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.
snapshot_idsarrayAn array of snapshot IDs of any snapshots created from the Droplet instance.
featuresarrayAn array of features enabled on this Droplet.
regionobjectThe region that the Droplet instance is deployed in. When setting a region, the value should be the slug identifier for the region. When you query a Droplet, the entire region object will be returned.
imageobjectThe base image used to create the Droplet instance. When setting an image, the value is set to the image id or slug. When querying the Droplet, the entire image object will be returned.
sizeobjectThe current size object describing the Droplet. When setting a size, the value is set to the size slug. When querying the Droplet, the entire size object will be returned. Note that the disk volume of a Droplet may not match the size's disk due to Droplet resize actions. The disk attribute on the Droplet should always be referenced.
size_slugstringThe unique slug identifier for the size of this Droplet.
networksobjectThe 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.
kernelnullable objectThe current kernel. This will initially be set to the kernel of the base image when the Droplet is created.
next_backup_windownullable objectThe details of the Droplet's backups feature, if backups are configured for the Droplet. This object contains keys for the start and end times of the window during which the backup will start.
tagsarrayAn array of Tags the Droplet has been tagged with.
volume_idsarrayA flat array including the unique identifier for each Block Storage volume attached to the Droplet.
vpc_uuidstringA string specifying the UUID of the VPC to which the Droplet is assigned.

Retrieve an Existing Droplet by ID

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/droplets/3164494"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

client.droplets.find(id: 3164494)

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

droplet, _, err := client.Droplets.Get(ctx, 3164494)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 902
ratelimit-reset: 1415984218

Response Body

{
  "droplet": {
    "id": 3164494,
    "name": "example.com",
    "memory": 1024,
    "vcpus": 1,
    "disk": 25,
    "locked": false,
    "status": "active",
    "kernel": {
      "id": 2233,
      "name": "Ubuntu 14.04 x64 vmlinuz-3.13.0-37-generic",
      "version": "3.13.0-37-generic"
    },
    "created_at": "2014-11-14T16:36:31Z",
    "features": [
      "ipv6",
      "virtio"
    ],
    "backup_ids": [

    ],
    "snapshot_ids": [
      7938206
    ],
    "image": {
      "id": 6918990,
      "name": "14.04 x64",
      "distribution": "Ubuntu",
      "slug": "ubuntu-16-04-x64",
      "public": true,
      "regions": [
        "nyc1",
        "ams1",
        "sfo1",
        "nyc2",
        "ams2",
        "sgp1",
        "lon1",
        "nyc3",
        "ams3",
        "nyc3"
      ],
      "created_at": "2014-10-17T20:24:33Z",
      "type": "snapshot",
      "min_disk_size": 20,
      "size_gigabytes": 2.34
    },
    "volume_ids": [

    ],
    "size": {
    },
    "size_slug": "s-1vcpu-1gb",
    "networks": {
      "v4": [
        {
          "ip_address": "104.131.186.241",
          "netmask": "255.255.240.0",
          "gateway": "104.131.176.1",
          "type": "public"
        }
      ],
      "v6": [
        {
          "ip_address": "2604:A880:0800:0010:0000:0000:031D:2001",
          "netmask": 64,
          "gateway": "2604:A880:0800:0010:0000:0000:0000:0001",
          "type": "public"
        }
      ]
    },
    "region": {
      "name": "New York 3",
      "slug": "nyc3",
      "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-192gb"
      ],
      "features": [
        "virtio",
        "private_networking",
        "backups",
        "ipv6",
        "metadata"
      ],
      "available": true
    },
    "tags": [

    ],
    "vpc_uuid": "f9b0769c-e118-42fb-a0c4-fed15ef69662"
  }
}

List All Droplets

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 representing each Droplet. These will contain the standard Droplet attributes:

NameTypeDescription
idintegerA unique identifier for each Droplet instance. This is automatically generated upon Droplet creation.
namestringThe human-readable name set for the Droplet instance.
memoryintegerMemory of the Droplet in megabytes.
vcpusintegerThe number of virtual CPUs.
diskintegerThe size of the Droplet's disk in gigabytes.
lockedbooleanA boolean value indicating whether the Droplet has been locked, preventing actions by users.
created_atstringA time value given in ISO8601 combined date and time format that represents when the Droplet was created.
statusstringA status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive".
backup_idsarrayAn 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.
snapshot_idsarrayAn array of snapshot IDs of any snapshots created from the Droplet instance.
featuresarrayAn array of features enabled on this Droplet.
regionobjectThe region that the Droplet instance is deployed in. When setting a region, the value should be the slug identifier for the region. When you query a Droplet, the entire region object will be returned.
imageobjectThe base image used to create the Droplet instance. When setting an image, the value is set to the image id or slug. When querying the Droplet, the entire image object will be returned.
sizeobjectThe current size object describing the Droplet. When setting a size, the value is set to the size slug. When querying the Droplet, the entire size object will be returned. Note that the disk volume of a Droplet may not match the size's disk due to Droplet resize actions. The disk attribute on the Droplet should always be referenced.
size_slugstringThe unique slug identifier for the size of this Droplet.
networksobjectThe 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.
kernelnullable objectThe current kernel. This will initially be set to the kernel of the base image when the Droplet is created.
next_backup_windownullable objectThe details of the Droplet's backups feature, if backups are configured for the Droplet. This object contains keys for the start and end times of the window during which the backup will start.
tagsarrayAn array of Tags the Droplet has been tagged with.
volume_idsarrayA flat array including the unique identifier for each Block Storage volume attached to the Droplet.
vpc_uuidstringA string specifying the UUID of the VPC to which the Droplet is assigned.

List All Droplets

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/droplets?page=1&per_page=1"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

droplets = client.droplets.all
droplets.each

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

opt := &godo.ListOptions{
    Page:    1,
    PerPage: 200,
}

droplets, _, err := client.Droplets.List(ctx, opt)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 947
ratelimit-reset: 1415984218

Response Body

{
  "droplets": [
    {
      "id": 3164444,
      "name": "example.com",
      "memory": 1024,
      "vcpus": 1,
      "disk": 25,
      "locked": false,
      "status": "active",
      "kernel": {
        "id": 2233,
        "name": "Ubuntu 14.04 x64 vmlinuz-3.13.0-37-generic",
        "version": "3.13.0-37-generic"
      },
      "created_at": "2014-11-14T16:29:21Z",
      "features": [
        "backups",
        "ipv6",
        "virtio"
      ],
      "backup_ids": [
        7938002
      ],
      "snapshot_ids": [

      ],
      "image": {
        "id": 6918990,
        "name": "14.04 x64",
        "distribution": "Ubuntu",
        "slug": "ubuntu-16-04-x64",
        "public": true,
        "regions": [
          "nyc1",
          "ams1",
          "sfo1",
          "nyc2",
          "ams2",
          "sgp1",
          "lon1",
          "nyc3",
          "ams3",
          "nyc3"
        ],
        "created_at": "2014-10-17T20:24:33Z",
        "type": "snapshot",
        "min_disk_size": 20,
        "size_gigabytes": 2.34
      },
      "volume_ids": [

      ],
      "size": {
      },
      "size_slug": "s-1vcpu-1gb",
      "networks": {
        "v4": [
          {
            "ip_address": "104.236.32.182",
            "netmask": "255.255.192.0",
            "gateway": "104.236.0.1",
            "type": "public"
          }
        ],
        "v6": [
          {
            "ip_address": "2604:A880:0800:0010:0000:0000:02DD:4001",
            "netmask": 64,
            "gateway": "2604:A880:0800:0010:0000:0000:0000:0001",
            "type": "public"
          }
        ]
      },
      "region": {
        "name": "New York 3",
        "slug": "nyc3",
        "sizes": [

        ],
        "features": [
          "virtio",
          "private_networking",
          "backups",
          "ipv6",
          "metadata"
        ],
        "available": null
      },
      "tags": [

      ],
      "vpc_uuid": "f9b0769c-e118-42fb-a0c4-fed15ef69662"
    }
  ],
  "links": {
    "pages": {
      "last": "https://api.digitalocean.com/v2/droplets?page=3&per_page=1",
      "next": "https://api.digitalocean.com/v2/droplets?page=2&per_page=1"
    }
  },
  "meta": {
    "total": 3
  }
}

Listing Droplets by Tag

To list Droplets by a tag, send a GET request to /v2/droplets?tag_name=$TAG_NAME.

The response will match that of regular droplet listing request but will be filtered to only include the tagged Droplets.

Listing Droplets by Tag

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/droplets?tag_name=awesome"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

droplets = client.droplets.all(tag_name: awesome)
droplets.each

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

opt := &godo.ListOptions{
    Page:    1,
    PerPage: 200,
}

droplets, _, err := client.Droplets.ListByTag(ctx, "awesome", opt)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/octet-stream
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 901
ratelimit-reset: 1415984218

Response Body

{
  "droplets": [
    {
      "id": 3164444,
      "name": "example.com",
      "memory": 1024,
      "vcpus": 1,
      "disk": 25,
      "locked": false,
      "status": "active",
      "kernel": {
        "id": 2233,
        "name": "Ubuntu 14.04 x64 vmlinuz-3.13.0-37-generic",
        "version": "3.13.0-37-generic"
      },
      "created_at": "2014-11-14T16:29:21Z",
      "features": [
        "backups",
        "ipv6",
        "virtio"
      ],
      "backup_ids": [
        7938002
      ],
      "snapshot_ids": [

      ],
      "image": {
        "id": 6918990,
        "name": "14.04 x64",
        "distribution": "Ubuntu",
        "slug": "ubuntu-16-04-x64",
        "public": true,
        "regions": [
          "nyc1",
          "ams1",
          "sfo1",
          "nyc2",
          "ams2",
          "sgp1",
          "lon1",
          "nyc3",
          "ams3",
          "nyc3"
        ],
        "created_at": "2014-10-17T20:24:33Z",
        "type": "snapshot",
        "min_disk_size": 20,
        "size_gigabytes": 2.34
      },
      "volume_ids": [

      ],
      "size": {
      },
      "size_slug": "s-1vcpu-1gb",
      "networks": {
        "v4": [
          {
            "ip_address": "104.236.32.182",
            "netmask": "255.255.192.0",
            "gateway": "104.236.0.1",
            "type": "public"
          }
        ],
        "v6": [
          {
            "ip_address": "2604:A880:0800:0010:0000:0000:02DD:4001",
            "netmask": 64,
            "gateway": "2604:A880:0800:0010:0000:0000:0000:0001",
            "type": "public"
          }
        ]
      },
      "region": {
        "name": "New York 3",
        "slug": "nyc3",
        "sizes": [

        ],
        "features": [
          "virtio",
          "private_networking",
          "backups",
          "ipv6",
          "metadata"
        ],
        "available": null
      },
      "tags": [
        "awesome"
      ],
      "vpc_uuid": "f9b0769c-e118-42fb-a0c4-fed15ef69662"
    }
  ],
  "links": {
    "pages": {
      "last": "https://api.digitalocean.com/v2/droplets?page=3&per_page=1",
      "next": "https://api.digitalocean.com/v2/droplets?page=2&per_page=1"
    }
  },
  "meta": {
    "total": 3
  }
}

List All Available Kernels for a Droplet

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:

NameTypeDescription
idintegerA unique number used to identify and reference a specific kernel.
namestringThe display name of the kernel. This is shown in the web UI and is generally a descriptive title for the kernel in question.
versionstringA standard kernel version string representing the version, patch, and release information.

List All Available Kernels for a Droplet

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/droplets/3164494/kernels?page=1&per_page=1"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

kernels = client.droplets.kernels(id: 3164494)
kernels.each

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

opt := &godo.ListOptions{
    Page:    1,
    PerPage: 200,
}

kernels, _, err := client.Droplets.Kernels(ctx, 3164494, opt)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 946
ratelimit-reset: 1415984218

Response Body

{
  "kernels": [
    {
      "id": 231,
      "name": "DO-recovery-static-fsck",
      "version": "3.8.0-25-generic"
    }
  ],
  "links": {
    "pages": {
      "last": "https://api.digitalocean.com/v2/droplets/3164494/kernels?page=124&per_page=1",
      "next": "https://api.digitalocean.com/v2/droplets/3164494/kernels?page=2&per_page=1"
    }
  },
  "meta": {
    "total": 124
  }
}

List snapshots for a Droplet

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 image attributes:

NameTypeDescription
idintegerA unique number used to identify and reference a specific image.
namestringThe display name of the image. This is shown in the web UI and is generally a descriptive title for the image in question.
typestringDescribes the kind of image. It may be one of "snapshot", "backup", or "custom". This specifies whether an image is a user-generated Droplet snapshot, automatically created Droplet backup, or a user-provided virtual machine image.
distributionstringThe base distribution used for this image.
slugnullable stringA uniquely identifying string that is associated with each of the DigitalOcean-provided public images. These can be used to reference a public image as an alternative to the numeric id.
publicbooleanA boolean value that indicates whether the image in question is public. An image that is public is available to all accounts. A non-public image is only accessible from your account.
regionsarrayAn array of the regions that the image is available in. The regions are represented by their identifying slug values.
min_disk_sizeintegerThe minimum 'disk' required for a size to use this image.
created_atstringA time value given in ISO8601 combined date and time format that represents when the Image was created.

List snapshots for a Droplet

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/droplets/3164494/snapshots?page=1&per_page=1"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

snapshots = client.droplets.snapshots(id: 3164494)
snapshots.each

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

opt := &godo.ListOptions{
    Page:    1,
    PerPage: 200,
}

snapshots, _, err := client.Droplets.Snapshots(ctx, 3164494, opt)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 904
ratelimit-reset: 1415984218

Response Body

{
  "snapshots": [
    {
      "id": 7938206,
      "name": "nginx-fresh",
      "distribution": "Ubuntu",
      "slug": null,
      "public": false,
      "regions": [
        "nyc3",
        "nyc3"
      ],
      "created_at": "2014-11-14T16:37:34Z",
      "type": "snapshot",
      "min_disk_size": 20,
      "size_gigabytes": 2.34
    }
  ],
  "links": {
  },
  "meta": {
    "total": 1
  }
}

List Backups for a Droplet

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 image attributes:

NameTypeDescription
idintegerA unique number used to identify and reference a specific image.
namestringThe display name of the image. This is shown in the web UI and is generally a descriptive title for the image in question.
typestringDescribes the kind of image. It may be one of "snapshot", "backup", or "custom". This specifies whether an image is a user-generated Droplet snapshot, automatically created Droplet backup, or a user-provided virtual machine image.
distributionstringThe base distribution used for this image.
slugnullable stringA uniquely identifying string that is associated with each of the DigitalOcean-provided public images. These can be used to reference a public image as an alternative to the numeric id.
publicbooleanA boolean value that indicates whether the image in question is public. An image that is public is available to all accounts. A non-public image is only accessible from your account.
regionsarrayAn array of the regions that the image is available in. The regions are represented by their identifying slug values.
min_disk_sizeintegerThe minimum 'disk' required for a size to use this image.
created_atstringA time value given in ISO8601 combined date and time format that represents when the Image was created.

List Backups for a Droplet

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/droplets/3067509/backups"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

backups = client.droplets.backups(id: 3164494)
backups.each

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

opt := &godo.ListOptions{
    Page:    1,
    PerPage: 200,
}

backups, _, err := client.Droplets.Backups(ctx, 3164494, opt)

Request Headers

Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582

Response Headers

content-type: application/json; charset=utf-8
status: 200 OK

Response Body

{
  "backups": [
    {
      "id": 7622989,
      "name": "example.com 2014-11-14",
      "distribution": "Ubuntu",
      "slug": null,
      "public": false,
      "regions": [
        "nyc3"
      ],
      "created_at": "2014-11-14T16:07:38Z",
      "type": "snapshot",
      "min_disk_size": 20,
      "size_gigabytes": 2.34
    }
  ],
  "meta": {
    "total": 1
  }
}

List Actions for a Droplet

To retrieve all actions that have been executed on a Droplet, send a GET request to /v2/droplets/$DROPLET_ID/actions.

The results will be returned as a JSON object with an actions key. This will be set to an array filled with action objects containing the standard action attributes:

NameTypeDescription
idintegerA unique numeric ID that can be used to identify and reference an action.
statusstringThe current status of the action. This can be "in-progress", "completed", or "errored".
typestringThis is the type of action that the object represents. For example, this could be "transfer" to represent the state of an image transfer action.
started_atstringA time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_atstringA time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_idintegerA unique identifier for the resource that the action is associated with.
resource_typestringThe type of resource that the action is associated with.
regionobjectA full region object containing information about the region where the action occurred.
region_slugnullable stringA slug representing the region where the action occurred.

List Actions for a Droplet

cURL Example

curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/droplets/3164494/actions?page=1&per_page=1"

Ruby Requirements

require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)

Ruby Example

actions = client.droplets.actions(id: 3164494)
actions.each

Go Requirements

import (
    "context" 
    "github.com/digitalocean/godo" 
)

func main() {
    pat := "mytoken" 

    client := godo.NewFromToken(pat)
    ctx := context.TODO()

    // ...
}

Go Example

opt := &godo.ListOptions{
    Page:    1,
    PerPage: 200,
}

actions, _, err := client.Droplets.Actions(ctx, 3164494, opt)