How to Use the DigitalOcean API

Once you have a personal access token, you can start using the DigitalOcean API v2.0.

Using the API

This page provides some example API requests, using the curl command. This allows us to demonstrate various endpoints in a readable, textual format. For all of the examples, we assign our token to a variable called TOKEN. For example, in Bash, you can use the following command. Make sure to substitute in your own token.

export TOKEN=77e027c7447f468068a7d4fea41e7149a75a94088082c66fcf555de3977f69d3

Note

If you attempt access the API with a token that does not exist, you see the following error message:

{
  "id":"not_found",
  "message":"The resource you were accessing could not be found."
}

Make sure you copy and paste your token correctly.

Example: List all Actions

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

curl -X GET "https://api.digitalocean.com/v2/actions" \
	-H "Authorization: Bearer $TOKEN"

Example: List all Droplets

To list all Droplets in your account, send a GET request to /v2/droplets:

curl -X GET "https://api.digitalocean.com/v2/droplets" \
	-H "Authorization: Bearer $TOKEN"

Example: Create a New Droplet

To create a new Droplet, send a POST request to /v2/droplets. For a full list of attributes that must be set to successfully create a Droplet, see the full documentation. The following example creates an Ubuntu 20.04 Droplet called “My-Droplet” in the NYC3 datacenter, with 1 GB RAM:

curl -X POST "https://api.digitalocean.com/v2/droplets" \
	-d'{"name":"My-Droplet","region":"nyc3","size":"s-1vcpu-1gb","image":"ubuntu-20-04-x64"}' \
	-H "Authorization: Bearer $TOKEN" \
	-H "Content-Type: application/json"

Note: This request, like any other request that makes a change to your account, requires that your token has “write” scope assigned to it.

Example: Create Multiple Droplets

You can also create multiple Droplets with the same attributes using a single API request by sending a POST to /v2/droplets. Instead of providing a single name in the request, provide an array of names. The following example creates two Ubuntu 20.04 Droplets, one called “sub-01.example.com” and one called “sub-02.example.com” They both are in the NYC3 datacenter, with 1 GB RAM:

curl -X POST "https://api.digitalocean.com/v2/droplets" \
	-d'{"names":["sub-01.example.com","sub-02.example.com"],"region":"nyc3","size":"s-1vcpu-1gb","image":"ubuntu-20-04-x64"}' \
	-H "Authorization: Bearer $TOKEN" \
	-H "Content-Type: application/json"

Using Wrappers For the API

There are a variety of wrappers in different languages for the API. Wrappers can be useful for integrating the API into a script or application, and can often be found on GitHub.

Here is an example of using the official DigitalOcean Ruby wrapper, DropletKit. This article demonstrates how to use DropletKit to create and delete a Droplet, but be sure to check the documentation for more functionality.

Ensure that you have RubyGems installed, then use the following command to install DropletKit:

gem install droplet_kit

DropletKit Example: Create a New Droplet

This example demonstrates how to use DropletKit to create an Ubuntu 20.04 Droplet called “My-Droplet” in the NYC3 datacenter, with 1 GB RAM.

Create a new ruby script called create_droplet.rb with the following command:

vi create_droplet.rb

And paste in the following code (replace token in the highlighted line with your personal access token with create permissions for Droplets):

    
        
            
#!/usr/bin/ruby

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

droplet = DropletKit::Droplet.new(name: 'example.com', region: 'nyc3', size: 's-1vcpu-1gb', image: 'ubuntu-20-04-x64')
client.droplets.create(droplet)

        
    

Save and quit by pressing the ESCAPE key, then typing :wq followed by ENTER. Once you’ve exited, run your create script with the following command:

ruby create_droplet.rb

You have initiated the creation of the specified Droplet.

DropletKit Example: Delete a Droplet

This example demonstrates how to use DropletKit to delete a Droplet with the ID 1916711.

Create a new ruby script called delete_droplet.rb with the following command:

vi delete_droplet.rb

And paste in the following code (replace token in the highlighted line with your personal access token with delete permissions for Droplets, and replace the Droplet ID):

    
        
            
#!/usr/bin/ruby

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

client.droplets.delete(id: 1916711)

        
    

Save and quit by pressing the ESCAPE key, then typing :wq followed by ENTER. Now run your delete script with the following command:

ruby delete_droplet.rb

You have initiated the delete action on the specified Droplet.

More Information

• Submit feedback at the APIv2 GitHub Issues page
• What libraries and wrappers are there for DigitalOcean’s APIv2?
• Explore API tutorials and questions on DigitalOcean
• DigitalOcean API v2.0 Documentation
• Available Droplet sizes and images built using the API