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.
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. |
| 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. |
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.
HTTP/1.1 403 Forbidden
{
"id": "forbidden",
"message": "You do not have access for the attempted action."
}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.
{
"droplet": {
"name": "example.com"
. . .
}
}{
"droplets": [
{
"name": "example.com"
. . .
},
{
"name": "second.com"
. . .
}
]
}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": {
"total": 43
}
. . .
}The links object is returned as part of the response body when pagination is enabled. By default, 25 objects are returned per page. If the response contains 25 objects or fewer, no links object will be returned. If the response contains more than 25 objects, the first 25 will be returned along with the links object.
You can request a different pagination limit or force pagination by appending ?per_page= to the request with the number of items you would like per page. For instance, to show only two results per page, you could add ?per_page=2 to the end of your query. The maximum number of results per page is 200.
The links object contains a pages object. The pages object, in turn, contains keys indicating the relationship of additional pages. The values of these are the URLs of the associated pages. The keys will be one of the following:
The pages object will only include the links that make sense. So for the first page of results, no first or prev links will ever be set. This convention holds true in other situations where a link would not make sense.
{
. . .
"links": {
"pages": {
"last": "https://api.digitalocean.com/v2/images?page=2",
"next": "https://api.digitalocean.com/v2/images?page=2"
}
}
. . .
}The number of requests that can be made through the API is currently limited to 5,000 per hour per OAuth token.
The rate limiting information is contained within the response headers of each request. The relevant headers are:
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.
. . .
RateLimit-Limit: 1200
RateLimit-Remaining: 1193
RateLimit-Reset: 1402425459
. . .429 Too Many Requests
{
id: "too_many_requests",
message: "API Rate limit exceeded."
}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 for 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.
export TOKEN=your_token_hereexport DROPLET_ID=1111111In 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.
There are two separate ways to authenticate using OAuth.
The first option is to send a bearer authorization header with your request. This is the preferred method of authenticating because it completes the authorization request in the header portion, away from the actual request.
You can also authenticate using basic authentication. The normal way to do this with a tool like curl is to use the -u flag which is used for passing authentication information.
You then send the username and password combination delimited by a colon character. We only have an OAuth token, so use the OAuth token as the username and leave the password field blank (make sure to include the colon character though).
This is effectively the same as embedding the authentication information within the URI itself.
curl -X $HTTP_METHOD -H "Authorization: Bearer $TOKEN" "https://api.digitalocean.com/v2/$OBJECT"curl -X $HTTP_METHOD -u "$TOKEN:" "https://api.digitalocean.com/v2/$OBJECT"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.
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" curl -H "Authorization: Bearer $TOKEN" \
-X GET \
"https://api.digitalocean.com/v2/images?type=snapshot"
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:
Origin header.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.
curl -I -H "Origin: https://example.com" -X OPTIONS "https://api.digitalocean.com/v2/droplets". . .
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
. . .By sending requests to the /v2/account endpoint, you can retrieve information about your current account.
| Name | Type | Description |
|---|---|---|
| droplet_limit | integer | The total number of Droplets current user or team may have active at one time. |
| floating_ip_limit | integer | The total number of Floating IPs the current user or team may have. |
| string | The email address used by the current user to registered for DigitalOcean. | |
| uuid | string | The unique universal identifier for the current user. |
| email_verified | boolean | If true, the user has verified their account via email. False otherwise. |
| status | string | This value is one of "active", "warning" or "locked". |
| status_message | string | A human-readable message giving more details about the status of the account. |
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:
| Name | Type | Description |
|---|---|---|
| droplet_limit | integer | The total number of Droplets current user or team may have active at one time. |
| floating_ip_limit | integer | The total number of Floating IPs the current user or team may have. |
| string | The email address used by the current user to registered for DigitalOcean. | |
| uuid | string | The unique universal identifier for the current user. |
| email_verified | boolean | If true, the user has verified their account via email. False otherwise. |
| status | string | This value is one of "active", "warning" or "locked". |
| status_message | string | A human-readable message giving more details about the status of the account. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/account"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
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.
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an action. |
| status | string | The current status of the action. This can be "in-progress", "completed", or "errored". |
| type | string | This 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_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
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 25 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:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an action. |
| status | string | The current status of the action. This can be "in-progress", "completed", or "errored". |
| type | string | This 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_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/actions?page=1&per_page=1"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
actions, _, err := client.Actions.List(ctx, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1124
ratelimit-reset: 1415984218{
"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
}
}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:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an action. |
| status | string | The current status of the action. This can be "in-progress", "completed", or "errored". |
| type | string | This 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_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/actions/36804636"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1123
ratelimit-reset: 1415984218{
"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"
}
}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.
| Name | Type | Description |
|---|---|---|
| id | string | The unique identifier for the Block Storage volume. |
| region | object | The 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_ids | array | An 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. |
| name | string | A 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. |
| description | string | An optional free-form text field to describe a Block Storage volume. |
| size_gigabytes | integer | The size of the Block Storage volume in GiB (1024^3). |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Block Storage volume was created. |
| filesystem_type | string | The type of filesystem currently in-use on the volume. |
| filesystem_label | string | The label currently applied to the filesystem. |
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 exmple: /v2/volumes?region=nyc1
| Name | Type | Description |
|---|---|---|
| id | string | The unique identifier for the Block Storage volume. |
| region | object | The 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_ids | array | An 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. |
| name | string | A 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. |
| description | string | An optional free-form text field to describe a Block Storage volume. |
| size_gigabytes | integer | The size of the Block Storage volume in GiB (1024^3). |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Block Storage volume was created. |
| filesystem_type | string | The type of filesystem currently in-use on the volume. |
| filesystem_label | string | The label currently applied to the filesystem. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/volumes?region=nyc1"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
volumes, _, err := client.Storage.ListVolumes(ctx, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833{
"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"
}
],
"links": {
},
"meta": {
"total": 1
}
}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:
| Name | Type | Description | Required |
|---|---|---|---|
| size_gigabytes | integer | The size of the Block Storage volume in GiB (1024^3). | true |
| name | string | A 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 |
| description | string | An optional free-form text field to describe a Block Storage volume. | |
| region | string | The 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. Should not be specified with a snapshot_id. | |
| snapshot_id | string | The unique identifier for the volume snapshot from which to create the volume. Should not be specified with a region_id. | |
| filesystem_type | string | The name of the filesystem type to be used on the volume. When provided, the volume will automatically be formated 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_label | string | The 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. |
The response will be a array called volume containing an object with the standard attributes associated with a volume:
| Name | Type | Description |
|---|---|---|
| id | string | The unique identifier for the Block Storage volume. |
| region | object | The 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_ids | array | An 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. |
| name | string | A 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. |
| description | string | An optional free-form text field to describe a Block Storage volume. |
| size_gigabytes | integer | The size of the Block Storage volume in GiB (1024^3). |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Block Storage volume was created. |
| filesystem_type | string | The type of filesystem currently in-use on the volume. |
| filesystem_label | string | The label currently applied to the filesystem. |
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"}' "https://api.digitalocean.com/v2/volumes"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)volume = DropletKit::Volume.new(
size_gigabytes: 10,
name: 'Example',
description: 'Block store for examples',
region: 'nyc1'
)
client.volumes.create(volume)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()createRequest := &VolumeCreateRequest{
Region: "nyc1",
Name: "example",
Description: "Block store for examples",
SizeGigaBytes: 10,
}
volume, _, err := client.Storage.CreateVolume(ctx, createRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
{
"size_gigabytes": 10,
"name": "example",
"description": "Block store for examples",
"region": "nyc1"
}content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 5000
ratelimit-remaining: 4821
ratelimit-reset: 1444931833{
"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"
}
}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:
| Name | Type | Description |
|---|---|---|
| id | string | The unique identifier for the Block Storage volume. |
| region | object | The 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_ids | array | An 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. |
| name | string | A 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. |
| description | string | An optional free-form text field to describe a Block Storage volume. |
| size_gigabytes | integer | The size of the Block Storage volume in GiB (1024^3). |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Block Storage volume was created. |
| filesystem_type | string | The type of filesystem currently in-use on the volume. |
| filesystem_label | string | The label currently applied to the filesystem. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/volumes/7724db7c-e098-11e5-b522-000f53304e51"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4820
ratelimit-reset: 1444931833{
"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"
}
}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=$DRIVE_NAME®ion=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:
| Name | Type | Description |
|---|---|---|
| id | string | The unique identifier for the Block Storage volume. |
| region | object | The 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_ids | array | An 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. |
| name | string | A 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. |
| description | string | An optional free-form text field to describe a Block Storage volume. |
| size_gigabytes | integer | The size of the Block Storage volume in GiB (1024^3). |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Block Storage volume was created. |
| filesystem_type | string | The type of filesystem currently in-use on the volume. |
| filesystem_label | string | The label currently applied to the filesystem. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/volumes?name=example®ion=nyc1"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4820
ratelimit-reset: 1444931833{
"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"
}
],
"links": {
},
"meta": {
"total": 1
}
}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:
| Name | Type | Description |
|---|---|---|
| id | string | The unique identifier for the snapshot. |
| name | string | A human-readable name for the snapshot. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the snapshot was created. |
| regions | array | An array of the regions that the image is available in. The regions are represented by their identifying slug values. |
| resource_id | string | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| min_disk_size | integer | The minimum size in GB required for a volume or Droplet to use this snapshot. |
| size_gigabytes | integer | The billable size of the snapshot in gigabytes. |
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"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)snapshots = client.volumes.snapshots(id: '82a48a18-873f-11e6-96bf-000f53315a41')
snapshots.eachimport (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
volumes, _, err := client.Storage.ListSnapshots(ctx, '82a48a18-873f-11e6-96bf-000f53315a41', opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4982
ratelimit-reset: 1475263694{
"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
}
}To create a snapshot from a volume, sent a POST request to /v2/volumes/$VOLUME_ID/snapshots.
| Name | Type | Description |
|---|---|---|
| name | string | A human-readable name for the volume snapshot. |
You will get back a JSON object that has a snapshot key. This will contain the standard snapshot attributes:
| Name | Type | Description |
|---|---|---|
| id | string | The unique identifier for the snapshot. |
| name | string | A human-readable name for the snapshot. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the snapshot was created. |
| regions | array | An array of the regions that the image is available in. The regions are represented by their identifying slug values. |
| resource_id | string | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| min_disk_size | integer | The minimum size in GB required for a volume or Droplet to use this snapshot. |
| size_gigabytes | integer | The billable size of the snapshot in gigabytes. |
curl -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582' -d '{"name":"big-data-snapshot1475261774"}' "https://api.digitalocean.com/v2/volumes/82a48a18-873f-11e6-96bf-000f53315a41/snapshots"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)client.volumes.create_snapshot(id: "82a48a18-873f-11e6-96bf-000f53315a41", name: "big-data-snapshot1475261774")import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()snapshot, _, err := client.Storage.CreateSnapshot(ctx, "82a48a18-873f-11e6-96bf-000f53315a41")Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 5000
ratelimit-remaining: 4981
ratelimit-reset: 1475263694{
"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
}
}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.
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/volumes/7724db7c-e098-11e5-b522-000f53304e51"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()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=$DRIVE_NAME®ion=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.
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/volumes?name=example®ion=nyc1"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()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.
curl -X DELETE -H 'Content-Type: application/json' -H 'Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582' "https://api.digitalocean.com/v2/snapshots/fbe805e8-866b-11e6-96bf-000f53315a41"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Block Storage actions are commands that can be given to a DigitalOcean Block Storage volume. An example would be detaching or attaching a volume from a Droplet. These requests are made on the /v2/volumes/$VOLUME_ID/actions endpoint.
An action object is returned. These objects hold the current status of the requested action.
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an action. |
| status | string | The current status of the action. This can be "in-progress", "completed", or "errored". |
| type | string | This 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_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | nullable integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | The region where the resources acted upon are located. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
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.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | This must be "attach" | true |
| droplet_id | integer | The unique identifier for the Droplet the volume will be attached or detached from. | true |
| region | string | The 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:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an action. |
| status | string | The current status of the action. This can be "in-progress", "completed", or "errored". |
| type | string | This 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_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | nullable integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | The region where the resources acted upon are located. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type": "attach", "droplet_id": 11612190, "region": "nyc1"}' "https://api.digitalocean.com/v2/volumes/7724db7c-e098-11e5-b522-000f53304e51/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)client.volume_actions.attach(volume_id:'7724db7c-e098-11e5-b522-000f53304e51', droplet_id: 11612190, region: 'nyc1'import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()action, _, err := client.StorageActions.Attach(ctx, "7724db7c-e098-11e5-b522-000f53304e51", 11612190)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833{
"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"
}
}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 5 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.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | This must be "attach" | true |
| droplet_id | integer | The unique identifier for the Droplet the volume will be attached or detached from. | true |
| volume_name | string | The name of the Block Storage volume. | true |
| region | string | The 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:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an action. |
| status | string | The current status of the action. This can be "in-progress", "completed", or "errored". |
| type | string | This 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_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | nullable integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | The region where the resources acted upon are located. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type": "attach", "volume_name": "example", "region": "nyc1", "droplet_id": "11612190"}' "https://api.digitalocean.com/v2/volumes/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
{
"type": "attach",
"volume_name": "example",
"region": "nyc1",
"droplet_id": "11612190"
}content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833{
"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"
}
}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.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | This must be "detach" | true |
| droplet_id | integer | The unique identifier for the Droplet the volume will be attached or detached from. | true |
| region | string | The 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:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an action. |
| status | string | The current status of the action. This can be "in-progress", "completed", or "errored". |
| type | string | This 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_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | nullable integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | The region where the resources acted upon are located. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
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"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)client.volume_actions.detach(volume_id:'7724db7c-e098-11e5-b522-000f53304e51', droplet_id: 11612190, region: 'nyc1'import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()action, _, err := client.StorageActions.Detach(ctx, "7724db7c-e098-11e5-b522-000f53304e51")Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 5000
ratelimit-remaining: 4816
ratelimit-reset: 1444931833{
"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"
}
}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.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | This must be "detach" | true |
| droplet_id | integer | The unique identifier for the Droplet the volume will be attached or detached from. | true |
| volume_name | string | The name of the Block Storage volume. | true |
| region | string | The 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:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an action. |
| status | string | The current status of the action. This can be "in-progress", "completed", or "errored". |
| type | string | This 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_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | nullable integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | The region where the resources acted upon are located. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
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"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
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.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | This must be "resize" | true |
| size_gigabytes | integer | The new size of the Block Storage volume in GiB (1024^3). | true |
| region | string | The 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:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an action. |
| status | string | The current status of the action. This can be "in-progress", "completed", or "errored". |
| type | string | This 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_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | nullable integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | The region where the resources acted upon are located. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
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"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()action, _, err := client.StorageActions.Resize(ctx, "7724db7c-e098-11e5-b522-000f53304e51", 100, "nyc1")Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 1200
ratelimit-remaining: 1046
ratelimit-reset: 1415984218{
"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"
}
}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:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an action. |
| status | string | The current status of the action. This can be "in-progress", "completed", or "errored". |
| type | string | This 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_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | nullable integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | The region where the resources acted upon are located. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
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"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)actions = client.volume.actions(id: '7724db7c-e098-11e5-b522-000f53304e51')
actions.eachimport (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
actions, _, err := client.StorageActions(ctx, "7724db7c-e098-11e5-b522-000f53304e51", opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 903
ratelimit-reset: 1415984218{
"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
}
}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:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an action. |
| status | string | The current status of the action. This can be "in-progress", "completed", or "errored". |
| type | string | This 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_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | nullable integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | The region where the resources acted upon are located. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
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"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)client.volume.actions.find(volume_id: '7724db7c-e098-11e5-b522-000f53304e51', id: 72531856)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()action, _, err := client.StorageActions.Get(ctx, "7724db7c-e098-11e5-b522-000f53304e51", 72531856)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 837
ratelimit-reset: 1415984218{
"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"
}
}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.
| Name | Type | Description |
|---|---|---|
| id | string | A unique ID that can be used to identify and reference a CDN endpoint. |
| origin | string | The fully qualified domain name (FQDN) for the origin server which the provides the content for the CDN. This is currently restricted to a Space. |
| endpoint | string | The fully qualified domain name (FQDN) from which the CDN-backed content is served. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the CDN endpoint was created. |
| ttl | integer | The amount of time the content is cached by the CDN's edge servers in seconds. |
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.
| Name | Type | Description | Required |
|---|---|---|---|
| origin | string | The 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 |
| ttl | integer | The amount of time the content is cached by the CDN's edge servers in seconds. Defaults to 3600 (one hour) when excluded. |
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:
| Name | Type | Description |
|---|---|---|
| id | string | A unique ID that can be used to identify and reference a CDN endpoint. |
| origin | string | The fully qualified domain name (FQDN) for the origin server which the provides the content for the CDN. This is currently restricted to a Space. |
| endpoint | string | The fully qualified domain name (FQDN) from which the CDN-backed content is served. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the CDN endpoint was created. |
| ttl | integer | The amount of time the content is cached by the CDN's edge servers in seconds. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"origin": "static-images.nyc3.digitaloceanspaces.com","ttl": 3600}' "https://api.digitalocean.com/v2/cdn/endpoints"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
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:
| Name | Type | Description |
|---|---|---|
| id | string | A unique ID that can be used to identify and reference a CDN endpoint. |
| origin | string | The fully qualified domain name (FQDN) for the origin server which the provides the content for the CDN. This is currently restricted to a Space. |
| endpoint | string | The fully qualified domain name (FQDN) from which the CDN-backed content is served. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the CDN endpoint was created. |
| ttl | integer | The amount of time the content is cached by the CDN's edge servers in seconds. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/cdn/endpoints/19f06b6a-3ace-4315-b086-499a0e521b76"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
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:
| Name | Type | Description |
|---|---|---|
| id | string | A unique ID that can be used to identify and reference a CDN endpoint. |
| origin | string | The fully qualified domain name (FQDN) for the origin server which the provides the content for the CDN. This is currently restricted to a Space. |
| endpoint | string | The fully qualified domain name (FQDN) from which the CDN-backed content is served. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the CDN endpoint was created. |
| ttl | integer | The amount of time the content is cached by the CDN's edge servers in seconds. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/cdn/endpoints"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
To update the TTL of an existing CDN endpoint, send a PUT request to /v2/cdn/endpoints/$ENDPOINT_ID.
| Name | Type | Description | Required |
|---|---|---|---|
| ttl | integer | The amount of time the content is cached by the CDN's edge servers in seconds. | true |
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:
| Name | Type | Description |
|---|---|---|
| id | string | A unique ID that can be used to identify and reference a CDN endpoint. |
| origin | string | The fully qualified domain name (FQDN) for the origin server which the provides the content for the CDN. This is currently restricted to a Space. |
| endpoint | string | The fully qualified domain name (FQDN) from which the CDN-backed content is served. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the CDN endpoint was created. |
| ttl | integer | The amount of time the content is cached by the CDN's edge servers in seconds. |
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_command: ""require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
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.
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/cdn/endpoints/19f06b6a-3ace-4315-b086-499a0e521b76"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()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.
| Name | Type | Description | Required |
|---|---|---|---|
| files | array of strings | An 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.
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"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()In order to perform SSL termination on Load Balancers, DigitalOcean offers two types of SSL certificate management:
| Name | Type | Description |
|---|---|---|
| id | string | A unique ID that can be used to identify and reference a certificate. |
| name | string | A unique human-readable name referring to a certificate. |
| not_after | string | A time value given in ISO8601 combined date and time format that represents the certificate's expiration date. |
| sha1_fingerprint | string | A unique identifier generated from the SHA-1 fingerprint of the certificate. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the certificate was created. |
| dns_names | array of strings | An array of fully qualified domain names (FQDNs) for which the certificate was issued. |
| state | string | A string representing the current state of the certificate. It may be "pending", "verified", or "error". |
| type | string | A 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. |
To upload or create a new SSL certificate, 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 should be set to "custom". When generating a certificate using Let's Encrypt, the dns_names attribute must be provided, and the type should be set to "lets_encrypt".
The available attributes and the conditions in which they are required are:
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | A unique human-readable name referring to a certificate. | Always |
| private_key | string | The contents of a PEM-formatted private-key corresponding to the SSL certificate. | Custom |
| leaf_certificate | string | The contents of a PEM-formatted public SSL certificate. | Custom |
| certificate_chain | string | The full PEM-formatted trust chain between the certificate authority's certificate and your domain's SSL certificate. | |
| dns_names | array of strings | An 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 |
| type | string | A 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:
| Name | Type | Description |
|---|---|---|
| id | string | A unique ID that can be used to identify and reference a certificate. |
| name | string | A unique human-readable name referring to a certificate. |
| not_after | string | A time value given in ISO8601 combined date and time format that represents the certificate's expiration date. |
| sha1_fingerprint | string | A unique identifier generated from the SHA-1 fingerprint of the certificate. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the certificate was created. |
| dns_names | array of strings | An array of fully qualified domain names (FQDNs) for which the certificate was issued. |
| state | string | A string representing the current state of the certificate. It may be "pending", "verified", or "error". |
| type | string | A 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. |
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"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)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)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()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)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
{
"name": "web-cert-01",
"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-----"
}content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833{
"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"
}
}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:
| Name | Type | Description |
|---|---|---|
| id | string | A unique ID that can be used to identify and reference a certificate. |
| name | string | A unique human-readable name referring to a certificate. |
| not_after | string | A time value given in ISO8601 combined date and time format that represents the certificate's expiration date. |
| sha1_fingerprint | string | A unique identifier generated from the SHA-1 fingerprint of the certificate. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the certificate was created. |
| dns_names | array of strings | An array of fully qualified domain names (FQDNs) for which the certificate was issued. |
| state | string | A string representing the current state of the certificate. It may be "pending", "verified", or "error". |
| type | string | A 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. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/certificates/892071a0-bb95-49bc-8021-3afd67a210bf"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1123
ratelimit-reset: 1415984218{
"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"
}
}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:
| Name | Type | Description |
|---|---|---|
| id | string | A unique ID that can be used to identify and reference a certificate. |
| name | string | A unique human-readable name referring to a certificate. |
| not_after | string | A time value given in ISO8601 combined date and time format that represents the certificate's expiration date. |
| sha1_fingerprint | string | A unique identifier generated from the SHA-1 fingerprint of the certificate. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the certificate was created. |
| dns_names | array of strings | An array of fully qualified domain names (FQDNs) for which the certificate was issued. |
| state | string | A string representing the current state of the certificate. It may be "pending", "verified", or "error". |
| type | string | A 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. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/certificates"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
certs, _, err := client.Certificates.List(ctx, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4816
ratelimit-reset: 1444931833{
"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
}
}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.
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/certificates/892071a0-bb95-49bc-8021-3afd67a210bf"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()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.
| Name | Type | Description |
|---|---|---|
| name | string | The name of the domain itself. This should follow the standard domain format of domain.TLD. For instance, example.com is a valid domain name. |
| ttl | integer | This 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_file | string | This 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. |
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:
| Name | Type | Description |
|---|---|---|
| name | string | The name of the domain itself. This should follow the standard domain format of domain.TLD. For instance, example.com is a valid domain name. |
| ttl | integer | This 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_file | string | This 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. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/domains"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
domains, _, err := client.Domains.List(ctx, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1115
ratelimit-reset: 1415984218{
"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
}
}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.
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | The 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_address | string | This 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:
| Name | Type | Description |
|---|---|---|
| name | string | The name of the domain itself. This should follow the standard domain format of domain.TLD. For instance, example.com is a valid domain name. |
| ttl | integer | This 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_file | string | This 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.
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"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)domain = DropletKit::Domain.new(
name: 'example.com',
ip_address: '1.2.3.4'
)
client.domains.create(domain)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()createRequest := &godo.DomainCreateRequest{
Name: "example.com",
IPAddress: "1.2.3.4",
}
domain, _, err := client.Domains.Create(ctx, createRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
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:
| Name | Type | Description |
|---|---|---|
| name | string | The name of the domain itself. This should follow the standard domain format of domain.TLD. For instance, example.com is a valid domain name. |
| ttl | integer | This 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_file | string | This 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. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/domains/example.com"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1112
ratelimit-reset: 1415984218{
"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"
}
}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.
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/domains/example.com"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()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. |
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.
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each domain record. |
| type | string | The type of the DNS record. For example: A, CNAME, TXT, ... |
| name | string | The host name, alias, or service being defined by the record. |
| data | string | Variable 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. |
| priority | nullable integer | The priority for SRV and MX records. |
| port | nullable integer | The port for SRV records. |
| ttl | integer | This 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. |
| weight | nullable integer | The weight for SRV records. |
| flags | integer | An unsigned integer between 0-255 used for CAA records. |
| tag | string | The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef" |
To get a listing of all records configured for a domain, send a GET request to /v2/domains/$DOMAIN_NAME/records.
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.
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each domain record. |
| type | string | The type of the DNS record. For example: A, CNAME, TXT, ... |
| name | string | The host name, alias, or service being defined by the record. |
| data | string | Variable 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. |
| priority | nullable integer | The priority for SRV and MX records. |
| port | nullable integer | The port for SRV records. |
| ttl | integer | This 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. |
| weight | nullable integer | The weight for SRV records. |
| flags | integer | An unsigned integer between 0-255 used for CAA records. |
| tag | string | The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef" |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/domains/example.com/records"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 1,
}
records, _, err := client.Domains.Records(ctx, "example.com", opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1121
ratelimit-reset: 1415984218{
"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
}
}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:
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | The record type (A, MX, CNAME, etc). | All Records |
| name | string | The host name, alias, or service being defined by the record. | A, AAAA, CAA, CNAME, TXT, SRV |
| data | string | Variable 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 |
| priority | nullable integer | The priority of the host (for SRV and MX records. null otherwise). | MX, SRV |
| port | nullable integer | The port that the service is accessible on (for SRV records only. null otherwise). | SRV |
| ttl | integer | This 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. If not set, the default value is 1800. | |
| weight | nullable integer | The weight of records with the same priority (for SRV records only. null otherwise). | SRV |
| flags | nullable integer | An unsigned integer between 0-255 used for CAA records. | CAA |
| tag | string | The 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.
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each domain record. |
| type | string | The type of the DNS record. For example: A, CNAME, TXT, ... |
| name | string | The host name, alias, or service being defined by the record. |
| data | string | Variable 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. |
| priority | nullable integer | The priority for SRV and MX records. |
| port | nullable integer | The port for SRV records. |
| ttl | integer | This 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. |
| weight | nullable integer | The weight for SRV records. |
| flags | integer | An unsigned integer between 0-255 used for CAA records. |
| tag | string | The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef" |
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"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)record = DropletKit::DomainRecord.new(
type: 'A',
name: 'www',
data: '162.10.66.0'
)
client.domain_records.create(record, for_domain: 'example.com')import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()createRequest := &godo.DomainRecordEditRequest{
Type: "A",
Name: "www",
Data: "1.2.3.4",
}
domainRecord, _, err := client.Domains.CreateRecord(ctx, "example.com", createRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
{
"type": "A",
"name": "www",
"data": "162.10.66.0",
"priority": null,
"port": null,
"ttl": 1800,
"weight": null,
"flags": null,
"tag": null
}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:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each domain record. |
| type | string | The type of the DNS record. For example: A, CNAME, TXT, ... |
| name | string | The host name, alias, or service being defined by the record. |
| data | string | Variable 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. |
| priority | nullable integer | The priority for SRV and MX records. |
| port | nullable integer | The port for SRV records. |
| ttl | integer | This 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. |
| weight | nullable integer | The weight for SRV records. |
| flags | integer | An unsigned integer between 0-255 used for CAA records. |
| tag | string | The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef" |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/domains/example.com/records/3352896"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
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.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | The record type (A, MX, CNAME, etc). | All Records |
| name | string | The host name, alias, or service being defined by the record. | A, AAAA, CAA, CNAME, TXT, SRV |
| data | string | Variable 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 |
| priority | nullable integer | The priority of the host (for SRV and MX records. null otherwise). | MX, SRV |
| port | nullable integer | The port that the service is accessible on (for SRV records only. null otherwise). | SRV |
| ttl | integer | This 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. If not set, the default value is 1800. | |
| weight | nullable integer | The weight of records with the same priority (for SRV records only. null otherwise). | SRV |
| flags | nullable integer | An unsigned integer between 0-255 used for CAA records. | CAA |
| tag | string | The 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:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each domain record. |
| type | string | The type of the DNS record. For example: A, CNAME, TXT, ... |
| name | string | The host name, alias, or service being defined by the record. |
| data | string | Variable 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. |
| priority | nullable integer | The priority for SRV and MX records. |
| port | nullable integer | The port for SRV records. |
| ttl | integer | This 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. |
| weight | nullable integer | The weight for SRV records. |
| flags | integer | An unsigned integer between 0-255 used for CAA records. |
| tag | string | The parameter tag for CAA records. Valid values are "issue", "issuewild", or "iodef" |
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"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)record = DropletKit::DomainRecord.new(name: 'blog')
client.domain_records.update(record, for_domain: 'example.com', id: 3352896)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()editRequest := &godo.DomainRecordEditRequest{
Type: "A",
Name: "blog",
}
domainRecord, _, err := client.Domains.EditRecord(ctx, "example.com", 3352896, editRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
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.
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/domains/example.com/records/3352896"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()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.
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet instance. This is automatically generated upon Droplet creation. |
| name | string | The human-readable name set for the Droplet instance. |
| memory | integer | Memory of the Droplet in megabytes. |
| vcpus | integer | The number of virtual CPUs. |
| disk | integer | The size of the Droplet's disk in gigabytes. |
| locked | boolean | A boolean value indicating whether the Droplet has been locked, preventing actions by users. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Droplet was created. |
| status | string | A status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive". |
| backup_ids | array | An array of backup IDs of any backups that have been taken of the Droplet instance. Droplet backups are enabled at the time of the instance creation. |
| snapshot_ids | array | An array of snapshot IDs of any snapshots created from the Droplet instance. |
| features | array | An array of features enabled on this Droplet. |
| region | object | The 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. |
| image | object | The 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. |
| size | object | The 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_slug | string | The unique slug identifier for the size of this Droplet. |
| networks | object | The details of the network that are configured for the Droplet instance. This is an object that contains keys for IPv4 and IPv6. The value of each of these is an array that contains objects describing an individual IP resource allocated to the Droplet. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is. |
| kernel | nullable object | The current kernel. This will initially be set to the kernel of the base image when the Droplet is created. |
| next_backup_window | nullable object | The 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. |
| tags | array | An array of Tags the Droplet has been tagged with. |
| volume_ids | array | A flat array including the unique identifier for each Block Storage volume attached to the 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:
| Name | Type | Description | Required |
|---|---|---|---|
| name | String | The 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 |
| region | String | The unique slug identifier for the region that you wish to deploy in. | true |
| size | String | The unique slug identifier for the size that you wish to select for this Droplet. | true |
| image | integer (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_keys | Array | An array containing the IDs or fingerprints of the SSH keys that you wish to embed in the Droplet's root account upon creation. | |
| backups | Boolean | A boolean indicating whether automated backups should be enabled for the Droplet. Automated backups can only be enabled when the Droplet is created. | |
| ipv6 | Boolean | A boolean indicating whether IPv6 is enabled on the Droplet. | |
| private_networking | Boolean | A boolean indicating whether private networking is enabled for the Droplet. Private networking is currently only available in certain regions. | |
| user_data | String | A string containing 'user data' which may be used to configure the Droplet on first boot, often a 'cloud-config' file or Bash script. It must be plain text and may not exceed 64 KiB in size. | |
| monitoring | Boolean | A boolean indicating whether to install the DigitalOcean agent for monitoring. | |
| volumes | Array | A 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. | |
| tags | Array | A flat array of tag names as strings to apply to the Droplet after it is created. Tag names can either be existing or new tags. |
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:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet instance. This is automatically generated upon Droplet creation. |
| name | string | The human-readable name set for the Droplet instance. |
| memory | integer | Memory of the Droplet in megabytes. |
| vcpus | integer | The number of virtual CPUs. |
| disk | integer | The size of the Droplet's disk in gigabytes. |
| locked | boolean | A boolean value indicating whether the Droplet has been locked, preventing actions by users. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Droplet was created. |
| status | string | A status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive". |
| backup_ids | array | An array of backup IDs of any backups that have been taken of the Droplet instance. Droplet backups are enabled at the time of the instance creation. |
| snapshot_ids | array | An array of snapshot IDs of any snapshots created from the Droplet instance. |
| features | array | An array of features enabled on this Droplet. |
| region | object | The 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. |
| image | object | The 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. |
| size | object | The 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_slug | string | The unique slug identifier for the size of this Droplet. |
| networks | object | The details of the network that are configured for the Droplet instance. This is an object that contains keys for IPv4 and IPv6. The value of each of these is an array that contains objects describing an individual IP resource allocated to the Droplet. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is. |
| kernel | nullable object | The current kernel. This will initially be set to the kernel of the base image when the Droplet is created. |
| next_backup_window | nullable object | The 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. |
| tags | array | An array of Tags the Droplet has been tagged with. |
| volume_ids | array | A flat array including the unique identifier for each Block Storage volume attached to the Droplet. |
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":null,"backups":false,"ipv6":true,"user_data":null,"private_networking":null,"volumes": null,"tags":["web"]}' "https://api.digitalocean.com/v2/droplets"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)droplet = DropletKit::Droplet.new(
name: 'example.com',
region: 'nyc3',
size: 's-1vcpu-1gb',
image: 'ubuntu-16-04-x64',
ipv6: true,
tags: ["web"]
)
client.droplets.create(droplet)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()createRequest := &godo.DropletCreateRequest{
Name: "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.Create(ctx, createRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
{
"name": "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,
"volumes": null,
"tags": [
"web"
]
}content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 1200
ratelimit-remaining: 965
ratelimit-reset: 1415984218{
"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"
}
]
}
}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. Up to ten Droplets may be created at a time. The possible fields are:
| Name | Type | Description | Required |
|---|---|---|---|
| names | Array | An array of human human-readable strings you wish to use when displaying the Droplet name. Each name, if set to a domain name managed in the DigitalOcean DNS management system, will configure a PTR record for the Droplet. Each name set during creation will also determine the hostname for the Droplet in its internal configuration. | true |
| region | String | The unique slug identifier for the region that you wish to deploy in. | true |
| size | String | The unique slug identifier for the size that you wish to select for this Droplet. | true |
| image | integer (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_keys | Array | An array containing the IDs or fingerprints of the SSH keys that you wish to embed in the Droplet's root account upon creation. | |
| backups | Boolean | A boolean indicating whether automated backups should be enabled for the Droplet. Automated backups can only be enabled when the Droplet is created. | |
| ipv6 | Boolean | A boolean indicating whether IPv6 is enabled on the Droplet. | |
| private_networking | Boolean | A boolean indicating whether private networking is enabled for the Droplet. Private networking is currently only available in certain regions. | |
| user_data | String | A string containing 'user data' which may be used to configure the Droplet on first boot, often a 'cloud-config' file or Bash script. It must be plain text and may not exceed 64 KiB in size. | |
| monitoring | Boolean | A boolean indicating whether to install the DigitalOcean agent for monitoring. | |
| tags | Array | A flat array of tag names as strings to apply to the Droplet after it is created. Tag names can either be existing or new tags. |
A Droplet will be created for every name you send, using the associated information. The response body will contain a JSON array with a key called droplets. The array will contain JSON objects with standard attributes for your new Droplets:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet instance. This is automatically generated upon Droplet creation. |
| name | string | The human-readable name set for the Droplet instance. |
| memory | integer | Memory of the Droplet in megabytes. |
| vcpus | integer | The number of virtual CPUs. |
| disk | integer | The size of the Droplet's disk in gigabytes. |
| locked | boolean | A boolean value indicating whether the Droplet has been locked, preventing actions by users. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Droplet was created. |
| status | string | A status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive". |
| backup_ids | array | An array of backup IDs of any backups that have been taken of the Droplet instance. Droplet backups are enabled at the time of the instance creation. |
| snapshot_ids | array | An array of snapshot IDs of any snapshots created from the Droplet instance. |
| features | array | An array of features enabled on this Droplet. |
| region | object | The 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. |
| image | object | The 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. |
| size | object | The 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_slug | string | The unique slug identifier for the size of this Droplet. |
| networks | object | The details of the network that are configured for the Droplet instance. This is an object that contains keys for IPv4 and IPv6. The value of each of these is an array that contains objects describing an individual IP resource allocated to the Droplet. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is. |
| kernel | nullable object | The current kernel. This will initially be set to the kernel of the base image when the Droplet is created. |
| next_backup_window | nullable object | The 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. |
| tags | array | An array of Tags the Droplet has been tagged with. |
| volume_ids | array | A flat array including the unique identifier for each Block Storage volume attached to the Droplet. |
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"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)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)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()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)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
{
"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"
]
}content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 1200
ratelimit-remaining: 965
ratelimit-reset: 1415984218{
"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": 36805096,
"rel": "create_multiple",
"href": "https://api.digitalocean.com/v2/actions/36805096"
}
]
}
}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:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet instance. This is automatically generated upon Droplet creation. |
| name | string | The human-readable name set for the Droplet instance. |
| memory | integer | Memory of the Droplet in megabytes. |
| vcpus | integer | The number of virtual CPUs. |
| disk | integer | The size of the Droplet's disk in gigabytes. |
| locked | boolean | A boolean value indicating whether the Droplet has been locked, preventing actions by users. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Droplet was created. |
| status | string | A status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive". |
| backup_ids | array | An array of backup IDs of any backups that have been taken of the Droplet instance. Droplet backups are enabled at the time of the instance creation. |
| snapshot_ids | array | An array of snapshot IDs of any snapshots created from the Droplet instance. |
| features | array | An array of features enabled on this Droplet. |
| region | object | The 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. |
| image | object | The 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. |
| size | object | The 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_slug | string | The unique slug identifier for the size of this Droplet. |
| networks | object | The details of the network that are configured for the Droplet instance. This is an object that contains keys for IPv4 and IPv6. The value of each of these is an array that contains objects describing an individual IP resource allocated to the Droplet. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is. |
| kernel | nullable object | The current kernel. This will initially be set to the kernel of the base image when the Droplet is created. |
| next_backup_window | nullable object | The 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. |
| tags | array | An array of Tags the Droplet has been tagged with. |
| volume_ids | array | A flat array including the unique identifier for each Block Storage volume attached to the Droplet. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/droplets/3164494"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 902
ratelimit-reset: 1415984218{
"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": [
]
}
}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:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet instance. This is automatically generated upon Droplet creation. |
| name | string | The human-readable name set for the Droplet instance. |
| memory | integer | Memory of the Droplet in megabytes. |
| vcpus | integer | The number of virtual CPUs. |
| disk | integer | The size of the Droplet's disk in gigabytes. |
| locked | boolean | A boolean value indicating whether the Droplet has been locked, preventing actions by users. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Droplet was created. |
| status | string | A status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive". |
| backup_ids | array | An array of backup IDs of any backups that have been taken of the Droplet instance. Droplet backups are enabled at the time of the instance creation. |
| snapshot_ids | array | An array of snapshot IDs of any snapshots created from the Droplet instance. |
| features | array | An array of features enabled on this Droplet. |
| region | object | The 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. |
| image | object | The 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. |
| size | object | The 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_slug | string | The unique slug identifier for the size of this Droplet. |
| networks | object | The details of the network that are configured for the Droplet instance. This is an object that contains keys for IPv4 and IPv6. The value of each of these is an array that contains objects describing an individual IP resource allocated to the Droplet. These will define attributes like the IP address, netmask, and gateway of the specific network depending on the type of network it is. |
| kernel | nullable object | The current kernel. This will initially be set to the kernel of the base image when the Droplet is created. |
| next_backup_window | nullable object | The 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. |
| tags | array | An array of Tags the Droplet has been tagged with. |
| volume_ids | array | A flat array including the unique identifier for each Block Storage volume attached to the Droplet. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/droplets?page=1&per_page=1"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
droplets, _, err := client.Droplets.List(ctx, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 947
ratelimit-reset: 1415984218{
"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": [
]
}
],
"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
}
}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.
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/droplets?tag_name=awesome"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
droplets, _, err := client.Droplets.ListByTag(ctx, "awesome"opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/octet-stream
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 901
ratelimit-reset: 1415984218{
"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"
]
}
],
"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
}
}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:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique number used to identify and reference a specific kernel. |
| name | string | The display name of the kernel. This is shown in the web UI and is generally a descriptive title for the kernel in question. |
| version | string | A standard kernel version string representing the version, patch, and release information. |
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"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
kernels, _, err := client.Droplets.Kernels(ctx, 3164494, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 946
ratelimit-reset: 1415984218{
"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
}
}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:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique number used to identify and reference a specific image. |
| name | string | The display name of the image. This is shown in the web UI and is generally a descriptive title for the image in question. |
| type | string | The kind of image, describing the duration of how long the image is stored. This is either "snapshot" or "backup". |
| distribution | string | The base distribution used for this image. |
| slug | nullable string | A 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. |
| public | boolean | A 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. |
| regions | array | An array of the regions that the image is available in. The regions are represented by their identifying slug values. |
| min_disk_size | integer | The minimum 'disk' required for a size to use this image. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Image was created. |
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"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
snapshots, _, err := client.Droplets.Snapshots(ctx, 3164494, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 904
ratelimit-reset: 1415984218{
"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
}
}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:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique number used to identify and reference a specific image. |
| name | string | The display name of the image. This is shown in the web UI and is generally a descriptive title for the image in question. |
| type | string | The kind of image, describing the duration of how long the image is stored. This is either "snapshot" or "backup". |
| distribution | string | The base distribution used for this image. |
| slug | nullable string | A 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. |
| public | boolean | A 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. |
| regions | array | An array of the regions that the image is available in. The regions are represented by their identifying slug values. |
| min_disk_size | integer | The minimum 'disk' required for a size to use this image. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Image was created. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/droplets/3067509/backups"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
backups, _, err := client.Droplets.Backups(ctx, 3164494, opt)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:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an action. |
| status | string | The current status of the action. This can be "in-progress", "completed", or "errored". |
| type | string | This 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_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
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"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
actions, _, err := client.Droplets.Actions(ctx, 3164494, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 903
ratelimit-reset: 1415984218{
"actions": [
{
"id": 36805187,
"status": "completed",
"type": "snapshot",
"started_at": "2014-11-14T16:37:34Z",
"completed_at": "2014-11-14T16:39:32Z",
"resource_id": 3164494,
"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/droplets/3164494/actions?page=3&per_page=1",
"next": "https://api.digitalocean.com/v2/droplets/3164494/actions?page=2&per_page=1"
}
},
"meta": {
"total": 3
}
}To delete a Droplet, send a DELETE request to /v2/droplets/$DROPLET_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.
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/droplets/3164494"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()To delete Droplets by a tag (for example awesome), send a DELETE request to /v2/droplets?tag_name=$TAG_NAME.
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.
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/droplets?tag_name=awesome"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()To retrieve a list of Droplets that are running on the same physical server, send a GET request to /v2/droplets/$DROPLET_ID/neighbors
The results will be returned as a JSON object with a key of droplets. This will be set to an array containing objects representing any other Droplets that share the same physical hardware.
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/droplets/3164494/neighbors"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 903
ratelimit-reset: 1415984218{
"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
}
}
]
}To retrieve a list of any Droplets that are running on the same physical hardware, send a GET request to /v2/reports/droplet_neighbors
The results will be returned as a JSON object with a key of neighbors. This will be set to an array containing more arrays, one for each set of Droplets that share a physical server.
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/reports/droplet_neighbors"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 903
ratelimit-reset: 1415984218{
"neighbors": [
[
{
"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
}
}
]
]
}Droplet actions are tasks that can be executed on a Droplet. These can be things like rebooting, resizing, snapshotting, etc.
Droplet action requests are generally targeted at one of the "actions" endpoints for a specific Droplet. The specific actions are usually initiated by sending a POST request with the action and arguments as parameters.
Droplet action requests create a Droplet actions object, which can be used to get information about the status of an action. Creating a Droplet action is asynchronous: the HTTP call will return the action object before the action has finished processing on the Droplet. The current status of an action can be retrieved from either the Droplet actions endpoint or the global actions endpoint. If a Droplet action is uncompleted it may block the creation of a subsequent action for that Droplet, the locked attribute of the Droplet will be true and attempts to create a Droplet action will fail with a status of 422.
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet action event. This is used to reference a specific action that was requested. |
| status | string | The current status of the action. The value of this attribute will be "in-progress", "completed", or "errored". |
| type | string | The type of action that the event is executing (reboot, power_off, etc.). |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
To enable backups on an existing Droplet send a POST request to /v2/droplets/$DROPLET_ID/actions. Set the "type" attribute to enable_backups.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | Must be enable_backups | true |
The response will be a JSON object with a key called action. The value will be a Droplet actions object:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet action event. This is used to reference a specific action that was requested. |
| status | string | The current status of the action. The value of this attribute will be "in-progress", "completed", or "errored". |
| type | string | The type of action that the event is executing (reboot, power_off, etc.). |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"enable_backups"}' "https://api.digitalocean.com/v2/droplets/3164450/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 1200
ratelimit-remaining: 1099
ratelimit-reset: 1415984218{
"action": {
"id": 36804745,
"status": "in-progress",
"type": "enable_backups",
"started_at": "2014-11-14T16:30:56Z",
"completed_at": null,
"resource_id": 3164450,
"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"
}
}To disable backups on an existing Droplet send a POST request to /v2/droplets/$DROPLET_ID/actions. Set the "type" attribute to disable_backups.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | Must be disable_backups | true |
The response will be a JSON object with a key called action. The value will be a Droplet actions object:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet action event. This is used to reference a specific action that was requested. |
| status | string | The current status of the action. The value of this attribute will be "in-progress", "completed", or "errored". |
| type | string | The type of action that the event is executing (reboot, power_off, etc.). |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"disable_backups"}' "https://api.digitalocean.com/v2/droplets/3164450/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 1200
ratelimit-remaining: 1099
ratelimit-reset: 1415984218{
"action": {
"id": 36804745,
"status": "in-progress",
"type": "disable_backups",
"started_at": "2014-11-14T16:30:56Z",
"completed_at": null,
"resource_id": 3164450,
"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"
}
}To reboot a Droplet, send a POST request to /v2/droplets/$DROPLET_ID/actions. Set the "type" attribute to reboot.
A reboot action is an attempt to reboot the Droplet in a graceful way, similar to using the reboot command from the console.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | Must be reboot | true |
The response will be a JSON object with a key called action. The value will be a Droplet actions object:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet action event. This is used to reference a specific action that was requested. |
| status | string | The current status of the action. The value of this attribute will be "in-progress", "completed", or "errored". |
| type | string | The type of action that the event is executing (reboot, power_off, etc.). |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"reboot"}' "https://api.digitalocean.com/v2/droplets/3164450/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 1200
ratelimit-remaining: 1097
ratelimit-reset: 1415984218{
"action": {
"id": 36804748,
"status": "in-progress",
"type": "reboot",
"started_at": "2014-11-14T16:31:00Z",
"completed_at": null,
"resource_id": 3164450,
"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"
}
}To power cycle a Droplet (power off and then back on), send a POST request to /v2/droplets/$DROPLET_ID/actions. Set the "type" attribute to power_cycle.
A powercycle action is similar to pushing the reset button on a physical machine, it's similar to booting from scratch.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | Must be power_cycle | true |
The response will be a JSON object with a key called action. The value will be a Droplet actions object:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet action event. This is used to reference a specific action that was requested. |
| status | string | The current status of the action. The value of this attribute will be "in-progress", "completed", or "errored". |
| type | string | The type of action that the event is executing (reboot, power_off, etc.). |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"power_cycle"}' "https://api.digitalocean.com/v2/droplets/3164450/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 1200
ratelimit-remaining: 1095
ratelimit-reset: 1415984218{
"action": {
"id": 36804749,
"status": "in-progress",
"type": "power_cycle",
"started_at": "2014-11-14T16:31:03Z",
"completed_at": null,
"resource_id": 3164450,
"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"
}
}To shutdown a Droplet, send a POST request to /v2/droplets/$DROPLET_ID/actions. Set the "type" attribute to shutdown.
A shutdown action is an attempt to shutdown the Droplet in a graceful way, similar to using the shutdown command from the console. Since a shutdown command can fail, this action guarantees that the command is issued, not that it succeeds. The preferred way to turn off a Droplet is to attempt a shutdown, with a reasonable timeout, followed by a power off action to ensure the Droplet is off.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | Must be shutdown | true |
The response will be a JSON object with a key called action. The value will be a Droplet actions object:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet action event. This is used to reference a specific action that was requested. |
| status | string | The current status of the action. The value of this attribute will be "in-progress", "completed", or "errored". |
| type | string | The type of action that the event is executing (reboot, power_off, etc.). |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"shutdown"}' "https://api.digitalocean.com/v2/droplets/3067649/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
{
"action": {
"id": 36077293,
"status": "in-progress",
"type": "shutdown",
"started_at": "2014-11-04T17:08:03Z",
"completed_at": null,
"resource_id": 3067649,
"resource_type": "droplet",
"region": {
"name": "New York 2",
"slug": "nyc2",
"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": "nyc2"
}
}To power off a Droplet, send a POST request to /v2/droplets/$DROPLET_ID/actions. Set the "type" attribute to power_off.
A power_off event is a hard shutdown and should only be used if the shutdown action is not successful. It is similar to cutting the power on a server and could lead to complications.
The request should contain the following attributes:
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | Must be power_off | true |
The response will be a JSON object with a key called action. The value will be a Droplet actions object:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet action event. This is used to reference a specific action that was requested. |
| status | string | The current status of the action. The value of this attribute will be "in-progress", "completed", or "errored". |
| type | string | The type of action that the event is executing (reboot, power_off, etc.). |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"power_off"}' "https://api.digitalocean.com/v2/droplets/3164450/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 1200
ratelimit-remaining: 1093
ratelimit-reset: 1415984218{
"action": {
"id": 36804751,
"status": "in-progress",
"type": "power_off",
"started_at": "2014-11-14T16:31:07Z",
"completed_at": null,
"resource_id": 3164450,
"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"
}
}To power on a Droplet, send a POST request to /v2/droplets/$DROPLET_ID/actions. Set the "type" attribute to power_on.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | Must be power_on | true |
The response will be a JSON object with a key called action. The value will be a Droplet actions object:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet action event. This is used to reference a specific action that was requested. |
| status | string | The current status of the action. The value of this attribute will be "in-progress", "completed", or "errored". |
| type | string | The type of action that the event is executing (reboot, power_off, etc.). |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"power_on"}' "https://api.digitalocean.com/v2/droplets/3164450/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 1200
ratelimit-remaining: 1088
ratelimit-reset: 1415984218{
"action": {
"id": 36804758,
"status": "in-progress",
"type": "power_on",
"started_at": "2014-11-14T16:31:19Z",
"completed_at": null,
"resource_id": 3164450,
"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"
}
}To restore a Droplet, send a POST request to /v2/droplets/$DROPLET_ID/actions. Set the "type" attribute to restore and the "image" attribute to an image ID.
A Droplet restoration will rebuild an image using a backup image. The image ID that is passed in must be a backup of the current Droplet instance. The operation will leave any embedded SSH keys intact.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | Must be restore | true |
| image | string if an image slug. integer if an image ID. | An image slug or ID. This represents the image that the Droplet will use as a base. | true |
The response will be a JSON object with a key called action. The value will be a Droplet actions object:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet action event. This is used to reference a specific action that was requested. |
| status | string | The current status of the action. The value of this attribute will be "in-progress", "completed", or "errored". |
| type | string | The type of action that the event is executing (reboot, power_off, etc.). |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"restore", "image": 12389723 }' "https://api.digitalocean.com/v2/droplets/3067649/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
{
"action": {
"id": 36077293,
"status": "in-progress",
"type": "restore",
"started_at": "2014-11-04T17:08:03Z",
"completed_at": null,
"resource_id": 3067649,
"resource_type": "droplet",
"region": {
"name": "New York 2",
"slug": "nyc2",
"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": "nyc2"
}
}To reset the password for a Droplet, send a POST request to /v2/droplets/$DROPLET_ID/actions. Set the "type" attribute to password_reset.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | Must be password_reset | true |
The response will be a JSON object with a key called action. The value will be a Droplet actions object:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet action event. This is used to reference a specific action that was requested. |
| status | string | The current status of the action. The value of this attribute will be "in-progress", "completed", or "errored". |
| type | string | The type of action that the event is executing (reboot, power_off, etc.). |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"password_reset"}' "https://api.digitalocean.com/v2/droplets/3164450/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 1200
ratelimit-remaining: 1085
ratelimit-reset: 1415984218{
"action": {
"id": 36804760,
"status": "in-progress",
"type": "password_reset",
"started_at": "2014-11-14T16:31:25Z",
"completed_at": null,
"resource_id": 3164450,
"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"
}
}To resize a Droplet, send a POST request to /v2/droplets/$DROPLET_ID/actions. Set the "type" attribute to resize and the "size" attribute to a sizes slug. If a permanent resize, with disk changes included, is desired, set the "disk" attribute to true.
The Droplet must be powered off prior to resizing.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | Must be resize | true |
| disk | Boolean | Whether to increase disk size | |
| size | string | The size slug that you want to resize to. | true |
The response will be a JSON object with a key called action. The value will be a Droplet actions object:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet action event. This is used to reference a specific action that was requested. |
| status | string | The current status of the action. The value of this attribute will be "in-progress", "completed", or "errored". |
| type | string | The type of action that the event is executing (reboot, power_off, etc.). |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"resize","size":"1gb"}' "https://api.digitalocean.com/v2/droplets/3164450/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 1200
ratelimit-remaining: 1046
ratelimit-reset: 1415984218{
"action": {
"id": 36804888,
"status": "in-progress",
"type": "resize",
"started_at": "2014-11-14T16:33:17Z",
"completed_at": null,
"resource_id": 3164450,
"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"
}
}To rebuild a Droplet, send a POST request to /v2/droplets/$DROPLET_ID/actions. Set the "type" attribute to rebuild and the "image" attribute to an image ID or slug.
A rebuild action functions just like a new create.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | Must be rebuild | true |
| image | string if an image slug. integer if an image ID. | An image slug or ID. This represents the image that the Droplet will use as a base. | true |
The response will be a JSON object with a key called action. The value will be a Droplet actions object:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet action event. This is used to reference a specific action that was requested. |
| status | string | The current status of the action. The value of this attribute will be "in-progress", "completed", or "errored". |
| type | string | The type of action that the event is executing (reboot, power_off, etc.). |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"rebuild","image":"ubuntu-16-04-x64"}' "https://api.digitalocean.com/v2/droplets/3164450/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()action, _, err := client.DropletActions.RebuildByImageSlug(ctx, 3164450, "ubuntu-16-04-x64")Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 1200
ratelimit-remaining: 1043
ratelimit-reset: 1415984218{
"action": {
"id": 36804899,
"status": "in-progress",
"type": "rebuild",
"started_at": "2014-11-14T16:33:23Z",
"completed_at": null,
"resource_id": 3164450,
"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"
}
}To rename a Droplet, send a POST request to /v2/droplets/$DROPLET_ID/actions. Set the "type" attribute to rename and the "name" attribute to the new name for the Droplet.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | Must be rename | true |
| name | string | The new name for the Droplet. | true |
The response will be a JSON object with a key called action. The value will be a Droplet actions object:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet action event. This is used to reference a specific action that was requested. |
| status | string | The current status of the action. The value of this attribute will be "in-progress", "completed", or "errored". |
| type | string | The type of action that the event is executing (reboot, power_off, etc.). |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"rename","name":"nifty-new-name"}' "https://api.digitalocean.com/v2/droplets/3164450/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 1200
ratelimit-remaining: 1025
ratelimit-reset: 1415984218{
"action": {
"id": 36804946,
"status": "in-progress",
"type": "rename",
"started_at": "2014-11-14T16:34:16Z",
"completed_at": null,
"resource_id": 3164450,
"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"
}
}To change the kernel of a Droplet, send a POST request to /v2/droplets/$DROPLET_ID/actions. Set the "type" attribute to change_kernel and the "kernel" attribute to the new kernel's ID.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | Must be change_kernel | true |
| kernel | integer | A unique number used to identify and reference a specific kernel. | true |
The response will be a JSON object with a key called action. The value will be a Droplet actions object:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet action event. This is used to reference a specific action that was requested. |
| status | string | The current status of the action. The value of this attribute will be "in-progress", "completed", or "errored". |
| type | string | The type of action that the event is executing (reboot, power_off, etc.). |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"change_kernel","kernel":991}' "https://api.digitalocean.com/v2/droplets/3164450/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 1200
ratelimit-remaining: 1016
ratelimit-reset: 1415984218{
"action": {
"id": 36804951,
"status": "in-progress",
"type": "change_kernel",
"started_at": "2014-11-14T16:34:20Z",
"completed_at": null,
"resource_id": 3164450,
"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"
}
}To enable IPv6 networking on an existing Droplet (within a region that has IPv6 available), send a POST request to /v2/droplets/$DROPLET_ID/actions. Set the "type" attribute to enable_ipv6.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | Must be enable_ipv6 | true |
The response will be a JSON object with a key called action. The value will be a Droplet actions object:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet action event. This is used to reference a specific action that was requested. |
| status | string | The current status of the action. The value of this attribute will be "in-progress", "completed", or "errored". |
| type | string | The type of action that the event is executing (reboot, power_off, etc.). |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"enable_ipv6"}' "https://api.digitalocean.com/v2/droplets/3164450/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 1200
ratelimit-remaining: 1014
ratelimit-reset: 1415984218{
"action": {
"id": 36804954,
"status": "in-progress",
"type": "enable_ipv6",
"started_at": "2014-11-14T16:34:24Z",
"completed_at": null,
"resource_id": 3164450,
"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"
}
}To enable private networking on an existing Droplet (within a region that has private networking available), send a POST request to /v2/droplets/$DROPLET_ID/actions. Set the "type" attribute to enable_private_networking.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | Must be enable_private_networking | true |
The response will be a JSON object with a key called action. The value will be a Droplet actions object:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet action event. This is used to reference a specific action that was requested. |
| status | string | The current status of the action. The value of this attribute will be "in-progress", "completed", or "errored". |
| type | string | The type of action that the event is executing (reboot, power_off, etc.). |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"enable_private_networking"}' "https://api.digitalocean.com/v2/droplets/3164450/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 1200
ratelimit-remaining: 1008
ratelimit-reset: 1415984218{
"action": {
"id": 36805001,
"status": "in-progress",
"type": "enable_private_networking",
"started_at": "2014-11-14T16:34:36Z",
"completed_at": null,
"resource_id": 3164450,
"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"
}
}To snapshot a Droplet, send a POST request to /v2/droplets/$DROPLET_ID/actions. Set the "type" attribute to snapshot and the "name" attribute to the name you would like to give the created image.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | Must be snapshot | true |
| name | string | The name to give the new snapshot |
The response will be a JSON object with a key called action. The value will be a Droplet actions object:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet action event. This is used to reference a specific action that was requested. |
| status | string | The current status of the action. The value of this attribute will be "in-progress", "completed", or "errored". |
| type | string | The type of action that the event is executing (reboot, power_off, etc.). |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"snapshot","name":"Nifty New Snapshot"}' "https://api.digitalocean.com/v2/droplets/3164450/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 1200
ratelimit-remaining: 1006
ratelimit-reset: 1415984218{
"action": {
"id": 36805022,
"status": "in-progress",
"type": "snapshot",
"started_at": "2014-11-14T16:34:39Z",
"completed_at": null,
"resource_id": 3164450,
"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"
}
}Some actions can be performed in bulk on tagged Droplets. The actions can be initiated by sending a POST to /v2/droplets/actions?tag_name=$TAG_NAME with the action arguments.
The list of supported action types are:
power_cyclepower_onpower_offshutdownenable_private_networkingenable_ipv6enable_backupsdisable_backupssnapshotThe response will be a JSON object with a key called actions. The value will be an array of Droplet actions objects:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet action event. This is used to reference a specific action that was requested. |
| status | string | The current status of the action. The value of this attribute will be "in-progress", "completed", or "errored". |
| type | string | The type of action that the event is executing (reboot, power_off, etc.). |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"enable_backups"}' "https://api.digitalocean.com/v2/droplets/actions?tag_name=awesome"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 1200
ratelimit-remaining: 1099
ratelimit-reset: 1415984218{
"actions": [
{
"id": 36077293,
"status": "in-progress",
"type": "shutdown",
"started_at": "2014-11-04T17:08:03Z",
"completed_at": null,
"resource_id": 3067649,
"resource_type": "droplet",
"region": {
"name": "New York 2",
"slug": "nyc2",
"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"
},
{
"id": 36077294,
"status": "in-progress",
"type": "shutdown",
"started_at": "2014-11-04T17:08:03Z",
"completed_at": null,
"resource_id": 3067650,
"resource_type": "droplet",
"region": {
"name": "New York 2",
"slug": "nyc2",
"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"
}
]
}To retrieve a Droplet action, send a GET request to /v2/droplets/$DROPLET_ID/actions/$ACTION_ID.
The response will be a JSON object with a key called action. The value will be a Droplet actions object:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique identifier for each Droplet action event. This is used to reference a specific action that was requested. |
| status | string | The current status of the action. The value of this attribute will be "in-progress", "completed", or "errored". |
| type | string | The type of action that the event is executing (reboot, power_off, etc.). |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/droplets/3164444/actions/36804807"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 966
ratelimit-reset: 1415984218{
"action": {
"id": 36804807,
"status": "completed",
"type": "backup",
"started_at": "2014-11-14T16:32:24Z",
"completed_at": "2014-11-14T16:34:15Z",
"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"
}
}Floating IP objects represent a publicly-accessible static IP addresses that can be mapped to one of your Droplets. They can be used to create highly available setups or other configurations requiring movable addresses.
Floating IPs are bound to a specific region.
| Name | Type | Description |
|---|---|---|
| ip | string | The public IP address of the Floating IP. It also serves as its identifier. |
| region | object | The region that the Floating IP is reserved to. When you query a Floating IP, the entire region object will be returned. |
| droplet | object | The Droplet that the Floating IP has been assigned to. When you query a Floating IP, if it is assigned to a Droplet, the entire Droplet object will be returned. If it is not assigned, the value will be null. |
To list all of the Floating IPs available on your account, send a GET request to /v2/floating_ips.
The response will be a JSON object with a key called floating_ips. This will be set to an array of Floating IP objects, each of which will contain the standard Floating IP attributes:
| Name | Type | Description |
|---|---|---|
| ip | string | The public IP address of the Floating IP. It also serves as its identifier. |
| region | object | The region that the Floating IP is reserved to. When you query a Floating IP, the entire region object will be returned. |
| droplet | object | The Droplet that the Floating IP has been assigned to. When you query a Floating IP, if it is assigned to a Droplet, the entire Droplet object will be returned. If it is not assigned, the value will be null. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/floating_ips?page=1&per_page=20"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
floatingIPs, _, err := client.FloatingIPs.List(ctx, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833{
"floating_ips": [
{
"ip": "45.55.96.47",
"droplet": null,
"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": [
"private_networking",
"backups",
"ipv6",
"metadata"
],
"available": true
},
"locked": false
}
],
"links": {
},
"meta": {
"total": 1
}
}On creation, a Floating IP must be either assigned to a Droplet or reserved to a region. To create a new Floating IP assigned to a Droplet, send a POST request to /v2/floating_ips with the "droplet_id" attribute.
| Name | Type | Description | Required |
|---|---|---|---|
| droplet_id | integer | The ID of Droplet that the Floating IP will be assigned to. | true |
The response will be a JSON object with a key called floating_ip. The value of this will be an object that contains the standard attributes associated with a Floating IP:
| Name | Type | Description |
|---|---|---|
| ip | string | The public IP address of the Floating IP. It also serves as its identifier. |
| region | object | The region that the Floating IP is reserved to. When you query a Floating IP, the entire region object will be returned. |
| droplet | object | The Droplet that the Floating IP has been assigned to. When you query a Floating IP, if it is assigned to a Droplet, the entire Droplet object will be returned. If it is not assigned, the value will be null. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"droplet_id": 123456}' "https://api.digitalocean.com/v2/floating_ips"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)floating_ip = DropletKit::FloatingIp.new(droplet_id: 123456)
client.floating_ips.create(floating_ip)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()createRequest := &godo.FloatingIPCreateRequest{
DropletID: 123456,
}
floatingIP, _, err := client.FloatingIPs.Create(ctx, createRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 5000
ratelimit-remaining: 4821
ratelimit-reset: 1444931833{
"floating_ip": {
"ip": "45.55.96.47",
"droplet": null,
"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": [
"private_networking",
"backups",
"ipv6",
"metadata"
],
"available": true
},
"locked": false
},
"links": {
}
}On creation, a Floating IP must be either assigned to a Droplet or reserved to a region. To create a Floating IP reserved to a Region, send a POST request to /v2/floating_ips with the "region" attribute.
| Name | Type | Description | Required |
|---|---|---|---|
| region | string | The slug identifier for the region the Floating IP will be reserved to. | true |
The response will be a JSON object with a key called floating_ip. The value of this will be an object that contains the standard attributes associated with a Floating IP:
| Name | Type | Description |
|---|---|---|
| ip | string | The public IP address of the Floating IP. It also serves as its identifier. |
| region | object | The region that the Floating IP is reserved to. When you query a Floating IP, the entire region object will be returned. |
| droplet | object | The Droplet that the Floating IP has been assigned to. When you query a Floating IP, if it is assigned to a Droplet, the entire Droplet object will be returned. If it is not assigned, the value will be null. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"region":"nyc3"}' "https://api.digitalocean.com/v2/floating_ips"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)floating_ip = DropletKit::FloatingIp.new(region: 'nyc3')
client.floating_ips.create(floating_ip)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()createRequest := &godo.FloatingIPCreateRequest{
Region: "nyc3",
}
floatingIP, _, err := client.FloatingIPs.Create(ctx, createRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 5000
ratelimit-remaining: 4821
ratelimit-reset: 1444931833{
"floating_ip": {
"ip": "45.55.96.47",
"droplet": null,
"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": [
"private_networking",
"backups",
"ipv6",
"metadata"
],
"available": true
},
"locked": false
},
"links": {
}
}To show information about a Floating IP, send a GET request to /v2/floating_ips/$FLOATING_IP_ADDR.
The response will be a JSON object with a key called floating_ip. The value of this will be an object that contains the standard attributes associated with a Floating IP:
| Name | Type | Description |
|---|---|---|
| ip | string | The public IP address of the Floating IP. It also serves as its identifier. |
| region | object | The region that the Floating IP is reserved to. When you query a Floating IP, the entire region object will be returned. |
| droplet | object | The Droplet that the Floating IP has been assigned to. When you query a Floating IP, if it is assigned to a Droplet, the entire Droplet object will be returned. If it is not assigned, the value will be null. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/floating_ips/45.55.96.47"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4820
ratelimit-reset: 1444931833{
"floating_ip": {
"ip": "45.55.96.47",
"droplet": null,
"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": [
"private_networking",
"backups",
"ipv6",
"metadata"
],
"available": true
},
"locked": false
}
}To delete a Floating IP and remove it from your account, send a DELETE request to /v2/floating_ips/$FLOATING_IP_ADDR.
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.
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/floating_ips/45.55.96.47"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Floating IP actions are commands that can be given to a DigitalOcean Floating IP. These requests are made on the actions endpoint of a specific Floating IP.
An action object is returned. These objects hold the current status of the requested action.
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an action. |
| status | string | The current status of the action. This can be "in-progress", "completed", or "errored". |
| type | string | This is the type of action that the object represents. For example, this could be "assign_ip" to represent the state of a Floating IP assign action. |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
To assign a Floating IP to a Droplet, send a POST request to /v2/floating_ips/$FLOATING_IP_ADDR/actions. Set the "type" attribute to assign and the "droplet_id" attribute to the Droplet's ID.
The response will be a JSON object with a key called action. The value will be an action object:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an action. |
| status | string | The current status of the action. This can be "in-progress", "completed", or "errored". |
| type | string | This is the type of action that the object represents. For example, this could be "assign_ip" to represent the state of a Floating IP assign action. |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"assign","droplet_id":8219222}' "https://api.digitalocean.com/v2/floating_ips/45.55.96.47/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 5000
ratelimit-remaining: 4819
ratelimit-reset: 1444931833{
"action": {
"id": 68212728,
"status": "in-progress",
"type": "assign_ip",
"started_at": "2015-10-15T17:45:44Z",
"completed_at": null,
"resource_id": 758603823,
"resource_type": "floating_ip",
"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": [
"private_networking",
"backups",
"ipv6",
"metadata"
],
"available": true
},
"region_slug": "nyc3"
}
}To unassign a Floating IP, send a POST request to /v2/floating_ips/$FLOATING_IP_ADDR/actions. Set the "type" attribute to unassign. The Floating IP will be reserved in the region but not assigned to a Droplet.
The response will be a JSON object with a key called action. The value will be an action object:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an action. |
| status | string | The current status of the action. This can be "in-progress", "completed", or "errored". |
| type | string | This is the type of action that the object represents. For example, this could be "assign_ip" to represent the state of a Floating IP assign action. |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"unassign"}' "https://api.digitalocean.com/v2/floating_ips/45.55.96.47/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 5000
ratelimit-remaining: 4816
ratelimit-reset: 1444931833{
"action": {
"id": 68212773,
"status": "in-progress",
"type": "unassign_ip",
"started_at": "2015-10-15T17:46:15Z",
"completed_at": null,
"resource_id": 758603823,
"resource_type": "floating_ip",
"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": [
"private_networking",
"backups",
"ipv6",
"metadata"
],
"available": true
},
"region_slug": "nyc3"
}
}To retrieve all actions that have been executed on a Floating IP, send a GET request to /v2/floating_ips/$FLOATING_IP/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 Floating IP action attributes:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an action. |
| status | string | The current status of the action. This can be "in-progress", "completed", or "errored". |
| type | string | This is the type of action that the object represents. For example, this could be "assign_ip" to represent the state of a Floating IP assign action. |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/floating_ips/45.55.96.47/actions?page=1&per_page=1"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
actions, _, err := client.FloatingIPActions.List(ctx, '45.55.96.47', opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 903
ratelimit-reset: 1415984218{
"actions": [
{
"id": 72531856,
"status": "completed",
"type": "reserve_ip",
"started_at": "2015-11-21T21:51:09Z",
"completed_at": "2015-11-21T21:51:09Z",
"resource_id": 758604197,
"resource_type": "floating_ip",
"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": [
"private_networking",
"backups",
"ipv6",
"metadata"
],
"available": true
},
"region_slug": "nyc3"
}
],
"links": {
},
"meta": {
"total": 1
}
}To retrieve the status of a Floating IP action, send a GET request to /v2/floating_ips/$FLOATING_IP/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 Floating IP action attributes:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an action. |
| status | string | The current status of the action. This can be "in-progress", "completed", or "errored". |
| type | string | This is the type of action that the object represents. For example, this could be "assign_ip" to represent the state of a Floating IP assign action. |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/floating_ips/45.55.96.47/actions/72531856"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 837
ratelimit-reset: 1415984218{
"action": {
"id": 72531856,
"status": "completed",
"type": "assign_ip",
"started_at": "2015-11-12T17:51:03Z",
"completed_at": "2015-11-12T17:51:14Z",
"resource_id": 758604968,
"resource_type": "floating_ip",
"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": [
"private_networking",
"backups",
"ipv6",
"metadata"
],
"available": true
},
"region_slug": "nyc3"
}
}Cloud Firewalls provide the ability to restrict network access to and from a Droplet allowing you to define which ports will accept inbound or outbound connections. By sending requests to the /v2/firewalls endpoint, you can list, create, or delete Firewalls as well as modify access rules.
| Name | Type | Description |
|---|---|---|
| id | string | A unique ID that can be used to identify and reference a Firewall. |
| status | string | A status string indicating the current state of the Firewall. This can be "waiting", "succeeded", or "failed". |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Firewall was created. |
| pending_changes | array of objects | An array of objects each containing the fields "droplet_id", "removing", and "status". It is provided to detail exactly which Droplets are having their security policies updated. When empty, all changes have been successfully applied. |
| name | string | A human-readable name for a Firewall. |
| inbound_rules | array of objects | An object specifying the inbound access rules for a Firewall (see table below). |
| outbound_rules | array of objects | An object specifying the outbound access rules for a Firewall (see table below). |
| droplet_ids | array of integers | An array containing the IDs of the Droplets assigned to the Firewall. |
| tags | array of strings | An array containing the names of the Tags assigned to the Firewall. |
A Firewall's inbound_rules and outbound_rules attributes will have arrays of objects as their values. These objects will contain the standard attributes of their associated types which can be found below.
Inbound access rules specify the protocol (TCP, UDP, or ICMP), ports, and sources for inbound traffic that will be allowed through the Firewall to the target Droplets. The ports attribute may contain a single port, a range of ports (e.g. "8000-9000"), or "all" to allow traffic on all ports for the specified protocol. The sources attribute will contain an object specifying a whitelist of sources from which traffic will be accepted.
| Name | Type | Description |
|---|---|---|
| protocol | string | The type of traffic to be allowed. This may be one of "tcp", "udp", or "icmp". |
| ports | string | The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "all" to open all ports for a protocol. |
| sources | object | An object specifying locations from which inbound traffic will be accepted. (See below for the available keys and the types.) |
Outbound access rules are simular to the inbound rules and specify the protocol (TCP, UDP, or ICMP), ports, and sources for outbound traffic that will be allowed through the Firewall to the specified destinations. Instead of a sources attribute, outbound rules will contain a destinations attribute. It contains an object specifying a whitelist of destinations to which traffic will be allowed.
| Name | Type | Description |
|---|---|---|
| protocol | string | The type of traffic to be allowed. This may be one of "tcp", "udp", or "icmp". |
| ports | string | The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "all" to open all ports for a protocol. |
| destinations | object | An object specifying locations to which outbound traffic that will be allowed. (See below for the available keys and the types.) |
Both an inbound rule's sources attribute and an outbound rule's destinations attribute may specify individual Droplets, Load Balancers, individual IP addresses, IP ranges in CIDR notation, and/or sets of Droplets by using Tags. The available keys and the types for their values are:
| Name | Type | Description |
|---|---|---|
| addresses | array of strings | An array of strings containing the IPv4 addresses, IPv6 addresses, IPv4 CIDRs, and/or IPv6 CIDRs to which the Firewall will allow traffic. |
| droplet_ids | array of integers | An array containing the IDs of the Droplets to which the Firewall will allow traffic. |
| load_balancer_uids | array of strings | An array containing the IDs of the Load Balancers to which the Firewall will allow traffic. |
| tags | array of strings | An array containing the names of Tags corresponding to groups of Droplets to which the Firewall will allow traffic. |
To create a new Cloud Firewall, send a POST request to /v2/firewalls. The attribute values that must be set to successfully create a Firewall are:
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | A human-readable name for a Firewall. | true |
| inbound_rules | array of objects | An object specifying the inbound access rules for a Firewall (see table below). | true |
| outbound_rules | array of objects | An object specifying the outbound access rules for a Firewall (see table below). | true |
| droplet_ids | array of integers | An array containing the IDs of the Droplets to be assigned to the Firewall. | |
| tags | array of strings | An array containing the names of the Tags to be assigned to the Firewall. |
The request must contain at least one inbound or outbound access rule. A Firewall's inbound_rules attribute is made up of an array of objects with the following attributes:
| Name | Type | Description | Required |
|---|---|---|---|
| protocol | string | The type of traffic to be allowed. This may be one of "tcp", "udp", or "icmp". | true |
| ports | string | The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "all" to open all ports for a protocol. | true |
| sources | object | An object specifying locations from which inbound traffic will be accepted. (See below for the available keys and the types.) | true |
Similarly, a Firewall's outbound_rules attribute is made up of an array of objects with the following attributes:
| Name | Type | Description | Required |
|---|---|---|---|
| protocol | string | The type of traffic to be allowed. This may be one of "tcp", "udp", or "icmp". | true |
| ports | string | The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "all" to open all ports for a protocol. | true |
| destinations | object | An object specifying locations to which outbound traffic that will be allowed. (See below for the available keys and the types.) | true |
Within these rules, the sources and destinations attributes may specify individual Droplets, Load Balancers, individual IP addresses, IP ranges in CIDR notation, and/or sets of Droplets by using Tags. The available keys and the types for their values are:
| Name | Type | Description |
|---|---|---|
| addresses | array of strings | An array of strings containing the IPv4 addresses, IPv6 addresses, IPv4 CIDRs, and/or IPv6 CIDRs to which the Firewall will allow traffic. |
| droplet_ids | array of integers | An array containing the IDs of the Droplets to which the Firewall will allow traffic. |
| load_balancer_uids | array of strings | An array containing the IDs of the Load Balancers to which the Firewall will allow traffic. |
| tags | array of strings | An array containing the names of Tags corresponding to groups of Droplets to which the Firewall will allow traffic. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name":"firewall","inbound_rules":[{"protocol":"tcp","ports":"22","sources":{"addresses":["0.0.0.0/0","::/0"]}}],"inbound_rules":[{"protocol":"tcp","ports":"80","sources":{"load_balancer_uids": ["4de7ac8b-495b-4884-9a69-1050c6793cd6"]}},{"protocol": "tcp","ports": 22,"sources":{"tags": ["gateway"],"addresses": ["18.0.0.0/8"]}}],"outbound_rules":[{"protocol":"tcp","ports":"80","destinations":{"addresses":["0.0.0.0/0","::/0"]}}],"droplet_ids":[8043964],"tags":null}' "https://api.digitalocean.com/v2/firewalls"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)firewall = DropletKit::Firewall.new(
name: 'firewall',
inbound_rules: [
DropletKit::FirewallInboundRule.new(
protocol: 'tcp',
ports: '80',
sources: {
load_balancer_uids: ['4de7ac8b-495b-4884-9a69-1050c6793cd6']
}
),
DropletKit::FirewallInboundRule.new(
protocol: 'tcp',
ports: '22',
sources: {
tags: ['gateway'],
addresses: ['18.0.0.0/8']
}
)
],
outbound_rules: [
DropletKit::FirewallOutboundRule.new(
protocol: 'tcp',
ports: '80',
destinations: {
addresses: ['0.0.0.0/0', '::/0'],
}
)
],
droplet_ids: [8043964]
)
client.firewalls.create(firewall)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()createRequest := &godo.FirewallRequest{
Name: 'firewall',
InboundRules: []godo.InboundRule{
{
Protocol: 'tcp',
PortRange: '80',
Sources: &godo.Sources{
LoadBalancerUIDs: []string{'4de7ac8b-495b-4884-9a69-1050c6793cd6'},
},
},
{
Protocol: 'tcp',
PortRange: '22',
Sources: &godo.Sources{
Addresses: []string{'18.0.0.0/8'},
Tags: []string{'gateway'},
},
},
},
OutboundRules: []godo.OutboundRule{
{
Protocol: 'tcp',
PortRange: '80',
Destinations: &godo.Destinations{
Addresses: []string{'0.0.0.0/0', '::/0'},
},
},
},
DropletIDs: []int{8043964},
}
firewall, req, err := client.Firewalls.Create(ctx, createRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
{
"name": "firewall",
"inbound_rules": [
{
"protocol": "tcp",
"ports": "80",
"sources": {
"load_balancer_uids": [
"4de7ac8b-495b-4884-9a69-1050c6793cd6"
]
}
},
{
"protocol": "tcp",
"ports": 22,
"sources": {
"tags": [
"gateway"
],
"addresses": [
"18.0.0.0/8"
]
}
}
],
"outbound_rules": [
{
"protocol": "tcp",
"ports": "80",
"destinations": {
"addresses": [
"0.0.0.0/0",
"::/0"
]
}
}
],
"droplet_ids": [
8043964
],
"tags": null
}content-type: application/json; charset=utf-8
content-length: 419
ratelimit-limit: 5000
ratelimit-remaining: 4983
ratelimit-reset: 1495574766{
"firewall": {
"id": "bb4b2611-3d72-467b-8602-280330ecd65c",
"name": "firewall",
"status": "waiting",
"inbound_rules": [
{
"protocol": "tcp",
"ports": "80",
"sources": {
"load_balancer_uids": [
"4de7ac8b-495b-4884-9a69-1050c6793cd6"
]
}
},
{
"protocol": "tcp",
"ports": 22,
"sources": {
"tags": [
"gateway"
],
"addresses": [
"18.0.0.0/8"
]
}
}
],
"outbound_rules": [
{
"protocol": "tcp",
"ports": "80",
"destinations": {
"addresses": [
"0.0.0.0/0",
"::/0"
]
}
}
],
"created_at": "2017-05-23T21:24:00Z",
"droplet_ids": [
8043964
],
"tags": [
],
"pending_changes": [
{
"droplet_id": 8043964,
"removing": false,
"status": "waiting"
}
]
}
}To show information about an existing Cloud Firewall, send a GET request to /v2/firewalls/$FIREWALL_ID.
The response will be a JSON object with a firewall key. This will be set to an object containing the standard Firewall attributes:
| Name | Type | Description |
|---|---|---|
| id | string | A unique ID that can be used to identify and reference a Firewall. |
| status | string | A status string indicating the current state of the Firewall. This can be "waiting", "succeeded", or "failed". |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Firewall was created. |
| pending_changes | array of objects | An array of objects each containing the fields "droplet_id", "removing", and "status". It is provided to detail exactly which Droplets are having their security policies updated. When empty, all changes have been successfully applied. |
| name | string | A human-readable name for a Firewall. |
| inbound_rules | array of objects | An object specifying the inbound access rules for a Firewall (see table below). |
| outbound_rules | array of objects | An object specifying the outbound access rules for a Firewall (see table below). |
| droplet_ids | array of integers | An array containing the IDs of the Droplets assigned to the Firewall. |
| tags | array of strings | An array containing the names of the Tags assigned to the Firewall. |
The inbound_rules attribute will contain an array of objects with the following attributes:
| Name | Type | Description |
|---|---|---|
| protocol | string | The type of traffic to be allowed. This may be one of "tcp", "udp", or "icmp". |
| ports | string | The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "all" to open all ports for a protocol. |
| sources | object | An object specifying locations from which inbound traffic will be accepted. (See below for the available keys and the types.) |
The outbound_rules attribute will contain an array of objects with the following attributes:
| Name | Type | Description |
|---|---|---|
| protocol | string | The type of traffic to be allowed. This may be one of "tcp", "udp", or "icmp". |
| ports | string | The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "all" to open all ports for a protocol. |
| destinations | object | An object specifying locations to which outbound traffic that will be allowed. (See below for the available keys and the types.) |
Both an inbound rule's sources attribute and an outbound rule's destinations may contain the following keys:
| Name | Type | Description |
|---|---|---|
| addresses | array of strings | An array of strings containing the IPv4 addresses, IPv6 addresses, IPv4 CIDRs, and/or IPv6 CIDRs to which the Firewall will allow traffic. |
| droplet_ids | array of integers | An array containing the IDs of the Droplets to which the Firewall will allow traffic. |
| load_balancer_uids | array of strings | An array containing the IDs of the Load Balancers to which the Firewall will allow traffic. |
| tags | array of strings | An array containing the names of Tags corresponding to groups of Droplets to which the Firewall will allow traffic. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
ratelimit-limit: 5000
ratelimit-remaining: 4982
ratelimit-reset: 1495574766{
"firewall": {
"id": "bb4b2611-3d72-467b-8602-280330ecd65c",
"name": "firewall",
"status": "succeeded",
"inbound_rules": [
{
"protocol": "tcp",
"ports": "80",
"sources": {
"load_balancer_uids": [
"4de7ac8b-495b-4884-9a69-1050c6793cd6"
]
}
},
{
"protocol": "tcp",
"ports": 22,
"sources": {
"tags": [
"gateway"
],
"addresses": [
"18.0.0.0/8"
]
}
}
],
"outbound_rules": [
{
"protocol": "tcp",
"ports": "80",
"destinations": {
"addresses": [
"0.0.0.0/0",
"::/0"
]
}
}
],
"created_at": "2017-05-23T21:24:00Z",
"droplet_ids": [
8043964
],
"tags": [
],
"pending_changes": [
]
}
}To list all of the Cloud Firewalls available on your account, send a GET request to /v2/firewalls.
The response will be a JSON object with a key called firewalls. This will be set to an array of Firewall objects, each of which will contain the standard Firewall attributes:
| Name | Type | Description |
|---|---|---|
| id | string | A unique ID that can be used to identify and reference a Firewall. |
| status | string | A status string indicating the current state of the Firewall. This can be "waiting", "succeeded", or "failed". |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Firewall was created. |
| pending_changes | array of objects | An array of objects each containing the fields "droplet_id", "removing", and "status". It is provided to detail exactly which Droplets are having their security policies updated. When empty, all changes have been successfully applied. |
| name | string | A human-readable name for a Firewall. |
| inbound_rules | array of objects | An object specifying the inbound access rules for a Firewall (see table below). |
| outbound_rules | array of objects | An object specifying the outbound access rules for a Firewall (see table below). |
| droplet_ids | array of integers | An array containing the IDs of the Droplets assigned to the Firewall. |
| tags | array of strings | An array containing the names of the Tags assigned to the Firewall. |
The inbound_rules attribute will contain an array of objects with the following attributes:
| Name | Type | Description |
|---|---|---|
| protocol | string | The type of traffic to be allowed. This may be one of "tcp", "udp", or "icmp". |
| ports | string | The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "all" to open all ports for a protocol. |
| sources | object | An object specifying locations from which inbound traffic will be accepted. (See below for the available keys and the types.) |
The outbound_rules attribute will contain an array of objects with the following attributes:
| Name | Type | Description |
|---|---|---|
| protocol | string | The type of traffic to be allowed. This may be one of "tcp", "udp", or "icmp". |
| ports | string | The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "all" to open all ports for a protocol. |
| destinations | object | An object specifying locations to which outbound traffic that will be allowed. (See below for the available keys and the types.) |
Both an inbound rule's sources attribute and an outbound rule's destinations may contain the following keys:
| Name | Type | Description |
|---|---|---|
| addresses | array of strings | An array of strings containing the IPv4 addresses, IPv6 addresses, IPv4 CIDRs, and/or IPv6 CIDRs to which the Firewall will allow traffic. |
| droplet_ids | array of integers | An array containing the IDs of the Droplets to which the Firewall will allow traffic. |
| load_balancer_uids | array of strings | An array containing the IDs of the Load Balancers to which the Firewall will allow traffic. |
| tags | array of strings | An array containing the names of Tags corresponding to groups of Droplets to which the Firewall will allow traffic. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/firewalls"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
firewalls, _, err := client.Firewalls.List(ctx, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
ratelimit-limit: 5000
ratelimit-remaining: 4985
ratelimit-reset: 1495574766{
"firewalls": [
{
"id": "fb6045f1-cf1d-4ca3-bfac-18832663025b",
"name": "firewall",
"status": "succeeded",
"inbound_rules": [
{
"protocol": "tcp",
"ports": "80",
"sources": {
"load_balancer_uids": [
"4de7ac8b-495b-4884-9a69-1050c6793cd6"
]
}
},
{
"protocol": "tcp",
"ports": 22,
"sources": {
"tags": [
"gateway"
],
"addresses": [
"18.0.0.0/8"
]
}
}
],
"outbound_rules": [
{
"protocol": "tcp",
"ports": "80",
"destinations": {
"addresses": [
"0.0.0.0/0",
"::/0"
]
}
}
],
"created_at": "2017-05-23T21:23:59Z",
"droplet_ids": [
8043964
],
"tags": [
],
"pending_changes": [
]
}
],
"links": {
},
"meta": {
"total": 1
}
}To update the configuration of an existing Cloud Firewall, send a PUT request to /v2/firewalls/$FIREWALL_ID. The request should contain a full representation of the Firewall including existing attributes. Note that any attributes that are not provided will be reset to their default values.
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | A human-readable name for a Firewall. | true |
| inbound_rules | array of objects | An object specifying the inbound access rules for a Firewall (see table below). | true |
| outbound_rules | array of objects | An object specifying the outbound access rules for a Firewall (see table below). | true |
| droplet_ids | array of integers | An array containing the IDs of the Droplets to be assigned to the Firewall. | |
| tags | array of strings | An array containing the names of the Tags to be assigned to the Firewall. |
The request must contain at least one inbound or outbound access rule. A Firewall's inbound_rules attribute is made up of an array of objects with the following attributes:
| Name | Type | Description | Required |
|---|---|---|---|
| protocol | string | The type of traffic to be allowed. This may be one of "tcp", "udp", or "icmp". | true |
| ports | string | The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "all" to open all ports for a protocol. | true |
| sources | object | An object specifying locations from which inbound traffic will be accepted. (See below for the available keys and the types.) | true |
Similarly, a Firewall's outbound_rules attribute is made up of an array of objects with the following attributes:
| Name | Type | Description | Required |
|---|---|---|---|
| protocol | string | The type of traffic to be allowed. This may be one of "tcp", "udp", or "icmp". | true |
| ports | string | The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "all" to open all ports for a protocol. | true |
| destinations | object | An object specifying locations to which outbound traffic that will be allowed. (See below for the available keys and the types.) | true |
Within these rules, the sources and destinations attributes may specify individual Droplets, Load Balancers, individual IP addresses, IP ranges in CIDR notation, and/or sets of Droplets by using Tags. The available keys and the types for their values are:
| Name | Type | Description |
|---|---|---|
| addresses | array of strings | An array of strings containing the IPv4 addresses, IPv6 addresses, IPv4 CIDRs, and/or IPv6 CIDRs to which the Firewall will allow traffic. |
| droplet_ids | array of integers | An array containing the IDs of the Droplets to which the Firewall will allow traffic. |
| load_balancer_uids | array of strings | An array containing the IDs of the Load Balancers to which the Firewall will allow traffic. |
| tags | array of strings | An array containing the names of Tags corresponding to groups of Droplets to which the Firewall will allow traffic. |
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name":"firewall","inbound_rules":[{"protocol":"tcp","ports":"8080","sources":{"load_balancer_uids": ["4de7ac8b-495b-4884-9a69-1050c6793cd6"]}},{"protocol": "tcp","ports": 22,"sources":{"tags": ["gateway"],"addresses": ["18.0.0.0/8"]}}],"outbound_rules":[{"protocol":"tcp","ports":"8080","destinations":{"addresses":["0.0.0.0/0","::/0"]}}],"droplet_ids":[8043964],"tags":["frontend"]}' "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)firewall = DropletKit::Firewall.new(
name: 'firewall',
inbound_rules: [
DropletKit::FirewallInboundRule.new(
protocol: 'tcp',
ports: '8080',
sources: {
load_balancer_uids: ['4de7ac8b-495b-4884-9a69-1050c6793cd6']
}
),
DropletKit::FirewallInboundRule.new(
protocol: 'tcp',
ports: '22',
sources: {
tags: ['gateway'],
addresses: ['18.0.0.0/8']
}
)
],
outbound_rules: [
DropletKit::FirewallOutboundRule.new(
protocol: 'tcp',
ports: '8080',
destinations: {
addresses: ['0.0.0.0/0', '::/0'],
}
)
],
droplet_ids: [8043964],
tags: ['frontend']
)
client.firewalls.update(firewall, id: 'bb4b2611-3d72-467b-8602-280330ecd65c')import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()updateRequest := &godo.FirewallRequest{
Name: 'firewall',
InboundRules: []godo.InboundRule{
{
Protocol: 'tcp',
PortRange: '8080',
Sources: &godo.Sources{
LoadBalancerUIDs: []string{'4de7ac8b-495b-4884-9a69-1050c6793cd6'},
},
},
{
Protocol: 'tcp',
PortRange: '22',
Sources: &godo.Sources{
Addresses: []string{'18.0.0.0/8'},
Tags: []string{'gateway'},
},
},
},
OutboundRules: []godo.OutboundRule{
{
Protocol: 'tcp',
PortRange: '8080',
Destinations: &godo.Destinations{
Addresses: []string{'0.0.0.0/0', '::/0'},
},
},
},
DropletIDs: []int{8043964},
Tags: []string{'frontend'}
}
firewall, req, err := client.Firewalls.Create(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', updateRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
{
"name": "firewall",
"inbound_rules": [
{
"protocol": "tcp",
"ports": "8080",
"sources": {
"load_balancer_uids": [
"4de7ac8b-495b-4884-9a69-1050c6793cd6"
]
}
},
{
"protocol": "tcp",
"ports": 22,
"sources": {
"tags": [
"gateway"
],
"addresses": [
"18.0.0.0/8"
]
}
}
],
"outbound_rules": [
{
"protocol": "tcp",
"ports": "8080",
"destinations": {
"addresses": [
"0.0.0.0/0",
"::/0"
]
}
}
],
"droplet_ids": [
8043964
],
"tags": [
"frontend"
]
}content-type: application/json; charset=utf-8
content-length: 419
ratelimit-limit: 5000
ratelimit-remaining: 4983
ratelimit-reset: 1495574766{
"firewall": {
"id": "bb4b2611-3d72-467b-8602-280330ecd65c",
"name": "firewall",
"status": "waiting",
"inbound_rules": [
{
"protocol": "tcp",
"ports": "80",
"sources": {
"load_balancer_uids": [
"4de7ac8b-495b-4884-9a69-1050c6793cd6"
]
}
},
{
"protocol": "tcp",
"ports": 22,
"sources": {
"tags": [
"gateway"
],
"addresses": [
"18.0.0.0/8"
]
}
}
],
"outbound_rules": [
{
"protocol": "tcp",
"ports": "80",
"destinations": {
"addresses": [
"0.0.0.0/0",
"::/0"
]
}
}
],
"created_at": "2017-05-23T21:24:00Z",
"droplet_ids": [
8043964
],
"tags": [
],
"pending_changes": [
{
"droplet_id": 8043964,
"removing": false,
"status": "waiting"
}
]
}
}To delete a Cloud Firewall send a DELETE request to /v2/firewalls/$FIREWALL_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.
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()To assign a Droplet to a Cloud Firewall, send a POST request to /v2/firewalls/$FIREWALL_ID/droplets. In the body of the request, there should be a "droplet_ids" attribute containing a list of Droplet IDs.
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.
| Name | Type | Description | Required |
|---|---|---|---|
| droplet_ids | array of integers | An array containing the IDs of the Droplets to be assigned to the Firewall. | true |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"droplet_ids":[49696269]}' "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c/droplets"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()_, err := client.Firewalls.AddDroplets(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', 49696269)To remove a Droplet from a Cloud Firewall, send a DELETE request to /v2/firewalls/$FIREWALL_ID/droplets. In the body of the request, there should be a "droplet_ids" attribute containing a list of Droplet IDs.
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.
| Name | Type | Description | Required |
|---|---|---|---|
| droplet_ids | array of integers | An array containing the IDs of the Droplets to be removed from the Firewall. | true |
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"droplet_ids":[49696269]}' "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c/droplets"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)client.firewalls.remove_droplets([49696269], id: 'bb4b2611-3d72-467b-8602-280330ecd65c')import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()_, err := client.Firewalls.RemoveDroplets(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', 49696269)To assign a Tag representing a group of Droplets to a Cloud Firewall, send a POST request to /v2/firewalls/$FIREWALL_ID/tags. In the body of the request, there should be a "tags" attribute containing a list of Tag names.
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.
| Name | Type | Description | Required |
|---|---|---|---|
| tags | array of strings | An array containing the names of the Tags to be assigned to the Firewall. | true |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"tags":["frontend"]}' "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c/tags"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()_, err := client.Firewalls.AddTags(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', 'frontend')To remove a Tag representing a group of Droplets from a Cloud Firewall, send a DELETE request to /v2/firewalls/$FIREWALL_ID/tags. In the body of the request, there should be a "tags" attribute containing a list of Tag names.
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.
| Name | Type | Description | Required |
|---|---|---|---|
| tags | array of strings | An array containing the names of the Tags to be removed from the Firewall. | true |
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"tags":["frontend"]}' "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c/tags"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()_, err := client.Firewalls.RemoveTags(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', 'frontend')To add additional access rules to a Cloud Firewall, send a POST request to /v2/firewalls/$FIREWALL_ID/rules. The body of the request may include an inbound_rules and/or outbound_rules attribute containing an array of rules to be added.
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.
An object specifying an inbound access rule should contain:
| Name | Type | Description | Required |
|---|---|---|---|
| protocol | string | The type of traffic to be allowed. This may be one of "tcp", "udp", or "icmp". | true |
| ports | string | The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "all" to open all ports for a protocol. | true |
| sources | object | An object specifying locations from which inbound traffic will be accepted. (See below for the available keys and the types.) | true |
An object specifying an outbound access rule should contain:
| Name | Type | Description | Required |
|---|---|---|---|
| protocol | string | The type of traffic to be allowed. This may be one of "tcp", "udp", or "icmp". | true |
| ports | string | The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "all" to open all ports for a protocol. | true |
| destinations | object | An object specifying locations to which outbound traffic that will be allowed. (See below for the available keys and the types.) | true |
Both an inbound rule's sources attribute and an outbound rule's destinations attribute may contain any of the following keys:
| Name | Type | Description |
|---|---|---|
| addresses | array of strings | An array of strings containing the IPv4 addresses, IPv6 addresses, IPv4 CIDRs, and/or IPv6 CIDRs to which the Firewall will allow traffic. |
| droplet_ids | array of integers | An array containing the IDs of the Droplets to which the Firewall will allow traffic. |
| load_balancer_uids | array of strings | An array containing the IDs of the Load Balancers to which the Firewall will allow traffic. |
| tags | array of strings | An array containing the names of Tags corresponding to groups of Droplets to which the Firewall will allow traffic. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"inbound_rules":[{"protocol":"tcp","ports":"3306","sources":{"droplet_ids":[49696269]}}],"outbound_rules":[{"protocol":"tcp","ports":"3306","destinations":{"droplet_ids":[49696269]}}]}' "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c/rules"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)inbound_rule = DropletKit::FirewallInboundRule.new(
protocol: 'tcp',
ports: '3306',
sources: {
droplet_ids: [49696269]
}
)
outbound_rule = DropletKit::FirewallOutboundRule.new(
protocol: 'tcp',
ports: '3306',
destinations: {
droplet_ids: [49696269]
}
)
client.firewalls.add_rules(inbound_rules: [inbound_rule], outbound_rules: [outbound_rule], id: 'bb4b2611-3d72-467b-8602-280330ecd65c')import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()ruleRequest := &godo.FirewallRulesRequest{
InboundRules: []godo.InboundRule{
{
Protocol: 'tcp',
PortRange: '3306',
Sources: &godo.Sources{
DropletIDs: []int{49696269},
},
},
},
OutboundRules: []godo.OutboundRule{
{
Protocol: 'tcp',
PortRange: '3306',
Destinations: &godo.Destinations{
DropletIDs: []int{49696269},
},
},
},
}
_, err := c.Firewalls.AddRules(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', ruleRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
To remove access rules from a Cloud Firewall, send a DELETE request to /v2/firewalls/$FIREWALL_ID/rules. The body of the request may include an inbound_rules and/or outbound_rules attribute containing an array of rules to be removed.
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.
An object specifying an inbound access rule should contain:
| Name | Type | Description | Required |
|---|---|---|---|
| protocol | string | The type of traffic to be allowed. This may be one of "tcp", "udp", or "icmp". | true |
| ports | string | The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "all" to open all ports for a protocol. | true |
| sources | object | An object specifying locations from which inbound traffic will be accepted. (See below for the available keys and the types.) | true |
An object specifying an outbound access rule should contain:
| Name | Type | Description | Required |
|---|---|---|---|
| protocol | string | The type of traffic to be allowed. This may be one of "tcp", "udp", or "icmp". | true |
| ports | string | The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "all" to open all ports for a protocol. | true |
| destinations | object | An object specifying locations to which outbound traffic that will be allowed. (See below for the available keys and the types.) | true |
Both an inbound rule's sources attribute and an outbound rule's destinations attribute may contain any of the following keys:
| Name | Type | Description |
|---|---|---|
| addresses | array of strings | An array of strings containing the IPv4 addresses, IPv6 addresses, IPv4 CIDRs, and/or IPv6 CIDRs to which the Firewall will allow traffic. |
| droplet_ids | array of integers | An array containing the IDs of the Droplets to which the Firewall will allow traffic. |
| load_balancer_uids | array of strings | An array containing the IDs of the Load Balancers to which the Firewall will allow traffic. |
| tags | array of strings | An array containing the names of Tags corresponding to groups of Droplets to which the Firewall will allow traffic. |
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"inbound_rules":[{"protocol":"tcp","ports":"3306","sources":{"droplet_ids":[49696269]}}],"outbound_rules":[{"protocol":"tcp","ports":"3306","destinations":{"droplet_ids":[49696269]}}]}' "https://api.digitalocean.com/v2/firewalls/bb4b2611-3d72-467b-8602-280330ecd65c/rules"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)inbound_rule = DropletKit::FirewallInboundRule.new(
protocol: 'tcp',
ports: '3306',
sources: {
droplet_ids: [49696269]
}
)
outbound_rule = DropletKit::FirewallOutboundRule.new(
protocol: 'tcp',
ports: '3306',
destinations: {
droplet_ids: [49696269]
}
)
client.firewalls.remove_rules(inbound_rules: [inbound_rule], outbound_rules: [outbound_rule], id: 'bb4b2611-3d72-467b-8602-280330ecd65c')import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()ruleRequest := &godo.FirewallRulesRequest{
InboundRules: []godo.InboundRule{
{
Protocol: 'tcp',
PortRange: '3306',
Sources: &godo.Sources{
DropletIDs: []int{49696269},
},
},
},
OutboundRules: []godo.OutboundRule{
{
Protocol: 'tcp',
PortRange: '3306',
Destinations: &godo.Destinations{
DropletIDs: []int{49696269},
},
},
},
}
_, err := c.Firewalls.RemoveRules(ctx, 'bb4b2611-3d72-467b-8602-280330ecd65c', ruleRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
A DigitalOcean image can be used to create a Droplet and may come in a number of flavors. Currently, there are five types of images: snapshots, backups, applications, distributions, and custom images.
To interact with images, you will generally send requests to the images endpoint at /v2/images.
| Name | Type | Description |
|---|---|---|
| id | integer | A unique number that can be used to identify and reference a specific image. |
| name | string | The display name that has been given to an image. This is what is shown in the control panel and is generally a descriptive title for the image in question. |
| type | string | The kind of image, describing the duration of how long the image is stored. This is either "snapshot", "backup", or "custom". |
| distribution | string | This attribute describes the base distribution used for this image. For custom images, this is user defined. |
| slug | nullable string | A 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. |
| public | boolean | This is a boolean value that indicates whether the image in question is public or not. An image that is public is available to all accounts. A non-public image is only accessible from your account. |
| regions | array | This attribute is an array of the regions that the image is available in. The regions are represented by their identifying slug values. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the image was created. |
| min_disk_size | integer | The minimum disk size in GB required for a Droplet to use this image. |
| size_gigabytes | integer | The size of the image in gigabytes. |
| description | string | An optional free-form text field to describe an image. |
| tags | array | An array containing the names of the tags the image has been tagged with. |
| status | string | A status string indicating the state of a custom image. This may be "NEW", "available", "pending", or "deleted". |
| error_message | string | A string containing information about errors that may occur when importing a custom image. |
To list all of the images available on your account, send a GET request to /v2/images.
The response will be a JSON object with a key called images. This will be set to an array of image objects, each of which will contain the standard image attributes:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique number that can be used to identify and reference a specific image. |
| name | string | The display name that has been given to an image. This is what is shown in the control panel and is generally a descriptive title for the image in question. |
| type | string | The kind of image, describing the duration of how long the image is stored. This is either "snapshot", "backup", or "custom". |
| distribution | string | This attribute describes the base distribution used for this image. For custom images, this is user defined. |
| slug | nullable string | A 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. |
| public | boolean | This is a boolean value that indicates whether the image in question is public or not. An image that is public is available to all accounts. A non-public image is only accessible from your account. |
| regions | array | This attribute is an array of the regions that the image is available in. The regions are represented by their identifying slug values. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the image was created. |
| min_disk_size | integer | The minimum disk size in GB required for a Droplet to use this image. |
| size_gigabytes | integer | The size of the image in gigabytes. |
| description | string | An optional free-form text field to describe an image. |
| tags | array | An array containing the names of the tags the image has been tagged with. |
| status | string | A status string indicating the state of a custom image. This may be "NEW", "available", "pending", or "deleted". |
| error_message | string | A string containing information about errors that may occur when importing a custom image. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/images?page=1&per_page=1"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
images, _, err := client.Images.List(ctx, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 777
ratelimit-reset: 1415984218{
"images": [
{
"id": 7555620,
"name": "Nifty New Snapshot",
"distribution": "Ubuntu",
"slug": null,
"public": false,
"regions": [
"nyc2",
"nyc2"
],
"created_at": "2014-11-04T22:23:02Z",
"type": "snapshot",
"min_disk_size": 20,
"size_gigabytes": 2.34,
"description": "",
"tags": [
],
"status": "available",
"error_message": ""
}
],
"links": {
"pages": {
"last": "https://api.digitalocean.com/v2/images?page=56&per_page=1",
"next": "https://api.digitalocean.com/v2/images?page=2&per_page=1"
}
},
"meta": {
"total": 56
}
}To retrieve only distribution images, include the type query parameter set to distribution, /v2/images?type=distribution.
| Name | Type | Description |
|---|---|---|
| id | integer | A unique number that can be used to identify and reference a specific image. |
| name | string | The display name that has been given to an image. This is what is shown in the control panel and is generally a descriptive title for the image in question. |
| type | string | The kind of image, describing the duration of how long the image is stored. This is either "snapshot", "backup", or "custom". |
| distribution | string | This attribute describes the base distribution used for this image. For custom images, this is user defined. |
| slug | nullable string | A 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. |
| public | boolean | This is a boolean value that indicates whether the image in question is public or not. An image that is public is available to all accounts. A non-public image is only accessible from your account. |
| regions | array | This attribute is an array of the regions that the image is available in. The regions are represented by their identifying slug values. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the image was created. |
| min_disk_size | integer | The minimum disk size in GB required for a Droplet to use this image. |
| size_gigabytes | integer | The size of the image in gigabytes. |
| description | string | An optional free-form text field to describe an image. |
| tags | array | An array containing the names of the tags the image has been tagged with. |
| status | string | A status string indicating the state of a custom image. This may be "NEW", "available", "pending", or "deleted". |
| error_message | string | A string containing information about errors that may occur when importing a custom image. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/images?page=1&per_page=1&type=distribution"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
images, _, err := client.Images.ListDistribution(ctx, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 776
ratelimit-reset: 1415984218{
"images": [
{
"id": 6370882,
"name": "20 x64",
"distribution": "Fedora",
"slug": "fedora-20-x64",
"public": true,
"regions": [
"nyc1",
"ams1",
"sfo1",
"nyc2",
"ams2",
"sgp1",
"lon1",
"nyc3",
"ams3",
"nyc3"
],
"created_at": "2014-09-26T15:29:01Z",
"min_disk_size": 20,
"size_gigabytes": 2.34,
"description": "",
"tags": [
],
"status": "available",
"error_message": ""
}
],
"links": {
"pages": {
"last": "https://api.digitalocean.com/v2/images?page=24&per_page=1&type=distribution",
"next": "https://api.digitalocean.com/v2/images?page=2&per_page=1&type=distribution"
}
},
"meta": {
"total": 24
}
}To retrieve only application images, include the type query parameter set to application, /v2/images?type=application.
| Name | Type | Description |
|---|---|---|
| id | integer | A unique number that can be used to identify and reference a specific image. |
| name | string | The display name that has been given to an image. This is what is shown in the control panel and is generally a descriptive title for the image in question. |
| type | string | The kind of image, describing the duration of how long the image is stored. This is either "snapshot", "backup", or "custom". |
| distribution | string | This attribute describes the base distribution used for this image. For custom images, this is user defined. |
| slug | nullable string | A 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. |
| public | boolean | This is a boolean value that indicates whether the image in question is public or not. An image that is public is available to all accounts. A non-public image is only accessible from your account. |
| regions | array | This attribute is an array of the regions that the image is available in. The regions are represented by their identifying slug values. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the image was created. |
| min_disk_size | integer | The minimum disk size in GB required for a Droplet to use this image. |
| size_gigabytes | integer | The size of the image in gigabytes. |
| description | string | An optional free-form text field to describe an image. |
| tags | array | An array containing the names of the tags the image has been tagged with. |
| status | string | A status string indicating the state of a custom image. This may be "NEW", "available", "pending", or "deleted". |
| error_message | string | A string containing information about errors that may occur when importing a custom image. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/images?page=1&per_page=1&type=application"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
images, _, err := client.Images.ListApplication(ctx, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 775
ratelimit-reset: 1415984218{
"images": [
{
"id": 6376601,
"name": "Ruby on Rails on 14.04 (Nginx + Unicorn)",
"distribution": "Ubuntu",
"slug": "ruby-on-rails",
"public": true,
"regions": [
"nyc1",
"ams1",
"sfo1",
"nyc2",
"ams2",
"sgp1",
"lon1",
"nyc3",
"ams3",
"nyc1"
],
"created_at": "2014-09-26T20:20:24Z",
"min_disk_size": 20,
"size_gigabytes": 2.34,
"description": "",
"tags": [
],
"status": "available",
"error_message": ""
}
],
"links": {
"pages": {
"last": "https://api.digitalocean.com/v2/images?page=14&per_page=1&type=application",
"next": "https://api.digitalocean.com/v2/images?page=2&per_page=1&type=application"
}
},
"meta": {
"total": 14
}
}To retrieve only the private images of a user, include the private query parameter set to true, /v2/images?private=true.
| Name | Type | Description |
|---|---|---|
| id | integer | A unique number that can be used to identify and reference a specific image. |
| name | string | The display name that has been given to an image. This is what is shown in the control panel and is generally a descriptive title for the image in question. |
| type | string | The kind of image, describing the duration of how long the image is stored. This is either "snapshot", "backup", or "custom". |
| distribution | string | This attribute describes the base distribution used for this image. For custom images, this is user defined. |
| slug | nullable string | A 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. |
| public | boolean | This is a boolean value that indicates whether the image in question is public or not. An image that is public is available to all accounts. A non-public image is only accessible from your account. |
| regions | array | This attribute is an array of the regions that the image is available in. The regions are represented by their identifying slug values. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the image was created. |
| min_disk_size | integer | The minimum disk size in GB required for a Droplet to use this image. |
| size_gigabytes | integer | The size of the image in gigabytes. |
| description | string | An optional free-form text field to describe an image. |
| tags | array | An array containing the names of the tags the image has been tagged with. |
| status | string | A status string indicating the state of a custom image. This may be "NEW", "available", "pending", or "deleted". |
| error_message | string | A string containing information about errors that may occur when importing a custom image. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/images?page=1&per_page=1&private=true"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
images, _, err := client.Images.ListUser(ctx, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 775
ratelimit-reset: 1415984218{
"images": [
{
"id": 6376601,
"name": "My application image",
"distribution": "Ubuntu",
"public": false,
"regions": [
"nyc1",
"ams1",
"sfo1",
"nyc2",
"ams2",
"sgp1"
],
"created_at": "2014-09-26T20:20:24Z",
"min_disk_size": 20,
"size_gigabytes": 2.34,
"description": "",
"tags": [
],
"status": "available",
"error_message": ""
}
],
"links": {
"pages": {
"last": "https://api.digitalocean.com/v2/images?page=14&per_page=1&type=application",
"next": "https://api.digitalocean.com/v2/images?page=2&per_page=1&type=application"
}
},
"meta": {
"total": 14
}
}To list all images assigned to a specific tag, include the tag_name query parameter set to the name of the tag in your GET request. For example, /v2/images?tag_name=$TAG_NAME.
| Name | Type | Description |
|---|---|---|
| id | integer | A unique number that can be used to identify and reference a specific image. |
| name | string | The display name that has been given to an image. This is what is shown in the control panel and is generally a descriptive title for the image in question. |
| type | string | The kind of image, describing the duration of how long the image is stored. This is either "snapshot", "backup", or "custom". |
| distribution | string | This attribute describes the base distribution used for this image. For custom images, this is user defined. |
| slug | nullable string | A 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. |
| public | boolean | This is a boolean value that indicates whether the image in question is public or not. An image that is public is available to all accounts. A non-public image is only accessible from your account. |
| regions | array | This attribute is an array of the regions that the image is available in. The regions are represented by their identifying slug values. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the image was created. |
| min_disk_size | integer | The minimum disk size in GB required for a Droplet to use this image. |
| size_gigabytes | integer | The size of the image in gigabytes. |
| description | string | An optional free-form text field to describe an image. |
| tags | array | An array containing the names of the tags the image has been tagged with. |
| status | string | A status string indicating the state of a custom image. This may be "NEW", "available", "pending", or "deleted". |
| error_message | string | A string containing information about errors that may occur when importing a custom image. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/images?tag_name=base-image"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 775
ratelimit-reset: 1415984218{
"images": [
{
"id": 38413969,
"name": "ubuntu-18.04-minimal",
"distribution": "Ubuntu",
"slug": null,
"public": false,
"regions": [
"nyc3"
],
"created_at": "2018-09-20T19:28:00Z",
"min_disk_size": 20,
"type": "custom",
"size_gigabytes": 2.36,
"description": "Cloud-optimized image w/ small footprint",
"tags": [
"base-image",
"prod"
],
"status": "available",
"error_message": ""
}
],
"links": {
},
"meta": {
"total": 1
}
}To create a new custom image, send a POST request to /v2/images. The body must contain a url attribute pointing to a Linux virtual machine image to be imported into DigitalOcean. The image must be in the raw, qcow2, vhdx, vdi, or vmdk format. It may be compressed using gzip or bzip2 and must be smaller than 100 GB after being decompressed.
The other attribute values that must be set to successfully create a custom image are:
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | The display name to be given to an image. | true |
| url | string | A URL from which the custom Linux virtual machine image may be retrieved. The image it points to must be in the raw, qcow2, vhdx, vdi, or vmdk format. It may be compressed using gzip or bzip2 and must be smaller than 100 GB after being decompressed. | true |
| region | string | The slug identifier for the region where the image will initially be available. | true |
| distribution | string | The name of a custom image's distribution. Currently, the valid values are "Arch Linux", "CentOS", "CoreOS", "Debian", "Fedora", "Fedora Atomic", "FreeBSD", "Gentoo", "openSUSE", "RancherOS", "Ubuntu", and "Unknown". Any other value will be accepted but ignored, and "Unknown" will be used in its place. | |
| description | string | An optional free-form text field to describe an image. | |
| tags | array | A flat array of tag names as strings to be applied to the image. Tag names may be for either existing or new tags. |
The response will be a JSON object with a key set to image. The value of this will be an image object containing a subset of the standard image attributes as listed below, including the image's id and status. After initial creation, the status will be NEW. Using the image's id, you may query the image's status by sending a GET request to the /v2/images/$IMAGE_ID endpoint. When the status changes to available, the image will be ready for use.
| Name | Type | Description |
|---|---|---|
| id | integer | A unique number that can be used to identify and reference a specific image. |
| name | string | The display name that has been given to an image. This is what is shown in the control panel and is generally a descriptive title for the image in question. |
| type | string | The kind of image, describing the duration of how long the image is stored. This is either "snapshot", "backup", or "custom". |
| description | string | An optional free-form text field to describe an image. |
| distribution | string | This attribute describes the base distribution used for this image. For custom images, this is user defined. |
| regions | array | This attribute is an array of the regions that the image is available in. The regions are represented by their identifying slug values. |
| tags | array | An array containing the names of the tags the image has been tagged with. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the image was created. |
| status | string | A status string indicating the state of a custom image. This may be "NEW", "available", "pending", or "deleted". |
| error_message | string | A string containing information about errors that may occur when importing a custom image. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name": "ubuntu-18.04-minimal", "url": "http://cloud-images.ubuntu.com/minimal/releases/bionic/release/ubuntu-18.04-minimal-cloudimg-amd64.img", "distribution": "Ubuntu", "region": "nyc3", "description": "Cloud-optimized image w/ small footprint", "tags":["base-image", "prod"]}' "https://api.digitalocean.com/v2/images"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
{
"name": "ubuntu-18.04-minimal",
"url": "http://cloud-images.ubuntu.com/minimal/releases/bionic/release/ubuntu-18.04-minimal-cloudimg-amd64.img",
"distribution": "Ubuntu",
"region": "nyc3",
"description": "Cloud-optimized image w/ small footprint",
"tags": [
"base-image",
"prod"
]
}content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 1200
ratelimit-remaining: 772
ratelimit-reset: 1415984218{
"image": {
"created_at": "2018-09-20T19:28:00Z",
"description": "Cloud-optimized image w/ small footprint",
"distribution": "Ubuntu",
"error_message": "",
"id": 38413969,
"name": "ubuntu-18.04-minimal",
"regions": [
],
"type": "custom",
"tags": [
"base-image",
"prod"
],
"status": "NEW"
}
}To retrieve information about an image (public or private), send a GET request to /v2/images/$IMAGE_ID.
The response will be a JSON object with a key called image. The value of this will be an image object containing the standard image attributes:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique number that can be used to identify and reference a specific image. |
| name | string | The display name that has been given to an image. This is what is shown in the control panel and is generally a descriptive title for the image in question. |
| type | string | The kind of image, describing the duration of how long the image is stored. This is either "snapshot", "backup", or "custom". |
| distribution | string | This attribute describes the base distribution used for this image. For custom images, this is user defined. |
| slug | nullable string | A 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. |
| public | boolean | This is a boolean value that indicates whether the image in question is public or not. An image that is public is available to all accounts. A non-public image is only accessible from your account. |
| regions | array | This attribute is an array of the regions that the image is available in. The regions are represented by their identifying slug values. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the image was created. |
| min_disk_size | integer | The minimum disk size in GB required for a Droplet to use this image. |
| size_gigabytes | integer | The size of the image in gigabytes. |
| description | string | An optional free-form text field to describe an image. |
| tags | array | An array containing the names of the tags the image has been tagged with. |
| status | string | A status string indicating the state of a custom image. This may be "NEW", "available", "pending", or "deleted". |
| error_message | string | A string containing information about errors that may occur when importing a custom image. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/images/7555620"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 774
ratelimit-reset: 1415984218{
"image": {
"id": 7555620,
"name": "Nifty New Snapshot",
"distribution": "Ubuntu",
"slug": null,
"public": false,
"regions": [
"nyc2",
"nyc2"
],
"created_at": "2014-11-04T22:23:02Z",
"min_disk_size": 20,
"size_gigabytes": 2.34,
"description": "",
"tags": [
],
"status": "available",
"error_message": ""
}
}To retrieve information about a public image, one option is to send a GET request to /v2/images/$IMAGE_SLUG.
The response will be a JSON object with a key called image. The value of this will be an image object containing the standard image attributes:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique number that can be used to identify and reference a specific image. |
| name | string | The display name that has been given to an image. This is what is shown in the control panel and is generally a descriptive title for the image in question. |
| type | string | The kind of image, describing the duration of how long the image is stored. This is either "snapshot", "backup", or "custom". |
| distribution | string | This attribute describes the base distribution used for this image. For custom images, this is user defined. |
| slug | nullable string | A 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. |
| public | boolean | This is a boolean value that indicates whether the image in question is public or not. An image that is public is available to all accounts. A non-public image is only accessible from your account. |
| regions | array | This attribute is an array of the regions that the image is available in. The regions are represented by their identifying slug values. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the image was created. |
| min_disk_size | integer | The minimum disk size in GB required for a Droplet to use this image. |
| size_gigabytes | integer | The size of the image in gigabytes. |
| description | string | An optional free-form text field to describe an image. |
| tags | array | An array containing the names of the tags the image has been tagged with. |
| status | string | A status string indicating the state of a custom image. This may be "NEW", "available", "pending", or "deleted". |
| error_message | string | A string containing information about errors that may occur when importing a custom image. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/images/ubuntu-16-04-x64"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 773
ratelimit-reset: 1415984218{
"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",
"min_disk_size": 20,
"size_gigabytes": 2.34,
"description": "",
"tags": [
],
"status": "available",
"error_message": ""
}
}To update an image, send a PUT request to /v2/images/$IMAGE_ID. Set the "name" attribute to the new value you would like to use. For custom images, the "description" and "distribution" attributes may also be updated.
| Name | Type | Description |
|---|---|---|
| name | string | The display name to be given to an image. |
| distribution | string | The name of a custom image's distribution. |
| description | string | An optional free-form text field to describe an image. |
The response will be a JSON object with a key set to image. The value of this will be an image object containing the standard image attributes:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique number that can be used to identify and reference a specific image. |
| name | string | The display name that has been given to an image. This is what is shown in the control panel and is generally a descriptive title for the image in question. |
| type | string | The kind of image, describing the duration of how long the image is stored. This is either "snapshot", "backup", or "custom". |
| distribution | string | This attribute describes the base distribution used for this image. For custom images, this is user defined. |
| slug | nullable string | A 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. |
| public | boolean | This is a boolean value that indicates whether the image in question is public or not. An image that is public is available to all accounts. A non-public image is only accessible from your account. |
| regions | array | This attribute is an array of the regions that the image is available in. The regions are represented by their identifying slug values. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the image was created. |
| min_disk_size | integer | The minimum disk size in GB required for a Droplet to use this image. |
| size_gigabytes | integer | The size of the image in gigabytes. |
| description | string | An optional free-form text field to describe an image. |
| tags | array | An array containing the names of the tags the image has been tagged with. |
| status | string | A status string indicating the state of a custom image. This may be "NEW", "available", "pending", or "deleted". |
| error_message | string | A string containing information about errors that may occur when importing a custom image. |
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name":"new-image-name"}' "https://api.digitalocean.com/v2/images/7938391"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)image = DropletKit::Image.new(name: 'new-image-name')
client.images.update(image, id: 7938391)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()updateRequest := &godo.ImageUpdateRequest{
Name: "new-image-name",
}
image, _, err := client.Images.Update(ctx, id, updateRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 772
ratelimit-reset: 1415984218{
"image": {
"id": 7938391,
"name": "new-image-name",
"distribution": "Ubuntu",
"slug": null,
"public": false,
"regions": [
"nyc3",
"nyc3"
],
"created_at": "2014-11-14T16:44:03Z",
"min_disk_size": 20,
"size_gigabytes": 2.34,
"description": "",
"tags": [
],
"status": "available",
"error_message": ""
}
}To retrieve all actions that have been executed on an image, send a GET request to /v2/images/$IMAGE_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:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an action. |
| status | string | The current status of the action. This can be "in-progress", "completed", or "errored". |
| type | string | This 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_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/images/7555620/actions?page=1&per_page=1"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 775
ratelimit-reset: 1415984218{
"actions": [
{
"id": 29410565,
"status": "completed",
"type": "transfer",
"started_at": "2014-07-25T15:04:21Z",
"completed_at": "2014-07-25T15:10:20Z",
"resource_id": 7555620,
"resource_type": "image",
"region": {
"name": "New York 2",
"slug": "nyc2",
"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": "nyc2"
}
],
"links": {
"pages": {
"last": "https://api.digitalocean.com/v2/images/7555620/actions?page=5&per_page=1",
"next": "https://api.digitalocean.com/v2/images/7555620/actions?page=2&per_page=1"
}
},
"meta": {
"total": 5
}
}To delete a snapshot or custom image, send a DELETE request to /v2/images/$IMAGE_ID.
A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/images/7938391"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Image actions are commands that can be given to a DigitalOcean image. In general, these requests are made on the actions endpoint of a specific image.
An image action object is returned. These objects hold the current status of the requested action.
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an image action. |
| status | string | The current status of the image action. This will be either "in-progress", "completed", or "errored". |
| type | string | This is the type of the image action that the JSON object represents. For example, this could be "transfer" to represent the state of an image transfer action. |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
To transfer an image to another region, send a POST request to /v2/images/$IMAGE_ID/actions. Set the "type" attribute to "transfer" and set "region" attribute to the slug identifier of the region you wish to transfer to.
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | Must be transfer | true |
| region | string | The region slug that represents the region target. | true |
The response will be a JSON object with a key called action. The value of this will be an object containing the standard image action attributes:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an image action. |
| status | string | The current status of the image action. This will be either "in-progress", "completed", or "errored". |
| type | string | This is the type of the image action that the JSON object represents. For example, this could be "transfer" to represent the state of an image transfer action. |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"transfer","region":"nyc2"}' "https://api.digitalocean.com/v2/images/7938269/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()transferRequest := &godo.ActionRequest{
"type": "transfer",
"region": "nyc2",
}
transfer, _, err := client.ImageActions.Transfer(ctx, 7938269, transferRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 1200
ratelimit-remaining: 838
ratelimit-reset: 1415984218{
"action": {
"id": 36805527,
"status": "in-progress",
"type": "transfer",
"started_at": "2014-11-14T16:42:45Z",
"completed_at": null,
"resource_id": 7938269,
"resource_type": "image",
"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"
}
}To convert an image, for example, a backup to a snapshot, send a POST request to /v2/images/$IMAGE_ID/actions. Set the "type" attribute to "convert".
| Name | Type | Description | Required |
|---|---|---|---|
| type | string | Must be convert | true |
The response will be a JSON object with a key called action. The value of this will be an object containing the standard image action attributes:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an image action. |
| status | string | The current status of the image action. This will be either "in-progress", "completed", or "errored". |
| type | string | This is the type of the image action that the JSON object represents. For example, this could be "transfer" to represent the state of an image transfer action. |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"type":"convert"}' "https://api.digitalocean.com/v2/images/7938291/actions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
To retrieve the status of an image action, send a GET request to /v2/images/$IMAGE_ID/actions/$IMAGE_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 image action attributes:
| Name | Type | Description |
|---|---|---|
| id | integer | A unique numeric ID that can be used to identify and reference an image action. |
| status | string | The current status of the image action. This will be either "in-progress", "completed", or "errored". |
| type | string | This is the type of the image action that the JSON object represents. For example, this could be "transfer" to represent the state of an image transfer action. |
| started_at | string | A time value given in ISO8601 combined date and time format that represents when the action was initiated. |
| completed_at | string | A time value given in ISO8601 combined date and time format that represents when the action was completed. |
| resource_id | integer | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| region | object | A full region object containing information about the region where the action occurred. |
| region_slug | nullable string | A slug representing the region where the action occurred. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/images/7938269/actions/36805527"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 837
ratelimit-reset: 1415984218{
"action": {
"id": 36805527,
"status": "in-progress",
"type": "transfer",
"started_at": "2014-11-14T16:42:45Z",
"completed_at": null,
"resource_id": 7938269,
"resource_type": "image",
"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"
}
}Load Balancers provide a way to distribute traffic across multiple Droplets. By sending requests to the /v2/load_balancers endpoint, you can list, create, or delete Load Balancers as well as add or remove Droplets, forwarding rules, and other configuration details.
| Name | Type | Description |
|---|---|---|
| id | string | A unique ID that can be used to identify and reference a Load Balancer. |
| name | string | A human-readable name for a Load Balancer instance. |
| ip | string | An attribute containing the public-facing IP address of the Load Balancer. |
| algorithm | string | The load balancing algorithm used to determine which backend Droplet will be selected by a client. It must be either "round_robin" or "least_connections". |
| status | string | A status string indicating the current state of the Load Balancer. This can be "new", "active", or "errored". |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Load Balancer was created. |
| forwarding_rules | object | An object specifying the forwarding rules for a Load Balancer (see table below). |
| health_check | object | An object specifying health check settings for the Load Balancer (see table below). |
| sticky_sessions | object | An object specifying sticky sessions settings for the Load Balancer (see table below). |
| region | object | The region where the Load Balancer instance is located. When setting a region, the value should be the slug identifier for the region. When you query a Load Balancer, an entire region object will be returned. |
| tag | string | The name of a Droplet tag corresponding to Droplets assigned to the Load Balancer. |
| droplet_ids | array of integers | An array containing the IDs of the Droplets assigned to the Load Balancer. |
| redirect_http_to_https | bool | A boolean value indicating whether HTTP requests to the Load Balancer on port 80 will be redirected to HTTPS on port 443. |
Some of a Load Balancer's attributes will have an object value. The forwarding_rules, health_check, and sticky_sessions objects will all contain the standard attributes of their associated types. These can be found below.
Forwarding rules determine how traffic will be routed from the Load Balancer to the Droplets assigned to it. They can be used to configure the type of traffic (HTTP, HTTPS, or TCP) and to map ports on the Load Balancer to ports on the Droplets. For SSL encrypted traffic, you may also configure whether to use SSL termination at the Load Balancer (by specifying an SSL certificate) or to pass the encrypted traffic through to the Droplet. Currently, each Load Balancer may have up to 15 forwarding rules.
| Name | Type | Description |
|---|---|---|
| entry_protocol | string | The protocol used for traffic to the Load Balancer. The possible values are: "http", "https", "http2", or "tcp". |
| entry_port | integer | An integer representing the port on which the Load Balancer instance will listen. |
| target_protocol | string | The protocol used for traffic from the Load Balancer to the backend Droplets. The possible values are: "http", "https", "http2", or "tcp". |
| target_port | integer | An integer representing the port on the backend Droplets to which the Load Balancer will send traffic. |
| certificate_id | string | The ID of the TLS certificate used for SSL termination if enabled. |
| tls_passthrough | bool | A boolean value indicating whether SSL encrypted traffic will be passed through to the backend Droplets. |
Health checks are used to tell if a Droplet is responding and should receive traffic. The Load Balancer will automatically stop sending traffic to unresponsive Droplets. You may specify the protocol, port, and path for a health check as well as additional setting such as the check interval and response timeout.
| Name | Type | Description |
|---|---|---|
| protocol | string | The protocol used for health checks sent to the backend Droplets. The possible values are "http" or "tcp". |
| port | integer | An integer representing the port on the backend Droplets on which the health check will attempt a connection. |
| path | string | The path on the backend Droplets to which the Load Balancer instance will send a request. |
| check_interval_seconds | integer | The number of seconds between between two consecutive health checks. |
| response_timeout_seconds | integer | The number of seconds the Load Balancer instance will wait for a response until marking a health check as failed. |
| unhealthy_threshold | integer | The number of times a health check must fail for a backend Droplet to be marked "unhealthy" and be removed from the pool. |
| healthy_threshold | integer | The number of times a health check must pass for a backend Droplet to be marked "healthy" and be re-added to the pool. |
When sticky sessions are in use, follow up requests from a client will be sent to the same Droplet as the original request. Both the name of the cookie and the TTL are configurable.
| Name | Type | Description |
|---|---|---|
| type | string | An attribute indicating how and if requests from a client will be persistently served by the same backend Droplet. The possible values are "cookies" or "none". |
| cookie_name | string | The name of the cookie sent to the client. This attribute is only returned when using "cookies" for the sticky sessions type. |
| cookie_ttl_seconds | string | The number of seconds until the cookie set by the Load Balancer expires. This attribute is only returned when using "cookies" for the sticky sessions type. |
To create a new Load Balancer instance, send a POST request to /v2/load_balancers. The attribute values that must be set to successfully create a Load Balancer are:
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | A human-readable name for a Load Balancer instance. | true |
| algorithm | string | The load balancing algorithm used to determine which backend Droplet will be selected by a client. It must be either "round_robin" or "least_connections". The default value is "round_robin". | |
| region | string | The region where the Load Balancer instance will be located. When setting a region, the value should be the slug identifier for the region. When you query a Load Balancer, an entire region object will be returned. | true |
| forwarding_rules | array of objects | An array of objects specifying the forwarding rules for a Load Balancer. At least one forwarding rule is required when creating a new Load Balancer instance (see table below). | true |
| health_check | object | An object specifying health check settings for the Load Balancer. If omitted, default values will be provided (see table below). | |
| sticky_sessions | object | An object specifying sticky sessions settings for the Load Balancer (see table below). | |
| redirect_http_to_https | bool | A boolean value indicating whether HTTP requests to the Load Balancer on port 80 will be redirected to HTTPS on port 443. Default value is false. | |
| droplet_ids | array of integers | An array containing the IDs of the Droplets to be assigned to the Load Balancer. |
The request must contain at least one forwarding rule. A Load Balancer's forwarding_rules attribute is made up of an array of objects with the following attributes:
| Name | Type | Description | Required |
|---|---|---|---|
| entry_protocol | string | The protocol used for traffic to the Load Balancer. The possible values are: "http", "https", "http2", or "tcp". | true |
| entry_port | integer | An integer representing the port on which the Load Balancer instance will listen. | true |
| target_protocol | string | The protocol used for traffic from the Load Balancer to the backend Droplets. The possible values are: "http", "https", "http2", or "tcp". | true |
| target_port | integer | An integer representing the port on the backend Droplets to which the Load Balancer will send traffic. | true |
| certificate_id | string | The ID of the TLS certificate to be used for SSL termination. | |
| tls_passthrough | bool | A boolean value indicating whether SSL encrypted traffic will be passed through to the backend Droplets. The defaults value is false. |
The request may also contain health check settings. Defaults will be provided if omitted. A Load Balancer's health_check attribute is made up of an object containing:
| Name | Type | Description | Required |
|---|---|---|---|
| protocol | string | The protocol used for health checks sent to the backend Droplets. The possible values are "http" or "tcp". | true |
| port | integer | An integer representing the port on the backend Droplets on which the health check will attempt a connection. | true |
| path | string | The path on the backend Droplets to which the Load Balancer instance will send a request. The default value is "/". | |
| check_interval_seconds | integer | The number of seconds between between two consecutive health checks. The value must be between 3 and 300. If not specified, the default value is 10. | |
| response_timeout_seconds | integer | The number of seconds the Load Balancer instance will wait for a response until marking a health check as failed. The value must be between 3 and 300. If not specified, the default value is 5. | |
| unhealthy_threshold | integer | The number of times a health check must fail for a backend Droplet to be marked "unhealthy" and be removed from the pool. The vaule must be between 2 and 10. If not specified, the default value is 3. | |
| healthy_threshold | integer | The number of times a health check must pass for a backend Droplet to be marked "healthy" and be re-added to the pool. The vaule must be between 2 and 10. If not specified, the default value is 5. |
The request may also contain sticky session settings. Sticky sessions will not be configured if omitted. A Load Balancer's sticky_sessions attribute is made up of an object containing:
| Name | Type | Description |
|---|---|---|
| type | string | An attribute indicating how and if requests from a client will be persistently served by the same backend Droplet. The possible values are "cookies" or "none". If not specified, the default value is "none". |
| cookie_name | string | The name to be used for the cookie sent to the client. This attribute is required when using "cookies" for the sticky sessions type. |
| cookie_ttl_seconds | string | The number of seconds until the cookie set by the Load Balancer expires. This attribute is required when using "cookies" for the sticky sessions type. |
A Load Balancer instance will be created using the provided information. The response body will contain a JSON object with a key called load_balancer. The value will be an object containing the standard attributes for your new Load Balancer:
| Name | Type | Description |
|---|---|---|
| id | string | A unique ID that can be used to identify and reference a Load Balancer. |
| name | string | A human-readable name for a Load Balancer instance. |
| ip | string | An attribute containing the public-facing IP address of the Load Balancer. |
| algorithm | string | The load balancing algorithm used to determine which backend Droplet will be selected by a client. It must be either "round_robin" or "least_connections". |
| status | string | A status string indicating the current state of the Load Balancer. This can be "new", "active", or "errored". |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Load Balancer was created. |
| forwarding_rules | object | An object specifying the forwarding rules for a Load Balancer (see table below). |
| health_check | object | An object specifying health check settings for the Load Balancer (see table below). |
| sticky_sessions | object | An object specifying sticky sessions settings for the Load Balancer (see table below). |
| region | object | The region where the Load Balancer instance is located. When setting a region, the value should be the slug identifier for the region. When you query a Load Balancer, an entire region object will be returned. |
| tag | string | The name of a Droplet tag corresponding to Droplets assigned to the Load Balancer. |
| droplet_ids | array of integers | An array containing the IDs of the Droplets assigned to the Load Balancer. |
| redirect_http_to_https | bool | A boolean value indicating whether HTTP requests to the Load Balancer on port 80 will be redirected to HTTPS on port 443. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name": "example-lb-01", "region": "nyc3", "forwarding_rules":[{"entry_protocol":"http","entry_port":80,"target_protocol":"http","target_port":80,"certificate_id":"","tls_passthrough":false}, {"entry_protocol": "https","entry_port": 444,"target_protocol": "https","target_port": 443,"tls_passthrough": true}], "health_check":{"protocol":"http","port":80,"path":"/","check_interval_seconds":10,"response_timeout_seconds":5,"healthy_threshold":5,"unhealthy_threshold":3}, "sticky_sessions":{"type":"none"}, "droplet_ids": [3164444, 3164445]}' "https://api.digitalocean.com/v2/load_balancers"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)load_balancer = DropletKit::LoadBalancer.new(
name: 'example-lb-01',
algorithm: 'round_robin',
droplet_ids: [ 3164444, 3164445],
redirect_http_to_https: true,
region: 'nyc3',
forwarding_rules: [
DropletKit::ForwardingRule.new(
entry_protocol: 'http',
entry_port: 80,
target_protocol: 'http',
target_port: 80,
certificate_id: '',
tls_passthrough: false
),
DropletKit::ForwardingRule.new(
entry_protocol: 'https',
entry_port: 443,
target_protocol: 'https',
target_port: 443,
certificate_id: '',
tls_passthrough: true
)
],
sticky_sessions: DropletKit::StickySession.new(
type: 'cookies',
cookie_name: 'DO-LB',
cookie_ttl_seconds: 5
),
health_check: DropletKit::HealthCheck.new(
protocol: 'http',
port: 80,
path: '/',
check_interval_seconds: 10,
response_timeout_seconds: 5,
healthy_threshold: 5,
unhealthy_threshold: 3
)
)
client.load_balancers.create(load_balancer)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()createRequest := &godo.LoadBalancerRequest{
Name: "example-01",
Algorithm: "round_robin",
Region: "nyc3",
ForwardingRules: []godo.ForwardingRule{
{
EntryProtocol: "http",
EntryPort: 80,
TargetProtocol: "http",
TargetPort: 80,
},
{
EntryProtocol: "https",
EntryPort: 443,
TargetProtocol: "https",
TargetPort: 443,
TlsPassthrough: true,
},
},
HealthCheck: &godo.HealthCheck{
Protocol: "http",
Port: 80,
Path: "/",
CheckIntervalSeconds: 10,
ResponseTimeoutSeconds: 5,
HealthyThreshold: 5,
UnhealthyThreshold: 3,
},
StickySessions: &godo.StickySessions{
Type: "none",
},
DropletIDs: []int{3164444, 3164445},
RedirectHttpToHttps: false,
}
lb, _, err := client.LoadBalancers.Create(ctx, createRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
{
"name": "example-lb-01",
"region": "nyc3",
"forwarding_rules": [
{
"entry_protocol": "http",
"entry_port": 80,
"target_protocol": "http",
"target_port": 80,
"certificate_id": "",
"tls_passthrough": false
},
{
"entry_protocol": "https",
"entry_port": 444,
"target_protocol": "https",
"target_port": 443,
"tls_passthrough": true
}
],
"health_check": {
"protocol": "http",
"port": 80,
"path": "/",
"check_interval_seconds": 10,
"response_timeout_seconds": 5,
"healthy_threshold": 5,
"unhealthy_threshold": 3
},
"sticky_sessions": {
"type": "none"
},
"droplet_ids": [
3164444,
3164445
]
}content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833{
"load_balancer": {
"id": "4de7ac8b-495b-4884-9a69-1050c6793cd6",
"name": "example-lb-01",
"ip": "",
"algorithm": "round_robin",
"status": "new",
"created_at": "2017-02-01T22:22:58Z",
"forwarding_rules": [
{
"entry_protocol": "http",
"entry_port": 80,
"target_protocol": "http",
"target_port": 80,
"certificate_id": "",
"tls_passthrough": false
},
{
"entry_protocol": "https",
"entry_port": 444,
"target_protocol": "https",
"target_port": 443,
"certificate_id": "",
"tls_passthrough": true
}
],
"health_check": {
"protocol": "http",
"port": 80,
"path": "/",
"check_interval_seconds": 10,
"response_timeout_seconds": 5,
"healthy_threshold": 5,
"unhealthy_threshold": 3
},
"sticky_sessions": {
"type": "none"
},
"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": [
"private_networking",
"backups",
"ipv6",
"metadata",
"install_agent"
],
"available": true
},
"tag": "",
"droplet_ids": [
3164444,
3164445
],
"redirect_http_to_https": false
}
}You may also use a Droplet tag to assign a group of Droplets to Load Balancer in place of a list of Droplet IDs. To create a new Load Balancer instance, send a POST request to /v2/load_balancers with the tag attribute. All Droplets with the tag will be assigned to the Load Balancer. Additional Droplets will be assigned as they are tagged. The other attributes remain the same:
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | A human-readable name for a Load Balancer instance. | true |
| algorithm | string | The load balancing algorithm used to determine which backend Droplet will be selected by a client. It must be either "round_robin" or "least_connections". The default value is "round_robin". | |
| region | string | The region where the Load Balancer instance will be located. When setting a region, the value should be the slug identifier for the region. When you query a Load Balancer, an entire region object will be returned. | true |
| forwarding_rules | array of objects | An array of objects specifying the forwarding rules for a Load Balancer. At least one forwarding rule is required when creating a new Load Balancer instance (see table below). | true |
| health_check | object | An object specifying health check settings for the Load Balancer. If omitted, default values will be provided (see table below). | |
| sticky_sessions | object | An object specifying sticky sessions settings for the Load Balancer (see table below). | |
| redirect_http_to_https | bool | A boolean value indicating whether HTTP requests to the Load Balancer on port 80 will be redirected to HTTPS on port 443. Default value is false. | |
| tag | string | The name of a Droplet tag corresponding to Droplets to be assigned to the Load Balancer. |
The request must contain at least one forwarding rule. A Load Balancer's forwarding_rules attribute is made up of an array of objects with the following attributes:
| Name | Type | Description | Required |
|---|---|---|---|
| entry_protocol | string | The protocol used for traffic to the Load Balancer. The possible values are: "http", "https", "http2", or "tcp". | true |
| entry_port | integer | An integer representing the port on which the Load Balancer instance will listen. | true |
| target_protocol | string | The protocol used for traffic from the Load Balancer to the backend Droplets. The possible values are: "http", "https", "http2", or "tcp". | true |
| target_port | integer | An integer representing the port on the backend Droplets to which the Load Balancer will send traffic. | true |
| certificate_id | string | The ID of the TLS certificate to be used for SSL termination. | |
| tls_passthrough | bool | A boolean value indicating whether SSL encrypted traffic will be passed through to the backend Droplets. The defaults value is false. |
The request may also contain health check settings. Defaults will be provided if omitted. A Load Balancer's health_check attribute is made up of an object containing:
| Name | Type | Description | Required |
|---|---|---|---|
| protocol | string | The protocol used for health checks sent to the backend Droplets. The possible values are "http" or "tcp". | true |
| port | integer | An integer representing the port on the backend Droplets on which the health check will attempt a connection. | true |
| path | string | The path on the backend Droplets to which the Load Balancer instance will send a request. The default value is "/". | |
| check_interval_seconds | integer | The number of seconds between between two consecutive health checks. The value must be between 3 and 300. If not specified, the default value is 10. | |
| response_timeout_seconds | integer | The number of seconds the Load Balancer instance will wait for a response until marking a health check as failed. The value must be between 3 and 300. If not specified, the default value is 5. | |
| unhealthy_threshold | integer | The number of times a health check must fail for a backend Droplet to be marked "unhealthy" and be removed from the pool. The vaule must be between 2 and 10. If not specified, the default value is 3. | |
| healthy_threshold | integer | The number of times a health check must pass for a backend Droplet to be marked "healthy" and be re-added to the pool. The vaule must be between 2 and 10. If not specified, the default value is 5. |
The request may also contain sticky session settings. Sticky sessions will not be configured if omitted. A Load Balancer's sticky_sessions attribute is made up of an object containing:
| Name | Type | Description |
|---|---|---|
| type | string | An attribute indicating how and if requests from a client will be persistently served by the same backend Droplet. The possible values are "cookies" or "none". If not specified, the default value is "none". |
| cookie_name | string | The name to be used for the cookie sent to the client. This attribute is required when using "cookies" for the sticky sessions type. |
| cookie_ttl_seconds | string | The number of seconds until the cookie set by the Load Balancer expires. This attribute is required when using "cookies" for the sticky sessions type. |
A Load Balancer instance will be created using the provided information. The response body will contain a JSON object with a key called load_balancer. The value will be an object containing the standard attributes for your new Load Balancer:
| Name | Type | Description |
|---|---|---|
| id | string | A unique ID that can be used to identify and reference a Load Balancer. |
| name | string | A human-readable name for a Load Balancer instance. |
| ip | string | An attribute containing the public-facing IP address of the Load Balancer. |
| algorithm | string | The load balancing algorithm used to determine which backend Droplet will be selected by a client. It must be either "round_robin" or "least_connections". |
| status | string | A status string indicating the current state of the Load Balancer. This can be "new", "active", or "errored". |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Load Balancer was created. |
| forwarding_rules | object | An object specifying the forwarding rules for a Load Balancer (see table below). |
| health_check | object | An object specifying health check settings for the Load Balancer (see table below). |
| sticky_sessions | object | An object specifying sticky sessions settings for the Load Balancer (see table below). |
| region | object | The region where the Load Balancer instance is located. When setting a region, the value should be the slug identifier for the region. When you query a Load Balancer, an entire region object will be returned. |
| tag | string | The name of a Droplet tag corresponding to Droplets assigned to the Load Balancer. |
| droplet_ids | array of integers | An array containing the IDs of the Droplets assigned to the Load Balancer. |
| redirect_http_to_https | bool | A boolean value indicating whether HTTP requests to the Load Balancer on port 80 will be redirected to HTTPS on port 443. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name": "example-lb-01", "region": "nyc3", "forwarding_rules":[{"entry_protocol":"http","entry_port":80,"target_protocol":"http","target_port":80,"certificate_id":"","tls_passthrough":false}, {"entry_protocol": "https","entry_port": 444,"target_protocol": "https","target_port": 443,"tls_passthrough": true}], "health_check":{"protocol":"http","port":80,"path":"/","check_interval_seconds":10,"response_timeout_seconds":5,"healthy_threshold":5,"unhealthy_threshold":3}, "sticky_sessions":{"type":"none"}, "tag": "web:prod"}' "https://api.digitalocean.com/v2/load_balancers"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)load_balancer = DropletKit::LoadBalancer.new(
name: 'example-lb-01',
algorithm: 'round_robin',
tag: 'web:prod',
redirect_http_to_https: true,
region: 'nyc3',
forwarding_rules: [
DropletKit::ForwardingRule.new(
entry_protocol: 'http',
entry_port: 80,
target_protocol: 'http',
target_port: 80,
certificate_id: '',
tls_passthrough: false
),
DropletKit::ForwardingRule.new(
entry_protocol: 'https',
entry_port: 443,
target_protocol: 'https',
target_port: 443,
certificate_id: '',
tls_passthrough: true
)
],
sticky_sessions: DropletKit::StickySession.new(
type: 'cookies',
cookie_name: 'DO-LB',
cookie_ttl_seconds: 5
),
health_check: DropletKit::HealthCheck.new(
protocol: 'http',
port: 80,
path: '/',
check_interval_seconds: 10,
response_timeout_seconds: 5,
healthy_threshold: 5,
unhealthy_threshold: 3
)
)
client.load_balancers.create(load_balancer)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()createRequest := &godo.LoadBalancerRequest{
Name: "example-01",
Algorithm: "round_robin",
Region: "nyc3",
ForwardingRules: []godo.ForwardingRule{
{
EntryProtocol: "http",
EntryPort: 80,
TargetProtocol: "http",
TargetPort: 80,
},
{
EntryProtocol: "https",
EntryPort: 443,
TargetProtocol: "https",
TargetPort: 443,
TlsPassthrough: true,
},
},
HealthCheck: &godo.HealthCheck{
Protocol: "http",
Port: 80,
Path: "/",
CheckIntervalSeconds: 10,
ResponseTimeoutSeconds: 5,
HealthyThreshold: 5,
UnhealthyThreshold: 3,
},
StickySessions: &godo.StickySessions{
Type: "none",
},
Tag: "web:prod",
RedirectHttpToHttps: false,
}
lb, _, err := c.LoadBalancers.Create(ctx, createRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
{
"name": "example-lb-01",
"region": "nyc3",
"forwarding_rules": [
{
"entry_protocol": "http",
"entry_port": 80,
"target_protocol": "http",
"target_port": 80,
"certificate_id": "",
"tls_passthrough": false
},
{
"entry_protocol": "https",
"entry_port": 444,
"target_protocol": "https",
"target_port": 443,
"tls_passthrough": true
}
],
"health_check": {
"protocol": "http",
"port": 80,
"path": "/",
"check_interval_seconds": 10,
"response_timeout_seconds": 5,
"healthy_threshold": 5,
"unhealthy_threshold": 3
},
"sticky_sessions": {
"type": "none"
},
"tag": "web:prod"
}content-type: application/json; charset=utf-8
status: 202 Accepted
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833{
"load_balancer": {
"id": "4de7ac8b-495b-4884-9a69-1050c6793cd6",
"name": "example-lb-01",
"ip": "",
"algorithm": "round_robin",
"status": "new",
"created_at": "2017-02-01T22:22:58Z",
"forwarding_rules": [
{
"entry_protocol": "http",
"entry_port": 80,
"target_protocol": "http",
"target_port": 80,
"certificate_id": "",
"tls_passthrough": false
},
{
"entry_protocol": "https",
"entry_port": 444,
"target_protocol": "https",
"target_port": 443,
"certificate_id": "",
"tls_passthrough": true
}
],
"health_check": {
"protocol": "http",
"port": 80,
"path": "/",
"check_interval_seconds": 10,
"response_timeout_seconds": 5,
"healthy_threshold": 5,
"unhealthy_threshold": 3
},
"sticky_sessions": {
"type": "none"
},
"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": [
"private_networking",
"backups",
"ipv6",
"metadata",
"install_agent"
],
"available": true
},
"droplet_ids": [
3164444,
3164445
],
"tag": "web:prod",
"redirect_http_to_https": false
}
}To show information about a Load Balancer instance, send a GET request to /v2/load_balancers/$LOAD_BALANCER_ID.
The response will be a JSON object with a key called load_balancer. The value of this will be an object that contains the standard attributes associated with a Load Balancer:
| Name | Type | Description |
|---|---|---|
| id | string | A unique ID that can be used to identify and reference a Load Balancer. |
| name | string | A human-readable name for a Load Balancer instance. |
| ip | string | An attribute containing the public-facing IP address of the Load Balancer. |
| algorithm | string | The load balancing algorithm used to determine which backend Droplet will be selected by a client. It must be either "round_robin" or "least_connections". |
| status | string | A status string indicating the current state of the Load Balancer. This can be "new", "active", or "errored". |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Load Balancer was created. |
| forwarding_rules | object | An object specifying the forwarding rules for a Load Balancer (see table below). |
| health_check | object | An object specifying health check settings for the Load Balancer (see table below). |
| sticky_sessions | object | An object specifying sticky sessions settings for the Load Balancer (see table below). |
| region | object | The region where the Load Balancer instance is located. When setting a region, the value should be the slug identifier for the region. When you query a Load Balancer, an entire region object will be returned. |
| tag | string | The name of a Droplet tag corresponding to Droplets assigned to the Load Balancer. |
| droplet_ids | array of integers | An array containing the IDs of the Droplets assigned to the Load Balancer. |
| redirect_http_to_https | bool | A boolean value indicating whether HTTP requests to the Load Balancer on port 80 will be redirected to HTTPS on port 443. |
The forwarding_rules attribute will contain an array of objects with the following attributes:
| Name | Type | Description |
|---|---|---|
| entry_protocol | string | The protocol used for traffic to the Load Balancer. The possible values are: "http", "https", "http2", or "tcp". |
| entry_port | integer | An integer representing the port on which the Load Balancer instance will listen. |
| target_protocol | string | The protocol used for traffic from the Load Balancer to the backend Droplets. The possible values are: "http", "https", "http2", or "tcp". |
| target_port | integer | An integer representing the port on the backend Droplets to which the Load Balancer will send traffic. |
| certificate_id | string | The ID of the TLS certificate used for SSL termination if enabled. |
| tls_passthrough | bool | A boolean value indicating whether SSL encrypted traffic will be passed through to the backend Droplets. |
The embedded health_check object will contain:
| Name | Type | Description |
|---|---|---|
| protocol | string | The protocol used for health checks sent to the backend Droplets. The possible values are "http" or "tcp". |
| port | integer | An integer representing the port on the backend Droplets on which the health check will attempt a connection. |
| path | string | The path on the backend Droplets to which the Load Balancer instance will send a request. |
| check_interval_seconds | integer | The number of seconds between between two consecutive health checks. |
| response_timeout_seconds | integer | The number of seconds the Load Balancer instance will wait for a response until marking a health check as failed. |
| unhealthy_threshold | integer | The number of times a health check must fail for a backend Droplet to be marked "unhealthy" and be removed from the pool. |
| healthy_threshold | integer | The number of times a health check must pass for a backend Droplet to be marked "healthy" and be re-added to the pool. |
The embedded sticky_sessions object will contain:
| Name | Type | Description |
|---|---|---|
| type | string | An attribute indicating how and if requests from a client will be persistently served by the same backend Droplet. The possible values are "cookies" or "none". |
| cookie_name | string | The name of the cookie sent to the client. This attribute is only returned when using "cookies" for the sticky sessions type. |
| cookie_ttl_seconds | string | The number of seconds until the cookie set by the Load Balancer expires. This attribute is only returned when using "cookies" for the sticky sessions type. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4823
ratelimit-reset: 1444931833{
"load_balancer": {
"id": "4de7ac8b-495b-4884-9a69-1050c6793cd6",
"name": "example-lb-01",
"ip": "104.131.186.241",
"algorithm": "round_robin",
"status": "new",
"created_at": "2017-02-01T22:22:58Z",
"forwarding_rules": [
{
"entry_protocol": "http",
"entry_port": 80,
"target_protocol": "http",
"target_port": 80,
"certificate_id": "",
"tls_passthrough": false
},
{
"entry_protocol": "https",
"entry_port": 444,
"target_protocol": "https",
"target_port": 443,
"certificate_id": "",
"tls_passthrough": true
}
],
"health_check": {
"protocol": "http",
"port": 80,
"path": "/",
"check_interval_seconds": 10,
"response_timeout_seconds": 5,
"healthy_threshold": 5,
"unhealthy_threshold": 3
},
"sticky_sessions": {
"type": "none"
},
"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": [
"private_networking",
"backups",
"ipv6",
"metadata",
"install_agent"
],
"available": true
},
"tag": "",
"droplet_ids": [
3164444,
3164445
],
"redirect_http_to_https": false
}
}To list all of the Load Balancer instances on your account, send a GET request to /v2/load_balancers.
The response will be a JSON object with a key called load_balancers. This will be set to an array of objects, each of which will contain the standard Load Balancer attributes.
| Name | Type | Description |
|---|---|---|
| id | string | A unique ID that can be used to identify and reference a Load Balancer. |
| name | string | A human-readable name for a Load Balancer instance. |
| ip | string | An attribute containing the public-facing IP address of the Load Balancer. |
| algorithm | string | The load balancing algorithm used to determine which backend Droplet will be selected by a client. It must be either "round_robin" or "least_connections". |
| status | string | A status string indicating the current state of the Load Balancer. This can be "new", "active", or "errored". |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Load Balancer was created. |
| forwarding_rules | object | An object specifying the forwarding rules for a Load Balancer (see table below). |
| health_check | object | An object specifying health check settings for the Load Balancer (see table below). |
| sticky_sessions | object | An object specifying sticky sessions settings for the Load Balancer (see table below). |
| region | object | The region where the Load Balancer instance is located. When setting a region, the value should be the slug identifier for the region. When you query a Load Balancer, an entire region object will be returned. |
| tag | string | The name of a Droplet tag corresponding to Droplets assigned to the Load Balancer. |
| droplet_ids | array of integers | An array containing the IDs of the Droplets assigned to the Load Balancer. |
| redirect_http_to_https | bool | A boolean value indicating whether HTTP requests to the Load Balancer on port 80 will be redirected to HTTPS on port 443. |
The forwarding_rules attribute will contain an array of objects with the following attributes:
| Name | Type | Description |
|---|---|---|
| entry_protocol | string | The protocol used for traffic to the Load Balancer. The possible values are: "http", "https", "http2", or "tcp". |
| entry_port | integer | An integer representing the port on which the Load Balancer instance will listen. |
| target_protocol | string | The protocol used for traffic from the Load Balancer to the backend Droplets. The possible values are: "http", "https", "http2", or "tcp". |
| target_port | integer | An integer representing the port on the backend Droplets to which the Load Balancer will send traffic. |
| certificate_id | string | The ID of the TLS certificate used for SSL termination if enabled. |
| tls_passthrough | bool | A boolean value indicating whether SSL encrypted traffic will be passed through to the backend Droplets. |
The embedded health_check object will contain:
| Name | Type | Description |
|---|---|---|
| protocol | string | The protocol used for health checks sent to the backend Droplets. The possible values are "http" or "tcp". |
| port | integer | An integer representing the port on the backend Droplets on which the health check will attempt a connection. |
| path | string | The path on the backend Droplets to which the Load Balancer instance will send a request. |
| check_interval_seconds | integer | The number of seconds between between two consecutive health checks. |
| response_timeout_seconds | integer | The number of seconds the Load Balancer instance will wait for a response until marking a health check as failed. |
| unhealthy_threshold | integer | The number of times a health check must fail for a backend Droplet to be marked "unhealthy" and be removed from the pool. |
| healthy_threshold | integer | The number of times a health check must pass for a backend Droplet to be marked "healthy" and be re-added to the pool. |
The embedded sticky_sessions object will contain:
| Name | Type | Description |
|---|---|---|
| type | string | An attribute indicating how and if requests from a client will be persistently served by the same backend Droplet. The possible values are "cookies" or "none". |
| cookie_name | string | The name of the cookie sent to the client. This attribute is only returned when using "cookies" for the sticky sessions type. |
| cookie_ttl_seconds | string | The number of seconds until the cookie set by the Load Balancer expires. This attribute is only returned when using "cookies" for the sticky sessions type. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/load_balancers"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
lbs, _, err := c.LoadBalancers.List(ctx, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4816
ratelimit-reset: 1444931833{
"load_balancers": [
{
"id": "4de7ac8b-495b-4884-9a69-1050c6793cd6",
"name": "example-lb-01",
"ip": "104.131.186.241",
"algorithm": "round_robin",
"status": "new",
"created_at": "2017-02-01T22:22:58Z",
"forwarding_rules": [
{
"entry_protocol": "http",
"entry_port": 80,
"target_protocol": "http",
"target_port": 80,
"certificate_id": "",
"tls_passthrough": false
},
{
"entry_protocol": "https",
"entry_port": 444,
"target_protocol": "https",
"target_port": 443,
"certificate_id": "",
"tls_passthrough": true
}
],
"health_check": {
"protocol": "http",
"port": 80,
"path": "/",
"check_interval_seconds": 10,
"response_timeout_seconds": 5,
"healthy_threshold": 5,
"unhealthy_threshold": 3
},
"sticky_sessions": {
"type": "none"
},
"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": [
"private_networking",
"backups",
"ipv6",
"metadata",
"install_agent"
],
"available": true
},
"tag": "",
"droplet_ids": [
3164444,
3164445
],
"redirect_http_to_https": false
}
],
"links": {
},
"meta": {
"total": 1
}
}To update a Load Balancer's settings, send a PUT request to /v2/load_balancers/$LOAD_BALANCER_ID. The request should contain a full representation of the Load Balancer including existing attributes. It may contain one of the droplets_ids or tag attributes as they are mutually exclusive. Note that any attribute that is not provided will be reset to its default value.
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | A human-readable name for a Load Balancer instance. | true |
| algorithm | string | The load balancing algorithm used to determine which backend Droplet will be selected by a client. It must be either "round_robin" or "least_connections". The default value is "round_robin". | |
| region | string | The region where the Load Balancer instance will be located. When setting a region, the value should be the slug identifier for the region. When you query a Load Balancer, an entire region object will be returned. | true |
| forwarding_rules | array of objects | An array of objects specifying the forwarding rules for a Load Balancer. At least one forwarding rule is required when creating a new Load Balancer instance (see table below). | true |
| health_check | object | An object specifying health check settings for the Load Balancer. If omitted, default values will be provided (see table below). | |
| sticky_sessions | object | An object specifying sticky sessions settings for the Load Balancer (see table below). | |
| redirect_http_to_https | bool | A boolean value indicating whether HTTP requests to the Load Balancer on port 80 will be redirected to HTTPS on port 443. Default value is false. | |
| droplet_ids | array of integers | An array containing the IDs of the Droplets to be assigned to the Load Balancer. This attribute and the "tag" attribute are mutually exclusive. | |
| tag | string | The name of a Droplet tag corresponding to Droplets to be assigned to the Load Balancer. This attribute and the "droplet_ids" attribute are mutually exclusive. |
A Load Balancer's forwarding_rules attribute is made up of an array of objects with the following attributes:
| Name | Type | Description | Required |
|---|---|---|---|
| entry_protocol | string | The protocol used for traffic to the Load Balancer. The possible values are: "http", "https", "http2", or "tcp". | true |
| entry_port | integer | An integer representing the port on which the Load Balancer instance will listen. | true |
| target_protocol | string | The protocol used for traffic from the Load Balancer to the backend Droplets. The possible values are: "http", "https", "http2", or "tcp". | true |
| target_port | integer | An integer representing the port on the backend Droplets to which the Load Balancer will send traffic. | true |
| certificate_id | string | The ID of the TLS certificate to be used for SSL termination. | |
| tls_passthrough | bool | A boolean value indicating whether SSL encrypted traffic will be passed through to the backend Droplets. The defaults value is false. |
A Load Balancer's health_check attribute is made up of an object containing:
| Name | Type | Description | Required |
|---|---|---|---|
| protocol | string | The protocol used for health checks sent to the backend Droplets. The possible values are "http" or "tcp". | true |
| port | integer | An integer representing the port on the backend Droplets on which the health check will attempt a connection. | true |
| path | string | The path on the backend Droplets to which the Load Balancer instance will send a request. The default value is "/". | |
| check_interval_seconds | integer | The number of seconds between between two consecutive health checks. The value must be between 3 and 300. If not specified, the default value is 10. | |
| response_timeout_seconds | integer | The number of seconds the Load Balancer instance will wait for a response until marking a health check as failed. The value must be between 3 and 300. If not specified, the default value is 5. | |
| unhealthy_threshold | integer | The number of times a health check must fail for a backend Droplet to be marked "unhealthy" and be removed from the pool. The vaule must be between 2 and 10. If not specified, the default value is 3. | |
| healthy_threshold | integer | The number of times a health check must pass for a backend Droplet to be marked "healthy" and be re-added to the pool. The vaule must be between 2 and 10. If not specified, the default value is 5. |
A Load Balancer's sticky_sessions attribute is made up of an object containing:
| Name | Type | Description |
|---|---|---|
| type | string | An attribute indicating how and if requests from a client will be persistently served by the same backend Droplet. The possible values are "cookies" or "none". If not specified, the default value is "none". |
| cookie_name | string | The name to be used for the cookie sent to the client. This attribute is required when using "cookies" for the sticky sessions type. |
| cookie_ttl_seconds | string | The number of seconds until the cookie set by the Load Balancer expires. This attribute is required when using "cookies" for the sticky sessions type. |
The Load Balancer instance will be updated using the provided information. The response body will contain a JSON object with a key called load_balancer. The value will be an object containing the standard attributes for your new Load Balancer:
| Name | Type | Description |
|---|---|---|
| id | string | A unique ID that can be used to identify and reference a Load Balancer. |
| name | string | A human-readable name for a Load Balancer instance. |
| ip | string | An attribute containing the public-facing IP address of the Load Balancer. |
| algorithm | string | The load balancing algorithm used to determine which backend Droplet will be selected by a client. It must be either "round_robin" or "least_connections". |
| status | string | A status string indicating the current state of the Load Balancer. This can be "new", "active", or "errored". |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the Load Balancer was created. |
| forwarding_rules | object | An object specifying the forwarding rules for a Load Balancer (see table below). |
| health_check | object | An object specifying health check settings for the Load Balancer (see table below). |
| sticky_sessions | object | An object specifying sticky sessions settings for the Load Balancer (see table below). |
| region | object | The region where the Load Balancer instance is located. When setting a region, the value should be the slug identifier for the region. When you query a Load Balancer, an entire region object will be returned. |
| tag | string | The name of a Droplet tag corresponding to Droplets assigned to the Load Balancer. |
| droplet_ids | array of integers | An array containing the IDs of the Droplets assigned to the Load Balancer. |
| redirect_http_to_https | bool | A boolean value indicating whether HTTP requests to the Load Balancer on port 80 will be redirected to HTTPS on port 443. |
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name":"example-lb-01","region":"nyc3","algorithm":"least_connections","forwarding_rules":[{"entry_protocol":"http","entry_port":80,"target_protocol":"http","target_port":80},{"entry_protocol":"https","entry_port":444,"target_protocol":"https","target_port":443,"tls_passthrough":true}],"health_check":{"protocol":"http","port":80,"path":"/","check_interval_seconds":10,"response_timeout_seconds":5,"healthy_threshold":5,"unhealthy_threshold":3},"sticky_sessions":{"type":"cookies", "cookie_name": "DO_LB", "cookie_ttl_seconds": 300}, "droplet_ids": [3164444, 3164445]}' "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)load_balancer = DropletKit::LoadBalancer.new(
name: 'example-lb-01',
algorithm: 'round_robin',
droplet_ids: [ 3164444, 3164445],
redirect_http_to_https: true,
region: 'nyc3',
forwarding_rules: [
DropletKit::ForwardingRule.new(
entry_protocol: 'http',
entry_port: 80,
target_protocol: 'http',
target_port: 80,
certificate_id: '',
tls_passthrough: false
),
DropletKit::ForwardingRule.new(
entry_protocol: 'https',
entry_port: 443,
target_protocol: 'https',
target_port: 443,
certificate_id: '',
tls_passthrough: true
)
],
sticky_sessions: DropletKit::StickySession.new(
type: 'cookies',
cookie_name: 'DO-LB-COOKIE',
cookie_ttl_seconds: 5
),
health_check: DropletKit::HealthCheck.new(
protocol: 'http',
port: 80,
path: '/',
check_interval_seconds: 10,
response_timeout_seconds: 5,
healthy_threshold: 5,
unhealthy_threshold: 3
)
)
client.load_balancers.update(load_balancer, id: '4de7ac8b-495b-4884-9a69-1050c6793cd6')import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()updateRequest := &godo.LoadBalancerRequest{
Name: "example-01",
Algorithm: "round_robin",
Region: "nyc3",
ForwardingRules: []godo.ForwardingRule{
{
EntryProtocol: "http",
EntryPort: 80,
TargetProtocol: "http",
TargetPort: 80,
},
{
EntryProtocol: "https",
EntryPort: 443,
TargetProtocol: "https",
TargetPort: 443,
TlsPassthrough: true,
},
},
HealthCheck: &godo.HealthCheck{
Protocol: "http",
Port: 80,
Path: "/",
CheckIntervalSeconds: 10,
ResponseTimeoutSeconds: 5,
HealthyThreshold: 5,
UnhealthyThreshold: 3,
},
StickySessions: &godo.StickySessions{
Type: "cookies",
CookieName: "DO_LB",
CookieTtlSeconds: 300,
},
DropletIDs: []int{3164444, 3164445},
RedirectHttpToHttps: false,
}
lb, _, err := c.LoadBalancers.Update(ctx, "c2c97ca7-6f63-4e23-8909-906fd86efb5e", updateRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
{
"name": "example-lb-01",
"region": "nyc3",
"algorithm": "least_connections",
"forwarding_rules": [
{
"entry_protocol": "http",
"entry_port": 80,
"target_protocol": "http",
"target_port": 80
},
{
"entry_protocol": "https",
"entry_port": 444,
"target_protocol": "https",
"target_port": 443,
"tls_passthrough": true
}
],
"health_check": {
"protocol": "http",
"port": 80,
"path": "/",
"check_interval_seconds": 10,
"response_timeout_seconds": 5,
"healthy_threshold": 5,
"unhealthy_threshold": 3
},
"sticky_sessions": {
"type": "cookies",
"cookie_name": "DO_LB",
"cookie_ttl_seconds": 300
},
"droplet_ids": [
3164444,
3164445
]
}content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 1046
ratelimit-reset: 1415984218{
"load_balancer": {
"id": "4de7ac8b-495b-4884-9a69-1050c6793cd6",
"name": "example-lb-01",
"ip": "138.197.50.73",
"algorithm": "least_connections",
"status": "active",
"created_at": "2017-02-01T22:22:58Z",
"forwarding_rules": [
{
"entry_protocol": "http",
"entry_port": 80,
"target_protocol": "http",
"target_port": 80,
"certificate_id": "",
"tls_passthrough": false
},
{
"entry_protocol": "https",
"entry_port": 444,
"target_protocol": "https",
"target_port": 443,
"certificate_id": "",
"tls_passthrough": true
}
],
"health_check": {
"protocol": "http",
"port": 80,
"path": "/",
"check_interval_seconds": 10,
"response_timeout_seconds": 5,
"healthy_threshold": 5,
"unhealthy_threshold": 3
},
"sticky_sessions": {
"type": "cookies",
"cookie_name": "DO_LB",
"cookie_ttl_seconds": 300
},
"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": [
"private_networking",
"backups",
"ipv6",
"metadata",
"install_agent"
],
"available": true
},
"tag": "",
"droplet_ids": [
34153248,
34153250
],
"redirect_http_to_https": false
}
}To delete a Load Balancer instance, disassociating any Droplets assigned to it and removing it from your account, send a DELETE request to /v2/load_balancers/$LOAD_BALANCER_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.
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()To assign a Droplet to a Load Balancer instance, send a POST request to /v2/load_balancers/$LOAD_BALANCER_ID/droplets. In the body of the request, there should be a "droplet_ids" attribute containing a list of Droplet IDs. Individual Droplets can not be added to a Load Balancer configured with a Droplet tag. Attempting to do so will result in a "422 Unprocessable Entity" response from the API.
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.
| Name | Type | Description | Required |
|---|---|---|---|
| droplet_ids | array of integers | An array containing the IDs of the Droplets to be assigned to the Load Balancer instance. | true |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"droplet_ids": [3164446, 3164447]}' "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6/droplets"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)client.load_balancers.add_droplets([3164446, 3164447], id: '4de7ac8b-495b-4884-9a69-1050c6793cd6')import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()droplets := []int{3164446, 3164447}
_, err := client.LoadBalancers.AddDroplets(ctx, "4de7ac8b-495b-4884-9a69-1050c6793cd6", droplets...)To remove a Droplet from a Load Balancer instance, send a DELETE request to /v2/load_balancers/$LOAD_BALANCER_ID/droplets. In the body of the request, there should be a "droplet_ids" attribute containing a list of Droplet IDs.
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.
| Name | Type | Description | Required |
|---|---|---|---|
| droplet_ids | array of integers | An array containing the IDs of the Droplets to be removed from the Load Balancer instance. | true |
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"droplet_ids": [3164446, 3164447]}' "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6/droplets"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)client.load_balancers.remove_droplets([3164446, 3164447], id: '4de7ac8b-495b-4884-9a69-1050c6793cd6')import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()droplets := []int{3164446, 3164447}
_, err := client.LoadBalancers.RemoveDroplets(ctx, "4de7ac8b-495b-4884-9a69-1050c6793cd6", droplets...)To add an additional forwarding rule to a Load Balancer instance, send a POST request to /v2/load_balancers/$LOAD_BALANCER_ID/forwarding_rules. In the body of the request, there should be a "forwarding_rules" attribute containing an array of rules to be added.
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.
| Name | Type | Description | Required |
|---|---|---|---|
| entry_protocol | string | The protocol used for traffic to the Load Balancer. The possible values are: "http", "https", "http2", or "tcp". | true |
| entry_port | integer | An integer representing the port on which the Load Balancer instance will listen. | true |
| target_protocol | string | The protocol used for traffic from the Load Balancer to the backend Droplets. The possible values are: "http", "https", "http2", or "tcp". | true |
| target_port | integer | An integer representing the port on the backend Droplets to which the Load Balancer will send traffic. | true |
| certificate_id | string | The ID of the TLS certificate to be used for SSL termination. | |
| tls_passthrough | bool | A boolean value indicating whether SSL encrypted traffic will be passed through to the backend Droplets. The defaults value is false. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"forwarding_rules": [{"entry_protocol": "tcp","entry_port": 3306,"target_protocol": "tcp","target_port": 3306}]}' "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6/forwarding_rules"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)rule = DropletKit::ForwardingRule.new(
entry_protocol: 'tcp',
entry_port: 3306,
target_protocol: 'tcp',
target_port: 3306,
certificate_id: '',
tls_passthrough: false
)
client.load_balancers.add_forwarding_rules([rule], id: '4de7ac8b-495b-4884-9a69-1050c6793cd6')import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()forwardingRule := []godo.ForwardingRule{
{
EntryProtocol: "tcp",
EntryPort: 3306,
TargetProtocol: "tcp",
TargetPort: 3306,
},
}
_, err := client.LoadBalancers.AddForwardingRules(ctx, "4de7ac8b-495b-4884-9a69-1050c6793cd6", forwardingRule...)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
To remove forwarding rules from a Load Balancer instance, send a DELETE request to /v2/load_balancers/$LOAD_BALANCER_ID/forwarding_rules. In the body of the request, there should be a "forwarding_rules" attribute containing an array of rules to be removed.
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.
| Name | Type | Description | Required |
|---|---|---|---|
| entry_protocol | string | The protocol used for traffic to the Load Balancer. The possible values are: "http", "https", "http2", or "tcp". | true |
| entry_port | integer | An integer representing the port on which the Load Balancer instance will listen. | true |
| target_protocol | string | The protocol used for traffic from the Load Balancer to the backend Droplets. The possible values are: "http", "https", "http2", or "tcp". | true |
| target_port | integer | An integer representing the port on the backend Droplets to which the Load Balancer will send traffic. | true |
| certificate_id | string | The ID of the TLS certificate to be used for SSL termination. | |
| tls_passthrough | bool | A boolean value indicating whether SSL encrypted traffic will be passed through to the backend Droplets. The defaults value is false. |
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"forwarding_rules": [{"entry_protocol": "tcp","entry_port": 3306,"target_protocol": "tcp","target_port": 3306}]}' "https://api.digitalocean.com/v2/load_balancers/4de7ac8b-495b-4884-9a69-1050c6793cd6/forwarding_rules"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)rule = DropletKit::ForwardingRule.new(
entry_protocol: 'tcp',
entry_port: 3306,
target_protocol: 'tcp',
target_port: 3306,
certificate_id: '',
tls_passthrough: false
)
client.load_balancers.remove_forwarding_rules([rule], id: '4de7ac8b-495b-4884-9a69-1050c6793cd6')import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()forwardingRule := []godo.ForwardingRule{
{
EntryProtocol: "tcp",
EntryPort: 3306,
TargetProtocol: "tcp",
TargetPort: 3306,
},
}
_, err := client.LoadBalancers.RemoveForwardingRules(ctx, "4de7ac8b-495b-4884-9a69-1050c6793cd6", forwardingRule...)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
Note: The projects API is currently in beta. Please follow along with the API changelog for updates and share your feedback to help shape its future.
Projects allow you to organize your resources into groups that fit the way you work. You can group resources (like Droplets, Spaces, Load Balancers, domains, and Floating IPs) in ways that align with the applications you host on DigitalOcean. Projects have the following attributes:| Name | Type | Description |
|---|---|---|
| id | string | The unique universal identifier of this project. |
| owner_uuid | string | The unique universal identifier of the project owner. |
| owner_id | integer | The integer id of the project owner. |
| name | string | The human-readable name for the project. The maximum length is 175 characters and the name must be unique. |
| description | string | The description of the project. The maximum length is 255 characters. |
| purpose | string | The purpose of the project. The maximum length is 255 characters. For examples of valid purposes, see the "Purposes" section |
| environment | string | The environment of the project's resources. |
| is_default | boolean | If true, all resources will be added to this project if no project is specified. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the project was created. |
| updated_at | string | A time value given in ISO8601 combined date and time format that represents when the project was updated. |
purpose attribute can have one of the following values:
purpose, for example "your custom purpose", your purpose will be stored as Other: your custom purpose
environment attribute must have one of the following values:
400 Bad Request is returned.
To create a project, send a POST request to /v2/projects. The following attributes are supported:
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | The human-readable name for the project. The maximum length is 175 characters and the name must be unique. | true |
| description | string | The description of the project. The maximum length is 255 characters. | |
| purpose | string | The purpose of the project. The maximum length is 255 characters. For examples of valid purposes, see the "Purposes" section | true |
| environment | string | The environment of the project's resources. |
The response will be a JSON object with a key called project. The value of this will be an object with the standard project attributes:
| Name | Type | Description |
|---|---|---|
| id | string | The unique universal identifier of this project. |
| owner_uuid | string | The unique universal identifier of the project owner. |
| owner_id | integer | The integer id of the project owner. |
| name | string | The human-readable name for the project. The maximum length is 175 characters and the name must be unique. |
| description | string | The description of the project. The maximum length is 255 characters. |
| purpose | string | The purpose of the project. The maximum length is 255 characters. For examples of valid purposes, see the "Purposes" section |
| environment | string | The environment of the project's resources. |
| is_default | boolean | If true, all resources will be added to this project if no project is specified. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the project was created. |
| updated_at | string | A time value given in ISO8601 combined date and time format that represents when the project was updated. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name":"my-web-api", "description": "My website API", "purpose": "Service or API", "environment": "Production"}' "https://api.digitalocean.com/v2/projects"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)project = DropletKit::Project.new(
name: 'my-api',
description: 'My website API',
purpose: 'Service or API',
environment: 'Production'
)
client.projects.create(project)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()createReq := &godo.CreateProjectRequest{
Name: "my-web-api",
Description: "My website API",
Purpose: "Service or API",
Environment: "Production",
}
client.Projects.Create(ctx, createReq)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
{
"name": "my-web-api",
"description": "My website API",
"purpose": "Service or API",
"environment": "Production"
}content-type: application/json; charset=utf-8
status: 201 Created
ratelimit-limit: 1200
ratelimit-remaining: 770
ratelimit-reset: 1415984218{
"project": {
"id": "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679",
"owner_uuid": "99525febec065ca37b2ffe4f852fd2b2581895e7",
"owner_id": 2,
"name": "my-web-api",
"description": "My website API",
"purpose": "Service or API",
"environment": "Production",
"is_default": false,
"created_at": "2018-09-27T15:52:48Z",
"updated_at": "2018-09-27T15:52:48Z"
}
}To list all your projects, send a GET request to /v2/projects. The response will be a JSON object with a key called projects. The value of this will be an object with the standard project attributes:
| Name | Type | Description |
|---|---|---|
| id | string | The unique universal identifier of this project. |
| owner_uuid | string | The unique universal identifier of the project owner. |
| owner_id | integer | The integer id of the project owner. |
| name | string | The human-readable name for the project. The maximum length is 175 characters and the name must be unique. |
| description | string | The description of the project. The maximum length is 255 characters. |
| purpose | string | The purpose of the project. The maximum length is 255 characters. For examples of valid purposes, see the "Purposes" section |
| environment | string | The environment of the project's resources. |
| is_default | boolean | If true, all resources will be added to this project if no project is specified. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the project was created. |
| updated_at | string | A time value given in ISO8601 combined date and time format that represents when the project was updated. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/projects"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 770
ratelimit-reset: 1415984218{
"projects": [
{
"id": "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679",
"owner_uuid": "99525febec065ca37b2ffe4f852fd2b2581895e7",
"owner_id": 2,
"name": "my-web-api",
"description": "My website API",
"purpose": "Service or API",
"environment": "Production",
"is_default": false,
"created_at": "2018-09-27T20:10:35Z",
"updated_at": "2018-09-27T20:10:35Z"
}
],
"links": {
"pages": {
"first": "https://api.digitalocean.com/v2/projects?page=1",
"last": "https://api.digitalocean.com/v2/projects?page=1"
}
},
"meta": {
"total": 1
}
}To update a project, send a PUT request to /v2/projects/$PROJECT_ID. All of the following attributes must be sent:
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | The human-readable name for the project. The maximum length is 175 characters. | true |
| description | string | The description of the project. The maximum length is 255 characters. | true |
| purpose | string | The purpose of the project. The maximum length is 255 characters. For examples of valid purposes, see the "Purposes" section | true |
| environment | string | The environment of the project's resources. | |
| is_default | boolean | If true, all resources will be added to this project if no project is specified. | true |
The response will be a JSON object with a key called project. The value of this will be an object with the standard project attributes:
| Name | Type | Description |
|---|---|---|
| id | string | The unique universal identifier of this project. |
| owner_uuid | string | The unique universal identifier of the project owner. |
| owner_id | integer | The integer id of the project owner. |
| name | string | The human-readable name for the project. The maximum length is 175 characters and the name must be unique. |
| description | string | The description of the project. The maximum length is 255 characters. |
| purpose | string | The purpose of the project. The maximum length is 255 characters. For examples of valid purposes, see the "Purposes" section |
| environment | string | The environment of the project's resources. |
| is_default | boolean | If true, all resources will be added to this project if no project is specified. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the project was created. |
| updated_at | string | A time value given in ISO8601 combined date and time format that represents when the project was updated. |
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name":"my-web-api", "description": "My website API", "purpose": "Service or API", "environment": "Staging", "is_default": false}' "https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)project = client.projects.find(id: '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679')
project.environment = 'Staging'
client.projects.update(project, id: '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679')import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()updateReq := &godo.UpdateProjectRequest{
Name: "my-web-api",
Description: "My website API",
Purpose: "Service or API",
Environment: "Staging",
IsDefault: false,
}
client.Projects.Update(ctx, "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679", updateReq)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
{
"name": "my-web-api",
"description": "My website API",
"purpose": "Service or API",
"environment": "Staging",
"is_default": false
}content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 770
ratelimit-reset: 1415984218{
"project": {
"id": "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679",
"owner_uuid": "99525febec065ca37b2ffe4f852fd2b2581895e7",
"owner_id": 2,
"name": "my-web-api",
"description": "My website API",
"purpose": "Service or API",
"environment": "Staging",
"is_default": false,
"created_at": "2018-09-27T15:52:48Z",
"updated_at": "2018-09-27T15:52:48Z"
}
}To update only specific attributes of a project, send a PATCH request to /v2/projects/$PROJECT_ID. Only one of the following attributes needs to be sent:
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | The human-readable name for the project. The maximum length is 175 characters. | true |
| description | string | The description of the project. The maximum length is 255 characters. | true |
| purpose | string | The purpose of the project. The maximum length is 255 characters. For examples of valid purposes, see the "Purposes" section | true |
| environment | string | The environment of the project's resources. | |
| is_default | boolean | If true, all resources will be added to this project if no project is specified. | true |
The response will be a JSON object with a key called project. The value of this will be an object with the standard project attributes:
| Name | Type | Description |
|---|---|---|
| id | string | The unique universal identifier of this project. |
| owner_uuid | string | The unique universal identifier of the project owner. |
| owner_id | integer | The integer id of the project owner. |
| name | string | The human-readable name for the project. The maximum length is 175 characters and the name must be unique. |
| description | string | The description of the project. The maximum length is 255 characters. |
| purpose | string | The purpose of the project. The maximum length is 255 characters. For examples of valid purposes, see the "Purposes" section |
| environment | string | The environment of the project's resources. |
| is_default | boolean | If true, all resources will be added to this project if no project is specified. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the project was created. |
| updated_at | string | A time value given in ISO8601 combined date and time format that represents when the project was updated. |
curl -X PATCH -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"environment": "Staging"}' "https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)project = client.projects.find(id: '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679')
project.environment = 'Staging'
client.projects.update(project, id: '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679')import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()updateReq := &godo.UpdateProjectRequest{
Environment: "Staging",
}
client.Projects.Update(ctx, "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679", updateReq)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 770
ratelimit-reset: 1415984218{
"project": {
"id": "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679",
"owner_uuid": "99525febec065ca37b2ffe4f852fd2b2581895e7",
"owner_id": 2,
"name": "my-web-api",
"description": "My website API",
"purpose": "Service or API",
"environment": "Staging",
"is_default": false,
"created_at": "2018-09-27T15:52:48Z",
"updated_at": "2018-09-27T15:52:48Z"
}
}To get a project, send a GET request to /v2/projects/$PROJECT_ID. The response will be a JSON object with a key called project. The value of this will be an object with the standard project attributes:
| Name | Type | Description |
|---|---|---|
| id | string | The unique universal identifier of this project. |
| owner_uuid | string | The unique universal identifier of the project owner. |
| owner_id | integer | The integer id of the project owner. |
| name | string | The human-readable name for the project. The maximum length is 175 characters and the name must be unique. |
| description | string | The description of the project. The maximum length is 255 characters. |
| purpose | string | The purpose of the project. The maximum length is 255 characters. For examples of valid purposes, see the "Purposes" section |
| environment | string | The environment of the project's resources. |
| is_default | boolean | If true, all resources will be added to this project if no project is specified. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the project was created. |
| updated_at | string | A time value given in ISO8601 combined date and time format that represents when the project was updated. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 770
ratelimit-reset: 1415984218{
"project": {
"id": "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679",
"owner_uuid": "99525febec065ca37b2ffe4f852fd2b2581895e7",
"owner_id": 2,
"name": "my-web-api",
"description": "My website API",
"purpose": "Service or API",
"environment": "Production",
"is_default": false,
"created_at": "2018-09-27T20:10:35Z",
"updated_at": "2018-09-27T20:10:35Z"
}
}To get the default project, send a GET request to /v2/projects/default. The response will be a JSON object with a key called project. The value of this will be an object with the standard project attributes:
| Name | Type | Description |
|---|---|---|
| id | string | The unique universal identifier of this project. |
| owner_uuid | string | The unique universal identifier of the project owner. |
| owner_id | integer | The integer id of the project owner. |
| name | string | The human-readable name for the project. The maximum length is 175 characters and the name must be unique. |
| description | string | The description of the project. The maximum length is 255 characters. |
| purpose | string | The purpose of the project. The maximum length is 255 characters. For examples of valid purposes, see the "Purposes" section |
| environment | string | The environment of the project's resources. |
| is_default | boolean | If true, all resources will be added to this project if no project is specified. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the project was created. |
| updated_at | string | A time value given in ISO8601 combined date and time format that represents when the project was updated. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/projects/default"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 770
ratelimit-reset: 1415984218{
"project": {
"id": "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679",
"owner_uuid": "99525febec065ca37b2ffe4f852fd2b2581895e7",
"owner_id": 2,
"name": "my-web-api",
"description": "My website API",
"purpose": "Service or API",
"environment": "Production",
"is_default": true,
"created_at": "2018-09-27T20:10:35Z",
"updated_at": "2018-09-27T20:10:35Z"
}
}To update the default project, send a PUT request to /v2/projects/default. All of the following attributes must be sent:
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | The human-readable name for the project. The maximum length is 175 characters. | true |
| description | string | The description of the project. The maximum length is 255 characters. | true |
| purpose | string | The purpose of the project. The maximum length is 255 characters. For examples of valid purposes, see the "Purposes" section | true |
| environment | string | The environment of the project's resources. | |
| is_default | boolean | If true, all resources will be added to this project if no project is specified. | true |
The response will be a JSON object with a key called project. The value of this will be an object with the standard project attributes:
| Name | Type | Description |
|---|---|---|
| id | string | The unique universal identifier of this project. |
| owner_uuid | string | The unique universal identifier of the project owner. |
| owner_id | integer | The integer id of the project owner. |
| name | string | The human-readable name for the project. The maximum length is 175 characters and the name must be unique. |
| description | string | The description of the project. The maximum length is 255 characters. |
| purpose | string | The purpose of the project. The maximum length is 255 characters. For examples of valid purposes, see the "Purposes" section |
| environment | string | The environment of the project's resources. |
| is_default | boolean | If true, all resources will be added to this project if no project is specified. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the project was created. |
| updated_at | string | A time value given in ISO8601 combined date and time format that represents when the project was updated. |
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name":"my-web-api", "description": "My website API", "purpose": "Service or API", "environment": "Staging", "is_default": false}' "https://api.digitalocean.com/v2/projects/default"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)project = client.projects.find_default
project.environment = 'Staging'
client.projects.update(project, id: 'default')import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()updateReq := &godo.UpdateProjectRequest{
Name: "my-web-api",
Description: "My website API",
Purpose: "Service or API",
Environment: "Staging",
IsDefault: false,
}
client.Projects.Update(ctx, godo.DefaultProject, updateReq)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
{
"name": "my-web-api",
"description": "My website API",
"purpose": "Service or API",
"environment": "Staging",
"is_default": false
}content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 770
ratelimit-reset: 1415984218{
"project": {
"id": "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679",
"owner_uuid": "99525febec065ca37b2ffe4f852fd2b2581895e7",
"owner_id": 2,
"name": "my-web-api",
"description": "My website API",
"purpose": "Service or API",
"environment": "Staging",
"is_default": false,
"created_at": "2018-09-27T15:52:48Z",
"updated_at": "2018-09-27T15:52:48Z"
}
}To update only specific attributes of the default project, send a PATCH request to /v2/projects/default. Only one of the following attributes needs to be sent:
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | The human-readable name for the project. The maximum length is 175 characters. | true |
| description | string | The description of the project. The maximum length is 255 characters. | true |
| purpose | string | The purpose of the project. The maximum length is 255 characters. For examples of valid purposes, see the "Purposes" section | true |
| environment | string | The environment of the project's resources. | |
| is_default | boolean | If true, all resources will be added to this project if no project is specified. | true |
The response will be a JSON object with a key called project. The value of this will be an object with the standard project attributes:
| Name | Type | Description |
|---|---|---|
| id | string | The unique universal identifier of this project. |
| owner_uuid | string | The unique universal identifier of the project owner. |
| owner_id | integer | The integer id of the project owner. |
| name | string | The human-readable name for the project. The maximum length is 175 characters and the name must be unique. |
| description | string | The description of the project. The maximum length is 255 characters. |
| purpose | string | The purpose of the project. The maximum length is 255 characters. For examples of valid purposes, see the "Purposes" section |
| environment | string | The environment of the project's resources. |
| is_default | boolean | If true, all resources will be added to this project if no project is specified. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the project was created. |
| updated_at | string | A time value given in ISO8601 combined date and time format that represents when the project was updated. |
curl -X PATCH -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"environment": "Staging"}' "https://api.digitalocean.com/v2/projects/default"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)project = client.projects.find_default
project.environment = 'Staging'
client.projects.update(project, id: 'default')import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()updateReq := &godo.UpdateProjectRequest{
Environment: "Staging",
}
client.Projects.Update(ctx, godo.DefaultProject, updateReq)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 770
ratelimit-reset: 1415984218{
"project": {
"id": "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679",
"owner_uuid": "99525febec065ca37b2ffe4f852fd2b2581895e7",
"owner_id": 2,
"name": "my-web-api",
"description": "My website API",
"purpose": "Service or API",
"environment": "Staging",
"is_default": false,
"created_at": "2018-09-27T15:52:48Z",
"updated_at": "2018-09-27T15:52:48Z"
}
}Note: The projects API is currently in beta. Please follow along with the API changelog for updates and share your feedback to help shape its future.
Project Resources are resources that can be grouped into your projects. You can group resources (like Droplets, Spaces, Load Balancers, domains, and Floating IPs) in ways that align with the applications you host on DigitalOcean. Resources can have the following attributes:| Name | Type | Description |
|---|---|---|
| urn | string | The uniform resource name of the resource. |
| assigned_at | string | A time value given in ISO8601 combined date and time format that represents when the project was created. |
| links | string | The links object contains the self object, which contains the resource relationship. |
| status | string | The status of assigning and fetching the resources. |
do:resource_type:resource_id. The following resource types are supported:
status attribute is returned that indicates if a resource was successfully retrieved or assigned. The status codes can be one of the following:
ok: there was no problem retrieving or assigning a resource.not_found: the resource was not found.assigned: the resource was successfully assigned.already_assigned: the resource was already assigned.service_down: there was a problem retrieving or assigning a resource. Please try again.To list all your resources in a project, send a GET request to /v2/projects/$PROJECT_ID/resources. The response will be a JSON object with a key called resources. The value of this will be an object with the standard resource attributes:
| Name | Type | Description |
|---|---|---|
| urn | string | The uniform resource name of the resource. |
| assigned_at | string | A time value given in ISO8601 combined date and time format that represents when the project was created. |
| links | string | The links object contains the self object, which contains the resource relationship. |
| status | string | The status of assigning and fetching the resources. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
PerPage: 10,
Page: 1,
}
client.Projects.ListResources(ctx, "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679", opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 770
ratelimit-reset: 1415984218{
"resources": [
{
"urn": "do:droplet:1",
"assigned_at": "2018-09-28T19:26:37Z",
"links": {
"self": "https://api.digitalocean.com/v2/droplets/1"
},
"status": "ok"
}
],
"links": {
"pages": {
"first": "https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679/resources?page=1",
"last": "https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679/resources?page=1"
}
},
"meta": {
"total": 1
}
}To assign resources to a project, send a POST request to /v2/projects/$PROJECT_ID/resources with the following attributes:
| Name | Type | Description | Required |
|---|---|---|---|
| urn | string | The uniform resource name of the resource. | true |
The response will be a JSON object with a key called resources. The value of this will be an object with the standard resource attributes:
| Name | Type | Description |
|---|---|---|
| urn | string | The uniform resource name of the resource. |
| assigned_at | string | A time value given in ISO8601 combined date and time format that represents when the project was created. |
| links | string | The links object contains the self object, which contains the resource relationship. |
| status | string | The status of assigning and fetching the resources. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"resources": ["do:droplet:1", "do:floatingip:192.168.99.100"]}' "https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679/resources"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)resource = DropletKit::ProjectAssignment.new(urn: 'do:droplet:1')
client.projects.assign_resources([resource], id: '4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679')import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()res := []interface{}{
&godo.Droplet{ID: 1},
"do:droplet:42",
&godo.FloatingIP{IP: "192.168.99.100"},
}
client.Projects.AssignResources(ctx, "4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679", res...)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 770
ratelimit-reset: 1415984218{
"resources": [
{
"urn": "do:droplet:1",
"assigned_at": "2018-09-28T19:26:37Z",
"links": {
"self": "https://api.digitalocean.com/v2/droplets/1"
},
"status": "assigned"
},
{
"urn": "do:floatingip:192.168.99.100",
"assigned_at": "2018-09-28T19:26:37Z",
"links": {
"self": "https://api.digitalocean.com/v2/floating_ips/192.168.99.100"
},
"status": "assigned"
}
],
"links": {
"pages": {
"first": "https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679/resources?page=1",
"last": "https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679/resources?page=1"
}
},
"meta": {
"total": 2
}
}To list all your resources in the default project, send a GET request to /v2/projects/default/resources. The response will be a JSON object with a key called resources. The value of this will be an object with the standard resource attributes:
| Name | Type | Description |
|---|---|---|
| urn | string | The uniform resource name of the resource. |
| assigned_at | string | A time value given in ISO8601 combined date and time format that represents when the project was created. |
| links | string | The links object contains the self object, which contains the resource relationship. |
| status | string | The status of assigning and fetching the resources. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/projects/default/resources"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
PerPage: 10,
Page: 1,
}
client.Projects.ListResources(ctx, godo.DefaultProject, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 770
ratelimit-reset: 1415984218{
"resources": [
{
"urn": "do:droplet:1",
"assigned_at": "2018-09-28T19:26:37Z",
"links": {
"self": "https://api.digitalocean.com/v2/droplets/1"
},
"status": "ok"
}
],
"links": {
"pages": {
"first": "https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679/resources?page=1",
"last": "https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679/resources?page=1"
}
},
"meta": {
"total": 1
}
}To assign resources to the default project, send a POST request to /v2/projects/default/resources with the following attributes:
| Name | Type | Description | Required |
|---|---|---|---|
| urn | string | The uniform resource name of the resource. | true |
The response will be a JSON object with a key called resources. The value of this will be an object with the standard resource attributes:
| Name | Type | Description |
|---|---|---|
| urn | string | The uniform resource name of the resource. |
| assigned_at | string | A time value given in ISO8601 combined date and time format that represents when the project was created. |
| links | string | The links object contains the self object, which contains the resource relationship. |
| status | string | The status of assigning and fetching the resources. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"resources": ["do:droplet:1", "do:floatingip:192.168.99.100"]}' "https://api.digitalocean.com/v2/projects/default/resources"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)resource = DropletKit::ProjectAssignment.new(urn: 'do:droplet:1')
client.projects.assign_resources([resource], id: 'default')import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()res := []interface{}{
&godo.Droplet{ID: 1},
"do:droplet:42",
&godo.FloatingIP{IP: "192.168.99.100"},
}
client.Projects.AssignResources(ctx, godo.DefaultProject, res...)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 770
ratelimit-reset: 1415984218{
"resources": [
{
"urn": "do:droplet:1",
"assigned_at": "2018-09-28T19:26:37Z",
"links": {
"self": "https://api.digitalocean.com/v2/droplets/1"
},
"status": "assigned"
},
{
"urn": "do:floatingip:192.168.99.100",
"assigned_at": "2018-09-28T19:26:37Z",
"links": {
"self": "https://api.digitalocean.com/v2/floating_ips/192.168.99.100"
},
"status": "assigned"
}
],
"links": {
"pages": {
"first": "https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679/resources?page=1",
"last": "https://api.digitalocean.com/v2/projects/4e1bfbc3-dc3e-41f2-a18f-1b4d7ba71679/resources?page=1"
}
},
"meta": {
"total": 2
}
}A region in DigitalOcean represents a datacenter where Droplets can be deployed and images can be transferred.
Each region represents a specific datacenter in a geographic location. Some geographical locations may have multiple "regions" available. This means that there are multiple datacenters available within that area.
| Name | Type | Description |
|---|---|---|
| slug | string | A human-readable string that is used as a unique identifier for each region. |
| name | string | The display name of the region. This will be a full name that is used in the control panel and other interfaces. |
| sizes | array | This attribute is set to an array which contains the identifying slugs for the sizes available in this region. |
| available | boolean | This is a boolean value that represents whether new Droplets can be created in this region. |
| features | array | This attribute is set to an array which contains features available in this region |
To list all of the regions that are available, send a GET request to /v2/regions.
The response will be a JSON object with a key called regions. The value of this will be an array of region objects, each of which will contain the standard region attributes:
| Name | Type | Description |
|---|---|---|
| slug | string | A human-readable string that is used as a unique identifier for each region. |
| name | string | The display name of the region. This will be a full name that is used in the control panel and other interfaces. |
| sizes | array | This attribute is set to an array which contains the identifying slugs for the sizes available in this region. |
| available | boolean | This is a boolean value that represents whether new Droplets can be created in this region. |
| features | array | This attribute is set to an array which contains features available in this region |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/regions"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
regions, _, err := client.Regions.List(ctx, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 770
ratelimit-reset: 1415984218{
"regions": [
{
"name": "New York 1",
"slug": "nyc1",
"sizes": [
],
"features": [
"virtio",
"backups"
],
"available": false
},
{
"name": "Amsterdam 1",
"slug": "ams1",
"sizes": [
],
"features": [
"virtio",
"backups"
],
"available": false
},
{
"name": "San Francisco 1",
"slug": "sfo1",
"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",
"backups",
"metadata"
],
"available": true
},
{
"name": "New York 2",
"slug": "nyc2",
"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"
],
"available": true
},
{
"name": "Amsterdam 2",
"slug": "ams2",
"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",
"metadata"
],
"available": true
},
{
"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": [
"virtio",
"private_networking",
"backups",
"ipv6",
"metadata"
],
"available": true
},
{
"name": "London 1",
"slug": "lon1",
"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
},
{
"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
},
{
"name": "Amsterdam 3",
"slug": "ams3",
"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
}
],
"links": {
},
"meta": {
"total": 9
}
}The sizes objects represent different packages of hardware resources that can be used for Droplets. When a Droplet is created, a size must be selected so that the correct resources can be allocated.
Each size represents a plan that bundles together specific sets of resources. This includes the amount of RAM, the number of virtual CPUs, disk space, and transfer. The size object also includes the pricing details and the regions that the size is available in.
| Name | Type | Description |
|---|---|---|
| slug | string | A human-readable string that is used to uniquely identify each size. |
| available | boolean | This is a boolean value that represents whether new Droplets can be created with this size. |
| transfer | integer | The amount of transfer bandwidth that is available for Droplets created in this size. This only counts traffic on the public interface. The value is given in terabytes. |
| price_monthly | integer | This attribute describes the monthly cost of this Droplet size if the Droplet is kept for an entire month. The value is measured in US dollars. |
| price_hourly | integer | This describes the price of the Droplet size as measured hourly. The value is measured in US dollars. |
| memory | integer | The amount of RAM allocated to Droplets created of this size. The value is represented in megabytes. |
| vcpus | integer | The integer of number CPUs allocated to Droplets of this size. |
| disk | integer | The amount of disk space set aside for Droplets of this size. The value is represented in gigabytes. |
| regions | array | An array containing the region slugs where this size is available for Droplet creates. |
To list all of the sizes, send a GET request to /v2/sizes.
The response will be a JSON object with a key called sizes. The value of this will be an array of size objects each of which contain the standard sizes attributes:
| Name | Type | Description |
|---|---|---|
| slug | string | A human-readable string that is used to uniquely identify each size. |
| available | boolean | This is a boolean value that represents whether new Droplets can be created with this size. |
| transfer | integer | The amount of transfer bandwidth that is available for Droplets created in this size. This only counts traffic on the public interface. The value is given in terabytes. |
| price_monthly | integer | This attribute describes the monthly cost of this Droplet size if the Droplet is kept for an entire month. The value is measured in US dollars. |
| price_hourly | integer | This describes the price of the Droplet size as measured hourly. The value is measured in US dollars. |
| memory | integer | The amount of RAM allocated to Droplets created of this size. The value is represented in megabytes. |
| vcpus | integer | The integer of number CPUs allocated to Droplets of this size. |
| disk | integer | The amount of disk space set aside for Droplets of this size. The value is represented in gigabytes. |
| regions | array | An array containing the region slugs where this size is available for Droplet creates. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/sizes"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
sizes, _, err := client.Sizes.List(ctx, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 769
ratelimit-reset: 1415984218{
"sizes": [
{
"slug": "s-1vcpu-1gb",
"memory": 1024,
"vcpus": 1,
"disk": 25,
"transfer": 1.0,
"price_monthly": 5.0,
"price_hourly": 0.00744,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sgp1",
"tor1"
],
"available": true
},
{
"slug": "s-3vcpu-1gb",
"memory": 1024,
"vcpus": 3,
"disk": 60,
"transfer": 3.0,
"price_monthly": 15.0,
"price_hourly": 0.02232,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sgp1",
"tor1"
],
"available": true
},
{
"slug": "s-1vcpu-2gb",
"memory": 2048,
"vcpus": 1,
"disk": 50,
"transfer": 2.0,
"price_monthly": 10.0,
"price_hourly": 0.01488,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sgp1",
"tor1"
],
"available": true
},
{
"slug": "s-2vcpu-2gb",
"memory": 2048,
"vcpus": 2,
"disk": 60,
"transfer": 3.0,
"price_monthly": 15.0,
"price_hourly": 0.02232,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sgp1",
"tor1"
],
"available": true
},
{
"slug": "s-1vcpu-3gb",
"memory": 3072,
"vcpus": 1,
"disk": 20,
"transfer": 3.0,
"price_monthly": 15.0,
"price_hourly": 0.02232,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sgp1",
"tor1"
],
"available": true
},
{
"slug": "c-2",
"memory": 4096,
"vcpus": 2,
"disk": 25,
"transfer": 5.0,
"price_monthly": 40.0,
"price_hourly": 0.06,
"regions": [
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc3",
"sfo2",
"sgp1",
"tor1"
],
"available": true
},
{
"slug": "s-2vcpu-4gb",
"memory": 4096,
"vcpus": 2,
"disk": 80,
"transfer": 4.0,
"price_monthly": 20.0,
"price_hourly": 0.02976,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sgp1",
"tor1"
],
"available": true
},
{
"slug": "s-4vcpu-8gb",
"memory": 8192,
"vcpus": 4,
"disk": 160,
"transfer": 5.0,
"price_monthly": 40.0,
"price_hourly": 0.05952,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sgp1",
"tor1"
],
"available": true
},
{
"slug": "c-4",
"memory": 8192,
"vcpus": 4,
"disk": 50,
"transfer": 5.0,
"price_monthly": 80.0,
"price_hourly": 0.119,
"regions": [
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc3",
"sfo2",
"sgp1",
"tor1"
],
"available": true
},
{
"slug": "c-8",
"memory": 16384,
"vcpus": 8,
"disk": 100,
"transfer": 5.0,
"price_monthly": 160.0,
"price_hourly": 0.238,
"regions": [
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc3",
"sfo2",
"sgp1",
"tor1"
],
"available": true
},
{
"slug": "s-6vcpu-16gb",
"memory": 16384,
"vcpus": 6,
"disk": 320,
"transfer": 6.0,
"price_monthly": 80.0,
"price_hourly": 0.11905,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sgp1",
"tor1"
],
"available": true
},
{
"slug": "s-8vcpu-32gb",
"memory": 32768,
"vcpus": 8,
"disk": 640,
"transfer": 7.0,
"price_monthly": 160.0,
"price_hourly": 0.2381,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sgp1",
"tor1"
],
"available": true
},
{
"slug": "c-16",
"memory": 32768,
"vcpus": 16,
"disk": 200,
"transfer": 5.0,
"price_monthly": 320.0,
"price_hourly": 0.476,
"regions": [
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc3",
"sfo2",
"sgp1",
"tor1"
],
"available": true
},
{
"slug": "s-12vcpu-48gb",
"memory": 49152,
"vcpus": 12,
"disk": 960,
"transfer": 8.0,
"price_monthly": 240.0,
"price_hourly": 0.35714,
"regions": [
"ams2",
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo1",
"sfo2",
"sgp1",
"tor1"
],
"available": true
},
{
"slug": "s-16vcpu-64gb",
"memory": 65536,
"vcpus": 16,
"disk": 1280,
"transfer": 9.0,
"price_monthly": 320.0,
"price_hourly": 0.47619,
"regions": [
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo2",
"sgp1",
"tor1"
],
"available": true
},
{
"slug": "c-32",
"memory": 65536,
"vcpus": 32,
"disk": 400,
"transfer": 5.0,
"price_monthly": 640.0,
"price_hourly": 0.952,
"regions": [
"fra1"
],
"available": true
},
{
"slug": "c-48",
"memory": 73728,
"vcpus": 48,
"disk": 20,
"transfer": 5.0,
"price_monthly": 960.0,
"price_hourly": 1.429,
"regions": [
],
"available": true
},
{
"slug": "s-20vcpu-96gb",
"memory": 98304,
"vcpus": 20,
"disk": 1920,
"transfer": 10.0,
"price_monthly": 480.0,
"price_hourly": 0.71429,
"regions": [
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo2",
"sgp1",
"tor1"
],
"available": true
},
{
"slug": "s-24vcpu-128gb",
"memory": 131072,
"vcpus": 24,
"disk": 2560,
"transfer": 11.0,
"price_monthly": 640.0,
"price_hourly": 0.95238,
"regions": [
"ams3",
"blr1",
"fra1",
"lon1",
"nyc1",
"nyc2",
"nyc3",
"sfo2",
"sgp1",
"tor1"
],
"available": true
},
{
"slug": "s-32vcpu-192gb",
"memory": 196608,
"vcpus": 24,
"disk": 3840,
"transfer": 12.0,
"price_monthly": 960.0,
"price_hourly": 1.42857,
"regions": [
],
"available": true
}
],
"links": {
},
"meta": {
"total": 20
}
}Snapshots are saved instances of a Droplet or a block storage volume, which is reflected in the resource_type attribute. In order to avoid problems with compressing filesystems, each defines a min_disk_size attribute which is the minimum size of the Droplet or volume disk when creating a new resource from the saved snapshot.
To interact with snapshots, you will generally send requests to the snapshots endpoint at /v2/snapshots.
| Name | Type | Description |
|---|---|---|
| id | string | The unique identifier for the snapshot. |
| name | string | A human-readable name for the snapshot. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the snapshot was created. |
| regions | array | An array of the regions that the image is available in. The regions are represented by their identifying slug values. |
| resource_id | string | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| min_disk_size | integer | The minimum size in GB required for a volume or Droplet to use this snapshot. |
| size_gigabytes | integer | The billable size of the snapshot in gigabytes. |
To list all of the snapshots available on your account, send a GET request to /v2/snapshots.
The response will be a JSON object with a key called snapshots. This will be set to an array of snapshot objects, each of which will contain the standard snapshot attributes:
| Name | Type | Description |
|---|---|---|
| id | string | The unique identifier for the snapshot. |
| name | string | A human-readable name for the snapshot. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the snapshot was created. |
| regions | array | An array of the regions that the image is available in. The regions are represented by their identifying slug values. |
| resource_id | string | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| min_disk_size | integer | The minimum size in GB required for a volume or Droplet to use this snapshot. |
| size_gigabytes | integer | The billable size of the snapshot in gigabytes. |
curl -X GET -H 'Content-Type: application/json' -H 'Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582' "https://api.digitalocean.com/v2/snapshots?page=1&per_page=1"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
snapshots, _, err := client.Snapshots.List(ctx, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4989
ratelimit-reset: 1475174402{
"snapshots": [
{
"id": 6372321,
"name": "5.10 x64",
"regions": [
"nyc1",
"ams1",
"sfo1",
"nyc2",
"ams2",
"sgp1",
"lon1",
"nyc3",
"ams3",
"fra1",
"tor1"
],
"created_at": "2014-09-26T16:40:18Z",
"resource_id": 2713828,
"resource_type": "droplet",
"min_disk_size": 20,
"size_gigabytes": 1.42
}
],
"links": {
"pages": {
"last": "https://api.digitalocean.com/v2/snapshots?page=110&per_page=1",
"next": "https://api.digitalocean.com/v2/snapshots?page=2&per_page=1"
}
},
"meta": {
"total": 110
}
}To retrieve only snapshots based on Droplets, include the resource_type query parameter set to droplet, /v2/snapshots?resource_type=droplet.
| Name | Type | Description |
|---|---|---|
| id | string | The unique identifier for the snapshot. |
| name | string | A human-readable name for the snapshot. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the snapshot was created. |
| regions | array | An array of the regions that the image is available in. The regions are represented by their identifying slug values. |
| resource_id | string | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| min_disk_size | integer | The minimum size in GB required for a volume or Droplet to use this snapshot. |
| size_gigabytes | integer | The billable size of the snapshot in gigabytes. |
curl -X GET -H 'Content-Type: application/json' -H 'Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582' "https://api.digitalocean.com/v2/snapshots?page=1&per_page=1&resource_type=droplet"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
snapshots, _, err := client.Snapshots.ListDroplet(ctx, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4988
ratelimit-reset: 1475174402{
"snapshots": [
{
"id": 19602538,
"name": "1153.4.0 (beta)",
"regions": [
"nyc1",
"sfo1",
"nyc2",
"ams2",
"sgp1",
"lon1",
"nyc3",
"ams3",
"fra1",
"tor1",
"sfo2",
"blr1"
],
"created_at": "2016-09-10T18:06:25Z",
"resource_id": null,
"resource_type": "droplet",
"min_disk_size": 20,
"size_gigabytes": 0.31
}
],
"links": {
"pages": {
"last": "https://api.digitalocean.com/v2/snapshots?page=103&per_page=1&resource_type=droplet",
"next": "https://api.digitalocean.com/v2/snapshots?page=2&per_page=1&resource_type=droplet"
}
},
"meta": {
"total": 103
}
}To retrieve only snapshots based on volumes, include the resource_type query parameter set to volume, /v2/snapshots?resource_type=volume.
| Name | Type | Description |
|---|---|---|
| id | string | The unique identifier for the snapshot. |
| name | string | A human-readable name for the snapshot. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the snapshot was created. |
| regions | array | An array of the regions that the image is available in. The regions are represented by their identifying slug values. |
| resource_id | string | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| min_disk_size | integer | The minimum size in GB required for a volume or Droplet to use this snapshot. |
| size_gigabytes | integer | The billable size of the snapshot in gigabytes. |
curl -X GET -H 'Content-Type: application/json' -H 'Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582' "https://api.digitalocean.com/v2/snapshots?page=1&per_page=1&resource_type=volume"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
snapshots, _, err := client.Snapshots.ListVolume(ctx, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4987
ratelimit-reset: 1475174402{
"snapshots": [
{
"id": "4f60fc64-85d1-11e6-a004-000f53315871",
"name": "big-data-snapshot1",
"regions": [
"nyc1"
],
"created_at": "2016-09-28T23:14:30Z",
"resource_id": "89bcc42f-85cf-11e6-a004-000f53315871",
"resource_type": "volume",
"min_disk_size": 10,
"size_gigabytes": 0
}
],
"links": {
"pages": {
"last": "https://api.digitalocean.com/v2/snapshots?page=7&per_page=1&resource_type=volume",
"next": "https://api.digitalocean.com/v2/snapshots?page=2&per_page=1&resource_type=volume"
}
},
"meta": {
"total": 7
}
}To retrieve information about a snapshot, send a GET request to /v2/snapshots/$SNAPSHOT_ID.
The response will be a JSON object with a key called snapshot. The value of this will be an snapshot object containing the standard snapshot attributes:
| Name | Type | Description |
|---|---|---|
| id | string | The unique identifier for the snapshot. |
| name | string | A human-readable name for the snapshot. |
| created_at | string | A time value given in ISO8601 combined date and time format that represents when the snapshot was created. |
| regions | array | An array of the regions that the image is available in. The regions are represented by their identifying slug values. |
| resource_id | string | A unique identifier for the resource that the action is associated with. |
| resource_type | string | The type of resource that the action is associated with. |
| min_disk_size | integer | The minimum size in GB required for a volume or Droplet to use this snapshot. |
| size_gigabytes | integer | The billable size of the snapshot in gigabytes. |
curl -X GET -H 'Content-Type: application/json' -H 'Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582' "https://api.digitalocean.com/v2/snapshots/fbe805e8-866b-11e6-96bf-000f53315a41"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4986
ratelimit-reset: 1475174402{
"snapshot": {
"id": "fbe805e8-866b-11e6-96bf-000f53315a41",
"name": "big-data-snapshot1475170902",
"regions": [
"nyc1"
],
"created_at": "2016-09-29T17:41:42Z",
"resource_id": "fbcbc5c8-866b-11e6-96bf-000f53315a41",
"resource_type": "volume",
"min_disk_size": 10,
"size_gigabytes": 0
}
}To delete a 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.
curl -X DELETE -H 'Content-Type: application/json' -H 'Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582' "https://api.digitalocean.com/v2/snapshots/fbe805e8-866b-11e6-96bf-000f53315a41"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()DigitalOcean allows you to add SSH public keys to the interface so that you can embed your public key into a Droplet at the time of creation. Only the public key is required to take advantage of this functionality.
| Name | Type | Description |
|---|---|---|
| id | integer | This is a unique identification number for the key. This can be used to reference a specific SSH key when you wish to embed a key into a Droplet. |
| fingerprint | string | This attribute contains the fingerprint value that is generated from the public key. This is a unique identifier that will differentiate it from other keys using a format that SSH recognizes. |
| public_key | string | This attribute contains the entire public key string that was uploaded. This is what is embedded into the root user's authorized_keys file if you choose to include this SSH key during Droplet creation. |
| name | string | This is the human-readable display name for the given SSH key. This is used to easily identify the SSH keys when they are displayed. |
To list all of the keys in your account, send a GET request to /v2/account/keys.
The response will be a JSON object with a key set to ssh_keys. The value of this will be an array of key objects, each of which contain the standard key attributes:
| Name | Type | Description |
|---|---|---|
| id | integer | This is a unique identification number for the key. This can be used to reference a specific SSH key when you wish to embed a key into a Droplet. |
| fingerprint | string | This attribute contains the fingerprint value that is generated from the public key. This is a unique identifier that will differentiate it from other keys using a format that SSH recognizes. |
| public_key | string | This attribute contains the entire public key string that was uploaded. This is what is embedded into the root user's authorized_keys file if you choose to include this SSH key during Droplet creation. |
| name | string | This is the human-readable display name for the given SSH key. This is used to easily identify the SSH keys when they are displayed. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/account/keys"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
keys, _, err := client.Keys.List(ctx, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 1200
ratelimit-remaining: 767
ratelimit-reset: 1415984218{
"ssh_keys": [
{
"id": 512189,
"fingerprint": "3b:16:bf:e4:8b:00:8b:b8:59:8c:a9:d3:f0:19:45:fa",
"public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAQQDDHr/jh2Jy4yALcK4JyWbVkPRaWmhck3IgCoeOO3z1e2dBowLh64QAM+Qb72pxekALga2oi4GvT+TlWNhzPH4V example",
"name": "My SSH Public Key"
}
],
"links": {
},
"meta": {
"total": 1
}
}To add a new SSH public key to your DigitalOcean account, send a POST request to /v2/account/keys. Set the "name" attribute to the name you wish to use and the "public_key" attribute to a string of the full public key you are adding.
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | The name to give the new SSH key in your account. | true |
| public_key | string | A string containing the entire public key. | true |
The response body will be a JSON object with a key set to ssh_key. The value will be the complete generated key object. This will have the standard key attributes:
| Name | Type | Description |
|---|---|---|
| id | integer | This is a unique identification number for the key. This can be used to reference a specific SSH key when you wish to embed a key into a Droplet. |
| fingerprint | string | This attribute contains the fingerprint value that is generated from the public key. This is a unique identifier that will differentiate it from other keys using a format that SSH recognizes. |
| public_key | string | This attribute contains the entire public key string that was uploaded. This is what is embedded into the root user's authorized_keys file if you choose to include this SSH key during Droplet creation. |
| name | string | This is the human-readable display name for the given SSH key. This is used to easily identify the SSH keys when they are displayed. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name":"My SSH Public Key","public_key":"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAQQDDHr/jh2Jy4yALcK4JyWbVkPRaWmhck3IgCoeOO3z1e2dBowLh64QAM+Qb72pxekALga2oi4GvT+TlWNhzPH4V example"}' "https://api.digitalocean.com/v2/account/keys"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)ssh_key = DropletKit::SSHKey.new(
name: 'My SSH Public Key',
public_key: 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAQQDDHr/jh2Jy4yALcK4JyWbVkPRaWmhck3IgCoeOO3z1e2dBowLh64QAM+Qb72pxekALga2oi4GvT+TlWNhzPH4V example'
)
client.ssh_keys.create(ssh_key)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()createRequest := &godo.KeyCreateRequest{
Name: "My SSH Public Key",
PublicKey: "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAQQDDHr/jh2Jy4yALcK4JyWbVkPRaWmhck3IgCoeOO3z1e2dBowLh64QAM+Qb72pxekALga2oi4GvT+TlWNhzPH4V example",
}
transfer, _, err := client.Keys.Create(ctx, createRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
{
"name": "My SSH Public Key",
"public_key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAQQDDHr/jh2Jy4yALcK4JyWbVkPRaWmhck3IgCoeOO3z1e2dBowLh64QAM+Qb72pxekALga2oi4GvT+TlWNhzPH4V example"
}To show information about a key, send a GET request to /v2/account/keys/$KEY_ID or /v2/account/keys/$KEY_FINGERPRINT.
The response will be a JSON object with a key called ssh_key. The value of this will be a key object which contains the standard key attributes:
| Name | Type | Description |
|---|---|---|
| id | integer | This is a unique identification number for the key. This can be used to reference a specific SSH key when you wish to embed a key into a Droplet. |
| fingerprint | string | This attribute contains the fingerprint value that is generated from the public key. This is a unique identifier that will differentiate it from other keys using a format that SSH recognizes. |
| public_key | string | This attribute contains the entire public key string that was uploaded. This is what is embedded into the root user's authorized_keys file if you choose to include this SSH key during Droplet creation. |
| name | string | This is the human-readable display name for the given SSH key. This is used to easily identify the SSH keys when they are displayed. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/account/keys/512190"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
To update the name of an SSH key, send a PUT request to either /v2/account/keys/$SSH_KEY_ID or /v2/account/keys/$SSH_KEY_FINGERPRINT. Set the "name" attribute to the new name you want to use.
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | The name to give the new SSH key in your account. | true |
The response body will be a JSON object with a key set to ssh_key. The value will be an ojbect that contains the standard key attributes:
| Name | Type | Description |
|---|---|---|
| id | integer | This is a unique identification number for the key. This can be used to reference a specific SSH key when you wish to embed a key into a Droplet. |
| fingerprint | string | This attribute contains the fingerprint value that is generated from the public key. This is a unique identifier that will differentiate it from other keys using a format that SSH recognizes. |
| public_key | string | This attribute contains the entire public key string that was uploaded. This is what is embedded into the root user's authorized_keys file if you choose to include this SSH key during Droplet creation. |
| name | string | This is the human-readable display name for the given SSH key. This is used to easily identify the SSH keys when they are displayed. |
curl -X PUT -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name":"Renamed SSH Key"}' "https://api.digitalocean.com/v2/account/keys/512190"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)ssh_key = DropletKit::SSHKey.new(name: 'Renamed SSH Key')
client.ssh_keys.update(ssh_key, id: 512190)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()updateRequest := &godo.KeyUpdateRequest{
Name: "Renamed SSH Key",
}
key, _, err := client.Keys.UpdateByID(ctx, 512190, updateRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
To destroy a public SSH key that you have in your account, send a DELETE request to /v2/account/keys/$KEY_ID or /v2/account/keys/$KEY_FINGERPRINT.
A 204 status will be returned, indicating that the action was successful and that the response body is empty.
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/account/keys/512190"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()A Tag is a label that can be applied to a resource (currently only Droplets and Images) in order to better organize or facilitate the lookups and actions on it.
Tags have two attributes: a user defined name attribute and an embedded resources attribute with information about resources that have been tagged.
| Name | Type | Description |
|---|---|---|
| name | string | Tags may contain letters, numbers, colons, dashes, and underscores. There is a limit of 255 characters per tag. |
| resources | object | An embedded object containing key value pairs of resource type and resource statistics. It also includes a count of the total number of resources tagged with the current tag as well as a last_tagged_uri attribute set to the last resource tagged with the current tag. |
Tagged Resource Statistics include metadata regarding the resource type that has been tagged.
| Name | Type | Description |
|---|---|---|
| count | integer | The number tagged objects for this type of resource. |
| last_tagged_uri | string | The URI for the last tagged object for this type of resource. |
| last_tagged | object | (Deprecated - Scheduled for removal on March 1st 2019) When the resource type is "droplet", a full representation of the last tagged object. |
To create a Tag you can send a POST request to /v2/tags with a name attribute.
| Name | Type | Description |
|---|---|---|
| name | string | The name of the tag. |
The response will be a JSON object with a key called tag. The value of this will be a tag object containing the standard tag attributes:
| Name | Type | Description |
|---|---|---|
| name | string | Tags may contain letters, numbers, colons, dashes, and underscores. There is a limit of 255 characters per tag. |
| resources | object | An embedded object containing key value pairs of resource type and resource statistics. It also includes a count of the total number of resources tagged with the current tag as well as a last_tagged_uri attribute set to the last resource tagged with the current tag. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"name":"awesome"}' "https://api.digitalocean.com/v2/tags"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()createRequest := &TagCreateRequest{
Name: "testing-1",
}
client.Tags.Create(ctx, request)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
To retrieve an individual tag, you can send a GET request to /v2/tags/$TAG_NAME.
The response will be a JSON object with a key called tag. The value of this will be a tag object containing the standard tag attributes:
| Name | Type | Description |
|---|---|---|
| name | string | Tags may contain letters, numbers, colons, dashes, and underscores. There is a limit of 255 characters per tag. |
| resources | object | An embedded object containing key value pairs of resource type and resource statistics. It also includes a count of the total number of resources tagged with the current tag as well as a last_tagged_uri attribute set to the last resource tagged with the current tag. |
| Name | Type | Description |
|---|---|---|
| count | integer | The number tagged objects for this type of resource. |
| last_tagged_uri | string | The URI for the last tagged object for this type of resource. |
| last_tagged | object | (Deprecated - Scheduled for removal on March 1st 2019) When the resource type is "droplet", a full representation of the last tagged object. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/tags/awesome"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4986
ratelimit-reset: 1450713671{
"tag": {
"name": "extra-awesome",
"resources": {
"count": 2,
"last_tagged_uri": "https://api.digitalocean.com/v2/images/7555620",
"droplets": {
"count": 1,
"last_tagged_uri": "https://api.digitalocean.com/v2/droplets/3164444",
"last_tagged": {
"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": [
"extra-awesome"
]
}
},
"images": {
"count": 1,
"last_tagged_uri": "https://api.digitalocean.com/v2/images/7555620"
}
}
}
}To list all of your tags, you can send a GET request to /v2/tags.
The response will be a JSON object with a key called tags. This will be set to an array of tag objects, each of which will contain the standard tag attributes:
| Name | Type | Description |
|---|---|---|
| name | string | Tags may contain letters, numbers, colons, dashes, and underscores. There is a limit of 255 characters per tag. |
| resources | object | An embedded object containing key value pairs of resource type and resource statistics. It also includes a count of the total number of resources tagged with the current tag as well as a last_tagged_uri attribute set to the last resource tagged with the current tag. |
| Name | Type | Description |
|---|---|---|
| count | integer | The number tagged objects for this type of resource. |
| last_tagged_uri | string | The URI for the last tagged object for this type of resource. |
| last_tagged | object | (Deprecated - Scheduled for removal on March 1st 2019) When the resource type is "droplet", a full representation of the last tagged object. |
curl -X GET -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/tags"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()opt := &godo.ListOptions{
Page: 1,
PerPage: 200,
}
tags, _, err := client.Tags.List(ctx, opt)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
content-type: application/json; charset=utf-8
status: 200 OK
ratelimit-limit: 5000
ratelimit-remaining: 4986
ratelimit-reset: 1450713671{
"tags": [
{
"name": "extra-awesome",
"resources": {
"count": 2,
"last_tagged_uri": "https://api.digitalocean.com/v2/images/7555620",
"droplets": {
"count": 1,
"last_tagged_uri": "https://api.digitalocean.com/v2/droplets/3164444",
"last_tagged": {
"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": [
"extra-awesome"
]
}
},
"images": {
"count": 1,
"last_tagged_uri": "https://api.digitalocean.com/v2/images/7555620"
}
}
}
]
}Resources can be tagged by sending a POST request to /v2/tags/$TAG_NAME/resources with an array of json objects containing resource_id and resource_type attributes.
Currently only tagging of Droplets and Images is supported. resource_id is expected to be the Droplet's id or Image's id attribute as a string, and resource_type is expected to be the string droplet or image.
| Name | Type | Description |
|---|---|---|
| resources | array | An array of objects containing resource_id and resource_type attributes. |
| Name | Type | Description |
|---|---|---|
| resource_id | string | The identifier of a resource. |
| resource_type | string | The type of the resource. |
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"resources":[{"resource_id":"9569411","resource_type":"droplet"},{"resource_id":"7555620","resource_type":"image"}]}' "https://api.digitalocean.com/v2/tags/awesome/resources"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)client.tags.tag_resources(name: 'awesome', resources: [{ resource_id => '9569411', resource_type: 'droplet' },{ resource_id => '7555620', resource_type: 'image' }])import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()tagResourcesRequest := &godo.TagResourcesRequest{
Resources: []Resource{{ID: "11457573", Type: "droplet"},{ID: "7555620", Type: "image"}},
}
client.Tags.TagResources(ctx, "awesome", tagResourcesRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
Resources can be untagged by sending a DELETE request to /v2/tags/$TAG_NAME/resources with an array of json objects containing resource_id and resource_type attributes.
Currently only untagging Droplets and Images is supported. resource_id is expected to be the Droplet's id or Image's id attribute as a string, and resource_type is expected to be the string droplet or image.
| Name | Type | Description |
|---|---|---|
| resources | array | An array of objects containing resource_id and resource_type attributes. |
| Name | Type | Description |
|---|---|---|
| resource_id | string | The identifier of a resource. |
| resource_type | string | The type of the resource. |
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" -d '{"resources":[{"resource_id":"9569411","resource_type":"droplet"},{"resource_id":"7555620","resource_type":"image"}]}' "https://api.digitalocean.com/v2/tags/awesome/resources"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)client.tags.untag_resources(name: 'awesome', resources: [{ resource_id => '9569411', resource_type: 'droplet' },{ resource_id => '7555620', resource_type: 'image' }])import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()untagResourcesRequest := &godo.UntagResourcesRequest{
Resources: []Resource{{ID: "11457573", Type: "droplet"},{ID: "7555620", Type: "image"}},
}
client.Tags.UntagResources(ctx, "awesome", untagResourcesRequest)Content-Type: application/json
Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582
A Tag can be deleted by sending a DELETE request to /v2/tags/$TAG_NAME. Deleting a Tag also untags all the resources that have previously been tagged by the Tag.
curl -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer b7d03a6947b217efb6f3ec3bd3504582" "https://api.digitalocean.com/v2/tags/awesome"require 'droplet_kit'
token = '16f79fc8cd5adcfe528a0994311fa63cc877737b385b6ff7d12ed6684ba4fef5'
client = DropletKit::Client.new(access_token: token)import (
"context"
"golang.org/x/oauth2"
"github.com/digitalocean/godo"
)
pat := "mytoken"
type TokenSource struct {
AccessToken string
}
func (t *TokenSource) Token() (*oauth2.Token, error) {
token := &oauth2.Token{
AccessToken: t.AccessToken,
}
return token, nil
}
tokenSource := &TokenSource{
AccessToken: pat,
}
oauthClient := oauth2.NewClient(oauth2.NoContext, tokenSource)
client := godo.NewClient(oauthClient)
ctx := context.TODO()