openapi: 3.0.0 info: title: DigitalOcean Droplets API version: '2.0' description: "# Introduction\n\nThe DigitalOcean API allows you to manage Droplets and resources within the\nDigitalOcean cloud in a simple, programmatic way using conventional HTTP requests.\n\nAll of the functionality that you are familiar with in the DigitalOcean\ncontrol panel is also available through the API, allowing you to script the\ncomplex actions that your situation requires.\n\nThe API documentation will start with a general overview about the design\nand technology that has been implemented, followed by reference information\nabout specific endpoints.\n\n## Requests\n\nAny tool that is fluent in HTTP can communicate with the API simply by\nrequesting the correct URI. Requests should be made using the HTTPS protocol\nso that traffic is encrypted. The interface responds to different methods\ndepending on the action required.\n\n|Method|Usage|\n|--- |--- |\n|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.|\n|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.|\n|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.|\n|PATCH|Some resources support partial modification. In these cases, the PATCH method is available. Unlike PUT which generally requires a complete representation of a resource, a PATCH request is a set of instructions on how to modify a resource updating only specific attributes.|\n|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.|\n|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.|\n\n\n## HTTP Statuses\n\nAlong with the HTTP methods that the API responds to, it will also return\nstandard HTTP statuses, including error codes.\n\nIn the event of a problem, the status will contain the error code, while the\nbody of the response will usually contain additional information about the\nproblem that was encountered.\n\nIn general, if the status returned is in the 200 range, it indicates that\nthe request was fulfilled successfully and that no error was encountered.\n\nReturn codes in the 400 range typically indicate that there was an issue\nwith the request that was sent. Among other things, this could mean that you\ndid not authenticate correctly, that you are requesting an action that you\ndo not have authorization for, that the object you are requesting does not\nexist, or that your request is malformed.\n\nIf you receive a status in the 500 range, this generally indicates a\nserver-side problem. This means that we are having an issue on our end and\ncannot fulfill your request currently.\n\n400 and 500 level error responses will include a JSON object in their body,\nincluding the following attributes:\n\n|Name|Type|Description|\n|--- |--- |--- |\n|id|string|A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be \"not_found.\"|\n|message|string|A message providing additional information about the error, including details to help resolve it when possible.|\n|request_id|string|Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.|\n\n### Example Error Response\n\n```\n HTTP/1.1 403 Forbidden\n {\n \"id\": \"forbidden\",\n \"message\": \"You do not have access for the attempted action.\"\n }\n```\n\n## Responses\n\nWhen a request is successful, a response body will typically be sent back in\nthe form of a JSON object. An exception to this is when a DELETE request is\nprocessed, which will result in a successful HTTP 204 status and an empty\nresponse body.\n\nInside of this JSON object, the resource root that was the target of the\nrequest will be set as the key. This will be the singular form of the word\nif the request operated on a single object, and the plural form of the word\nif a collection was processed.\n\nFor example, if you send a GET request to `/v2/droplets/$DROPLET_ID` you\nwill get back an object with a key called \"`droplet`\". However, if you send\nthe GET request to the general collection at `/v2/droplets`, you will get\nback an object with a key called \"`droplets`\".\n\nThe value of these keys will generally be a JSON object for a request on a\nsingle object and an array of objects for a request on a collection of\nobjects.\n\n### Response for a Single Object\n\n```json\n {\n \"droplet\": {\n \"name\": \"example.com\"\n . . .\n }\n }\n```\n\n### Response for an Object Collection\n\n```json\n {\n \"droplets\": [\n {\n \"name\": \"example.com\"\n . . .\n },\n {\n \"name\": \"second.com\"\n . . .\n }\n ]\n }\n```\n\n## Meta\n\nIn addition to the main resource root, the response may also contain a\n`meta` object. This object contains information about the response itself.\n\nThe `meta` object contains a `total` key that is set to the total number of\nobjects returned by the request. This has implications on the `links` object\nand pagination.\n\nThe `meta` object will only be displayed when it has a value. Currently, the\n`meta` object will have a value when a request is made on a collection (like\n`droplets` or `domains`).\n\n\n### Sample Meta Object\n\n```json\n {\n . . .\n \"meta\": {\n \"total\": 43\n }\n . . .\n }\n```\n\n## Links & Pagination\n\nThe `links` object is returned as part of the response body when pagination\nis enabled. By default, 20 objects are returned per page. If the response\ncontains 20 objects or fewer, no `links` object will be returned. If the\nresponse contains more than 20 objects, the first 20 will be returned along\nwith the `links` object.\n\nYou can request a different pagination limit or force pagination by\nappending `?per_page=` to the request with the number of items you would\nlike per page. For instance, to show only two results per page, you could\nadd `?per_page=2` to the end of your query. The maximum number of results\nper page is 200.\n\nThe `links` object contains a `pages` object. The `pages` object, in turn,\ncontains keys indicating the relationship of additional pages. The values of\nthese are the URLs of the associated pages. The keys will be one of the\nfollowing:\n\n* **first**: The URI of the first page of results.\n* **prev**: The URI of the previous sequential page of results.\n* **next**: The URI of the next sequential page of results.\n* **last**: The URI of the last page of results.\n\nThe `pages` object will only include the links that make sense. So for the\nfirst page of results, no `first` or `prev` links will ever be set. This\nconvention holds true in other situations where a link would not make sense.\n\n### Sample Links Object\n\n```json\n {\n . . .\n \"links\": {\n \"pages\": {\n \"last\": \"https://api.digitalocean.com/v2/images?page=2\",\n \"next\": \"https://api.digitalocean.com/v2/images?page=2\"\n }\n }\n . . .\n }\n```\n\n## Rate Limit\n\nRequests through the API are rate limited per OAuth token. Current rate limits:\n\n* 5,000 requests per hour\n* 250 requests per minute (5% of the hourly total)\n\nOnce you exceed either limit, you will be rate limited until the next cycle\nstarts. Space out any requests that you would otherwise issue in bursts for\nthe best results.\n\nThe rate limiting information is contained within the response headers of\neach request. The relevant headers are:\n\n* **ratelimit-limit**: The number of requests that can be made per hour.\n* **ratelimit-remaining**: The number of requests that remain before you hit your request limit. See the information below for how the request limits expire.\n* **ratelimit-reset**: This represents the time when the oldest request will expire. The value is given in [Unix epoch time](http://en.wikipedia.org/wiki/Unix_time). See below for more information about how request limits expire.\n\nMore rate limiting information is returned only within burst limit error response headers:\n* **retry-after**: The number of seconds to wait before making another request when rate limited.\n\nAs long as the `ratelimit-remaining` count is above zero, you will be able\nto make additional requests.\n\nThe way that a request expires and is removed from the current limit count\nis important to understand. Rather than counting all of the requests for an\nhour and resetting the `ratelimit-remaining` value at the end of the hour,\neach request instead has its own timer.\n\nThis means that each request contributes toward the `ratelimit-remaining`\ncount for one complete hour after the request is made. When that request's\ntimer runs out, it is no longer counted towards the request limit.\n\nThis has implications on the meaning of the `ratelimit-reset` header as\nwell. Because the entire rate limit is not reset at one time, the value of\nthis header is set to the time when the _oldest_ request will expire.\n\nKeep this in mind if you see your `ratelimit-reset` value change, but not\nmove an entire hour into the future.\n\nIf the `ratelimit-remaining` reaches zero, subsequent requests will receive\na 429 error code until the request reset has been reached. \n\n`ratelimit-remaining` reaching zero can also indicate that the \"burst limit\" of 250 \nrequests per minute limit was met, even if the 5,000 requests per hour limit was not. \nIn this case, the 429 error response will include a `retry-after` header to indicate how \nlong to wait (in seconds) until the request may be retried.\n\nYou can see the format of the response in the examples. \n\n**Note:** The following endpoints have special rate limit requirements that\nare independent of the limits defined above.\n\n* Only 12 `POST` requests to the `/v2/floating_ips` endpoint to create Floating IPs can be made per 60 seconds.\n* Only 10 `GET` requests to the `/v2/account/keys` endpoint to list SSH keys can be made per 60 seconds.\n* Only 5 requests to any and all `v2/cdn/endpoints` can be made per 10 seconds. This includes `v2/cdn/endpoints`, \n `v2/cdn/endpoints/$ENDPOINT_ID`, and `v2/cdn/endpoints/$ENDPOINT_ID/cache`.\n* Only 50 strings within the `files` json struct in the `v2/cdn/endpoints/$ENDPOINT_ID/cache` [payload](https://docs.digitalocean.com/reference/api/api-reference/#operation/cdn_purge_cache) \n can be requested every 20 seconds.\n\n### Sample Rate Limit Headers\n\n```\n . . .\n ratelimit-limit: 1200\n ratelimit-remaining: 1193\n rateLimit-reset: 1402425459\n . . .\n```\n\n ### Sample Rate Limit Headers When Burst Limit is Reached:\n\n```\n . . .\n ratelimit-limit: 5000\n ratelimit-remaining: 0\n rateLimit-reset: 1402425459\n retry-after: 29\n . . .\n```\n\n### Sample Rate Exceeded Response\n\n```\n 429 Too Many Requests\n {\n id: \"too_many_requests\",\n message: \"API Rate limit exceeded.\"\n }\n```\n\n## Curl Examples\n\nThroughout this document, some example API requests will be given using the\n`curl` command. This will allow us to demonstrate the various endpoints in a\nsimple, textual format.\n \n These examples assume that you are using a Linux or macOS command line. To run\nthese commands on a Windows machine, you can either use cmd.exe, PowerShell, or WSL:\n\n* For cmd.exe, use the `set VAR=VALUE` [syntax](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/set_1)\nto define environment variables, call them with `%VAR%`, then replace all backslashes (`\\`) in the examples with carets (`^`).\n\n* For PowerShell, use the `$Env:VAR = \"VALUE\"` [syntax](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7.2)\nto define environment variables, call them with `$Env:VAR`, then replace `curl` with `curl.exe` and all backslashes (`\\`) in the examples with backticks (`` ` ``).\n\n* WSL is a compatibility layer that allows you to emulate a Linux terminal on a Windows machine.\nInstall WSL with our [community tutorial](https://www.digitalocean.com/community/tutorials/how-to-install-the-windows-subsystem-for-linux-2-on-microsoft-windows-10), \nthen follow this API documentation normally.\n\nThe names of account-specific references (like Droplet IDs, for instance)\nwill be represented by variables. For instance, a Droplet ID may be\nrepresented by a variable called `$DROPLET_ID`. You can set the associated\nvariables in your environment if you wish to use the examples without\nmodification.\n\nThe first variable that you should set to get started is your OAuth\nauthorization token. The next section will go over the details of this, but\nyou can set an environmental variable for it now.\n\nGenerate a token by going to the [Apps & API](https://cloud.digitalocean.com/settings/applications)\nsection of the DigitalOcean control panel. Use an existing token if you have\nsaved one, or generate a new token with the \"Generate new token\" button.\nCopy the generated token and use it to set and export the TOKEN variable in\nyour environment as the example shows.\n\nYou may also wish to set some other variables now or as you go along. For\nexample, you may wish to set the `DROPLET_ID` variable to one of your\nDroplet IDs since this will be used frequently in the API.\n\nIf you are following along, make sure you use a Droplet ID that you control\nso that your commands will execute correctly.\n\nIf you need access to the headers of a response through `curl`, you can pass\nthe `-i` flag to display the header information along with the body. If you\nare only interested in the header, you can instead pass the `-I` flag, which\nwill exclude the response body entirely.\n\n\n### Set and Export your OAuth Token\n\n```\nexport DIGITALOCEAN_TOKEN=your_token_here\n```\n\n### Set and Export a Variable\n\n```\nexport DROPLET_ID=1111111\n```\n\n## Parameters\n\nThere are two different ways to pass parameters in a request with the API.\n\nWhen passing parameters to create or update an object, parameters should be\npassed as a JSON object containing the appropriate attribute names and\nvalues as key-value pairs. When you use this format, you should specify that\nyou are sending a JSON object in the header. This is done by setting the\n`Content-Type` header to `application/json`. This ensures that your request\nis interpreted correctly.\n\nWhen passing parameters to filter a response on GET requests, parameters can\nbe passed using standard query attributes. In this case, the parameters\nwould be embedded into the URI itself by appending a `?` to the end of the\nURI and then setting each attribute with an equal sign. Attributes can be\nseparated with a `&`. Tools like `curl` can create the appropriate URI when\ngiven parameters and values; this can also be done using the `-F` flag and\nthen passing the key and value as an argument. The argument should take the\nform of a quoted string with the attribute being set to a value with an\nequal sign.\n\n### Pass Parameters as a JSON Object\n\n```\n curl -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"example.com\", \"ip_address\": \"127.0.0.1\"}' \\\n -X POST \"https://api.digitalocean.com/v2/domains\"\n```\n\n### Pass Filter Parameters as a Query String\n\n```\n curl -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n -X GET \\\n \"https://api.digitalocean.com/v2/images?private=true\"\n```\n\n## Cross Origin Resource Sharing\n\nIn order to make requests to the API from other domains, the API implements\nCross Origin Resource Sharing (CORS) support.\n\nCORS support is generally used to create AJAX requests outside of the domain\nthat the request originated from. This is necessary to implement projects\nlike control panels utilizing the API. This tells the browser that it can\nsend requests to an outside domain.\n\nThe procedure that the browser initiates in order to perform these actions\n(other than GET requests) begins by sending a \"preflight\" request. This sets\nthe `Origin` header and uses the `OPTIONS` method. The server will reply\nback with the methods it allows and some of the limits it imposes. The\nclient then sends the actual request if it falls within the allowed\nconstraints.\n\nThis process is usually done in the background by the browser, but you can\nuse curl to emulate this process using the example provided. The headers\nthat will be set to show the constraints are:\n\n* **Access-Control-Allow-Origin**: This is the domain that is sent by the client or browser as the origin of the request. It is set through an `Origin` header.\n* **Access-Control-Allow-Methods**: This specifies the allowed options for requests from that domain. This will generally be all available methods.\n* **Access-Control-Expose-Headers**: This will contain the headers that will be available to requests from the origin domain.\n* **Access-Control-Max-Age**: This is the length of time that the access is considered valid. After this expires, a new preflight should be sent.\n* **Access-Control-Allow-Credentials**: This will be set to `true`. It basically allows you to send your OAuth token for authentication.\n\nYou should not need to be concerned with the details of these headers,\nbecause the browser will typically do all of the work for you.\n" license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html contact: name: DigitalOcean API Team email: api-engineering@digitalocean.com termsOfService: https://www.digitalocean.com/legal/terms-of-service-agreement/ servers: - url: https://api.digitalocean.com description: production security: - bearer_auth: [] tags: - name: Droplets description: 'A [Droplet](https://docs.digitalocean.com/products/droplets/) 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.' paths: /v2/droplets: get: operationId: droplets_list summary: List All Droplets description: 'To list all Droplets in your account, send a GET request to `/v2/droplets`. The response body will be a JSON object with a key of `droplets`. This will be set to an array containing objects each representing a Droplet. These will contain the standard Droplet attributes. ### Filtering Results by Tag It''s possible to request filtered results by including certain query parameters. To only list Droplets assigned to a specific tag, include the `tag_name` query parameter set to the name of the tag in your GET request. For example, `/v2/droplets?tag_name=$TAG_NAME`. ### GPU Droplets By default, only non-GPU Droplets are returned. To list only GPU Droplets, set the `type` query parameter to `gpus`. For example, `/v2/droplets?type=gpus`. ' tags: - Droplets parameters: - $ref: '#/components/parameters/per_page' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/droplet_tag_name' - $ref: '#/components/parameters/droplet_name' - $ref: '#/components/parameters/droplet_type' responses: '200': $ref: '#/components/responses/all_droplets' '401': $ref: '#/components/responses/unauthorized' '429': $ref: '#/components/responses/too_many_requests' '500': $ref: '#/components/responses/server_error' default: $ref: '#/components/responses/unexpected_error' x-codeSamples: - lang: cURL source: "curl -X GET \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/droplets?page=1&per_page=1\"" - lang: Go source: "import (\n \"context\"\n \"os\"\n\n \"github.com/digitalocean/godo\"\n)\n\nfunc main() {\n token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n client := godo.NewFromToken(token)\n ctx := context.TODO()\n\n opt := &godo.ListOptions{\n Page: 1,\n PerPage: 200,\n }\n\n droplets, _, err := client.Droplets.List(ctx, opt)\n}" - lang: Ruby source: 'require ''droplet_kit'' token = ENV[''DIGITALOCEAN_TOKEN''] client = DropletKit::Client.new(access_token: token) droplets = client.droplets.all droplets.each' - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.droplets.list()' security: - bearer_auth: - droplet:read post: operationId: droplets_create summary: Create a New Droplet description: 'To create a new Droplet, send a POST request to `/v2/droplets` setting the required attributes. A Droplet will be created using the provided information. The response body will contain a JSON object with a key called `droplet`. The value will be an object containing the standard attributes for your new Droplet. The response code, 202 Accepted, does not indicate the success or failure of the operation, just that the request has been accepted for processing. The `actions` returned as part of the response''s `links` object can be used to check the status of the Droplet create event. ### Create Multiple Droplets Creating multiple Droplets is very similar to creating a single Droplet. Instead of sending `name` as a string, send `names` as an array of strings. A Droplet will be created for each name you send using the associated information. Up to ten Droplets may be created this way at a time. Rather than returning a single Droplet, the response body will contain a JSON array with a key called `droplets`. This will be set to an array of JSON objects, each of which will contain the standard Droplet attributes. The response code, 202 Accepted, does not indicate the success or failure of any operation, just that the request has been accepted for processing. The array of `actions` returned as part of the response''s `links` object can be used to check the status of each individual Droplet create event. ' tags: - Droplets requestBody: content: application/json: schema: oneOf: - $ref: '#/components/schemas/droplet_single_create' - $ref: '#/components/schemas/droplet_multi_create' examples: Single Droplet Create Request: $ref: '#/components/examples/droplet_create_request' Multiple Droplet Create Request: $ref: '#/components/examples/droplet_multi_create_request' responses: '202': $ref: '#/components/responses/droplet_create' '401': $ref: '#/components/responses/unauthorized' '429': $ref: '#/components/responses/too_many_requests' '500': $ref: '#/components/responses/server_error' default: $ref: '#/components/responses/unexpected_error' x-codeSamples: - lang: cURL source: "curl -X POST \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n -d '{\"name\":\"example.com\",\"region\":\"nyc3\",\"size\":\"s-1vcpu-1gb\",\"image\":\"ubuntu-20-04-x64\",\"ssh_keys\":[289794,\"3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45\"],\"backups\":true,\"ipv6\":true,\"monitoring\":true,\"tags\":[\"env:prod\",\"web\"],\"user_data\":\"#cloud-config\\nruncmd:\\n - touch /test.txt\\n\",\"vpc_uuid\":\"760e09ef-dc84-11e8-981e-3cfdfeaae000\"}' \\\n \"https://api.digitalocean.com/v2/droplets\"" - lang: Go source: "import (\n \"context\"\n \"os\"\n\n \"github.com/digitalocean/godo\"\n)\n\nfunc main() {\n token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n client := godo.NewFromToken(token)\n ctx := context.TODO()\n\n createRequest := &godo.DropletCreateRequest{\n Name: \"example.com\",\n Region: \"nyc3\",\n Size: \"s-1vcpu-1gb\",\n Image: godo.DropletCreateImage{\n Slug: \"ubuntu-20-04-x64\",\n },\n SSHKeys: []godo.DropletCreateSSHKey{\n godo.DropletCreateSSHKey{ID: 289794},\n godo.DropletCreateSSHKey{Fingerprint: \"3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45\"}\n },\n Backups: true,\n IPv6: true,\n Monitoring: true,\n Tags: []string{\"env:prod\",\"web\"},\n UserData: \"#cloud-config\\nruncmd:\\n - touch /test.txt\\n\",\n VPCUUID: \"760e09ef-dc84-11e8-981e-3cfdfeaae000\",\n }" - lang: Ruby source: "require 'droplet_kit'\ntoken = ENV['DIGITALOCEAN_TOKEN']\nclient = DropletKit::Client.new(access_token: token)\n\ndroplet = DropletKit::Droplet.new(\n name: 'example.com',\n region: 'nyc3',\n size: 's-1vcpu-1gb',\n image: 'ubuntu-20-04-x64',\n ssh_keys: [289794,\"3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45\"],\n backups: true,\n ipv6: true,\n monitoring: true,\n tags: [\"env:prod\",\"web\"],\n user_data: \"#cloud-config\\nruncmd:\\n - touch /test.txt\\n\",\n vpc_uuid: \"760e09ef-dc84-11e8-981e-3cfdfeaae000\",\n)\nclient.droplets.create(droplet)" - lang: Python source: "import os\nfrom pydo import Client\n\nclient = Client(token=os.environ.get(\"DIGITALOCEAN_TOKEN\"))\n\nreq = {\n \"name\": \"example.com\",\n \"region\": \"nyc3\",\n \"size\": \"s-1vcpu-1gb\",\n \"image\": \"ubuntu-20-04-x64\",\n \"ssh_keys\": [\n 289794,\n \"3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45\"\n ],\n \"backups\": True,\n \"ipv6\": True,\n \"monitoring\": True,\n \"tags\": [\n \"env:prod\",\n \"web\"\n ],\n \"user_data\": \"#cloud-config\\nruncmd:\\n - touch /test.txt\\n\",\n \"vpc_uuid\": \"760e09ef-dc84-11e8-981e-3cfdfeaae000\"\n}\n\nresp = client.droplets.create(body=req)" security: - bearer_auth: - droplet:create delete: operationId: droplets_destroy_byTag summary: Deleting Droplets by Tag description: 'To delete **all** Droplets assigned to a specific tag, include the `tag_name` query parameter set to the name of the tag in your DELETE request. For example, `/v2/droplets?tag_name=$TAG_NAME`. A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully. ' tags: - Droplets parameters: - $ref: '#/components/parameters/droplet_delete_tag_name' responses: '204': $ref: '#/components/responses/no_content_with_content_type' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found' '429': $ref: '#/components/responses/too_many_requests' '500': $ref: '#/components/responses/server_error' default: $ref: '#/components/responses/unexpected_error' x-codeSamples: - lang: cURL source: "curl -X DELETE \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/droplets?tag_name=awesome\"" - lang: Go source: "import (\n \"context\"\n \"os\"\n\n \"github.com/digitalocean/godo\"\n)\n\nfunc main() {\n token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n client := godo.NewFromToken(token)\n ctx := context.TODO()\n\n client.Droplets.DeleteByTag(ctx, \"awesome\") \n}" - lang: Ruby source: 'require ''droplet_kit'' token = ENV[''DIGITALOCEAN_TOKEN''] client = DropletKit::Client.new(access_token: token) client.droplets.delete_for_tag(tag_name: awesome)' - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.droplets.destroy_by_tag(tag_name="production")' security: - bearer_auth: - droplet:delete /v2/droplets/{droplet_id}: get: operationId: droplets_get summary: Retrieve an Existing Droplet description: 'To show information about an individual Droplet, send a GET request to `/v2/droplets/$DROPLET_ID`. ' tags: - Droplets parameters: - $ref: '#/components/parameters/droplet_id' responses: '200': $ref: '#/components/responses/existing_droplet' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found' '429': $ref: '#/components/responses/too_many_requests' '500': $ref: '#/components/responses/server_error' default: $ref: '#/components/responses/unexpected_error' x-codeSamples: - lang: cURL source: "curl -X GET \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/droplets/3164494\"" - lang: Go source: "import (\n \"context\"\n \"os\"\n\n \"github.com/digitalocean/godo\"\n)\n\nfunc main() {\n token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n client := godo.NewFromToken(token)\n ctx := context.TODO()\n\n droplet, _, err := client.Droplets.Get(ctx, 3164494)\n}" - lang: Ruby source: 'require ''droplet_kit'' token = ENV[''DIGITALOCEAN_TOKEN''] client = DropletKit::Client.new(access_token: token) client.droplets.find(id: 3164494)' - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.droplets.get(droplet_id=594828)' security: - bearer_auth: - droplet:read delete: operationId: droplets_destroy summary: Delete an Existing Droplet description: 'To delete a Droplet, send a DELETE request to `/v2/droplets/$DROPLET_ID`. A successful request will receive a 204 status code with no body in response. This indicates that the request was processed successfully. ' tags: - Droplets parameters: - $ref: '#/components/parameters/droplet_id' responses: '204': $ref: '#/components/responses/no_content_with_content_type' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found' '429': $ref: '#/components/responses/too_many_requests' '500': $ref: '#/components/responses/server_error' default: $ref: '#/components/responses/unexpected_error' x-codeSamples: - lang: cURL source: "curl -X DELETE \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/droplets/3164494\"" - lang: Go source: "import (\n \"context\"\n \"os\"\n\n \"github.com/digitalocean/godo\"\n)\n\nfunc main() {\n token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n client := godo.NewFromToken(token)\n ctx := context.TODO()\n\n _, err := client.Droplets.Delete(ctx, 3164494)\n}" - lang: Ruby source: 'require ''droplet_kit'' token = ENV[''DIGITALOCEAN_TOKEN''] client = DropletKit::Client.new(access_token: token) client.droplets.delete(id: 3164494)' - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.droplets.destroy(droplet_id=553456)' security: - bearer_auth: - droplet:delete /v2/droplets/{droplet_id}/backups: get: operationId: droplets_list_backups summary: List Backups for a Droplet description: 'To retrieve any backups associated with a Droplet, send a GET request to `/v2/droplets/$DROPLET_ID/backups`. You will get back a JSON object that has a `backups` key. This will be set to an array of backup objects, each of which contain the standard Droplet backup attributes. ' tags: - Droplets parameters: - $ref: '#/components/parameters/droplet_id' - $ref: '#/components/parameters/per_page' - $ref: '#/components/parameters/page' responses: '200': $ref: '#/components/responses/all_droplet_backups' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found' '429': $ref: '#/components/responses/too_many_requests' '500': $ref: '#/components/responses/server_error' default: $ref: '#/components/responses/unexpected_error' x-codeSamples: - lang: cURL source: "curl -X GET \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/droplets/3067509/backups\"" - lang: Go source: "import (\n \"context\"\n \"os\"\n\n \"github.com/digitalocean/godo\"\n)\n\nfunc main() {\n token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n client := godo.NewFromToken(token)\n ctx := context.TODO()\n\n opt := &godo.ListOptions{\n Page: 1,\n PerPage: 200,\n }\n\n backups, _, err := client.Droplets.Backups(ctx, 3164494, opt)\n}" - lang: Ruby source: 'require ''droplet_kit'' token = ENV[''DIGITALOCEAN_TOKEN''] client = DropletKit::Client.new(access_token: token) backups = client.droplets.backups(id: 3164494) backups.each' - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.droplets.list_backups(droplet_id=594828)' security: - bearer_auth: - droplet:read /v2/droplets/{droplet_id}/backups/policy: get: operationId: droplets_get_backup_policy summary: Retrieve the Backup Policy for an Existing Droplet description: 'To show information about an individual Droplet''s backup policy, send a GET request to `/v2/droplets/$DROPLET_ID/backups/policy`. ' tags: - Droplets parameters: - $ref: '#/components/parameters/droplet_id' responses: '200': $ref: '#/components/responses/droplet_backup_policy' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found' '429': $ref: '#/components/responses/too_many_requests' '500': $ref: '#/components/responses/server_error' default: $ref: '#/components/responses/unexpected_error' x-codeSamples: - lang: cURL source: "curl -X GET \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/droplets/3164494/backups/policy\"" - lang: Go source: "import (\n \"context\"\n \"os\"\n\n \"github.com/digitalocean/godo\"\n)\n\nfunc main() {\n token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n client := godo.NewFromToken(token)\n ctx := context.TODO()\n\n droplet, _, err := client.Droplets.GetBackupPolicy(ctx, 444909706)\n}" - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.droplets.get_backup_policy(droplet_id=444909706)' security: - bearer_auth: - droplet:read /v2/droplets/backups/policies: get: operationId: droplets_list_backup_policies summary: List Backup Policies for All Existing Droplets description: 'To list information about the backup policies for all Droplets in the account, send a GET request to `/v2/droplets/backups/policies`. ' tags: - Droplets parameters: - $ref: '#/components/parameters/per_page' - $ref: '#/components/parameters/page' responses: '200': $ref: '#/components/responses/all_droplet_backup_policies' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found' '429': $ref: '#/components/responses/too_many_requests' '500': $ref: '#/components/responses/server_error' default: $ref: '#/components/responses/unexpected_error' x-codeSamples: - lang: cURL source: "curl -X GET \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/droplets/backups/policies\"" - lang: Go source: "import (\n \"context\"\n \"os\"\n\n \"github.com/digitalocean/godo\"\n)\n\nfunc main() {\n token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n client := godo.NewFromToken(token)\n ctx := context.TODO()\n\n droplet, _, err := client.Droplets.ListBackupPolicies(ctx)\n}" - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.droplets.list_backup_policies()' security: - bearer_auth: - droplet:read /v2/droplets/backups/supported_policies: get: operationId: droplets_list_supported_backup_policies summary: List Supported Droplet Backup Policies description: 'To retrieve a list of all supported Droplet backup policies, send a GET request to `/v2/droplets/backups/supported_policies`. ' tags: - Droplets responses: '200': $ref: '#/components/responses/droplets_supported_backup_policies' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found' '429': $ref: '#/components/responses/too_many_requests' '500': $ref: '#/components/responses/server_error' default: $ref: '#/components/responses/unexpected_error' x-codeSamples: - lang: cURL source: "curl -X GET \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/droplets/backups/supported_policies\"" - lang: Go source: "import (\n \"context\"\n \"os\"\n\n \"github.com/digitalocean/godo\"\n)\n\nfunc main() {\n token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n client := godo.NewFromToken(token)\n ctx := context.TODO()\n\n droplet, _, err := client.Droplets.ListSupportedBackupPolicies(ctx)\n}" - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.droplets.list_supported_backup_policies()' security: - bearer_auth: - droplet:read /v2/droplets/{droplet_id}/snapshots: get: operationId: droplets_list_snapshots summary: List Snapshots for a Droplet description: 'To retrieve the snapshots that have been created from a Droplet, send a GET request to `/v2/droplets/$DROPLET_ID/snapshots`. You will get back a JSON object that has a `snapshots` key. This will be set to an array of snapshot objects, each of which contain the standard Droplet snapshot attributes. ' tags: - Droplets parameters: - $ref: '#/components/parameters/droplet_id' - $ref: '#/components/parameters/per_page' - $ref: '#/components/parameters/page' responses: '200': $ref: '#/components/responses/all_droplet_snapshots' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found' '429': $ref: '#/components/responses/too_many_requests' '500': $ref: '#/components/responses/server_error' default: $ref: '#/components/responses/unexpected_error' x-codeSamples: - lang: cURL source: "curl -X GET \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/droplets/3164494/snapshots?page=1&per_page=1\"" - lang: Go source: "import (\n \"context\"\n \"os\"\n\n \"github.com/digitalocean/godo\"\n)\n\nfunc main() {\n token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n client := godo.NewFromToken(token)\n ctx := context.TODO()\n\n opt := &godo.ListOptions{\n Page: 1,\n PerPage: 200,\n }\n\n snapshots, _, err := client.Droplets.Snapshots(ctx, 3164494, opt)\n}" - lang: Ruby source: 'require ''droplet_kit'' token = ENV[''DIGITALOCEAN_TOKEN''] client = DropletKit::Client.new(access_token: token) snapshots = client.droplets.snapshots(id: 3164494) snapshots.each' - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.droplets.list_snapshots(droplet_id=3929391)' security: - bearer_auth: - droplet:read /v2/droplets/{droplet_id}/kernels: get: operationId: droplets_list_kernels summary: List All Available Kernels for a Droplet description: '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. ' tags: - Droplets parameters: - $ref: '#/components/parameters/droplet_id' - $ref: '#/components/parameters/per_page' - $ref: '#/components/parameters/page' responses: '200': $ref: '#/components/responses/all_kernels' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found' '429': $ref: '#/components/responses/too_many_requests' '500': $ref: '#/components/responses/server_error' default: $ref: '#/components/responses/unexpected_error' x-codeSamples: - lang: cURL source: "curl -X GET \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/droplets/3164494/kernels?page=1&per_page=1\"" - lang: Go source: "import (\n \"context\"\n \"os\"\n\n \"github.com/digitalocean/godo\"\n)\n\nfunc main() {\n token := os.Getenv(\"DIGITALOCEAN_TOKEN\")\n\n client := godo.NewFromToken(token)\n ctx := context.TODO()\n\n opt := &godo.ListOptions{\n Page: 1,\n PerPage: 200,\n }\n\n kernels, _, err := client.Droplets.Kernels(ctx, 3164494, opt) \n}" - lang: Ruby source: 'require ''droplet_kit'' token = ENV[''DIGITALOCEAN_TOKEN''] client = DropletKit::Client.new(access_token: token) kernels = client.droplets.kernels(id: 3164494) kernels.each' - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.droplets.list_kernels(droplet_id=594828)' security: - bearer_auth: - droplet:read /v2/droplets/{droplet_id}/firewalls: get: operationId: droplets_list_firewalls summary: List all Firewalls Applied to a Droplet description: 'To retrieve a list of all firewalls available to a Droplet, send a GET request to `/v2/droplets/$DROPLET_ID/firewalls` The response will be a JSON object that has a key called `firewalls`. This will be set to an array of `firewall` objects, each of which contain the standard `firewall` attributes. ' tags: - Droplets parameters: - $ref: '#/components/parameters/droplet_id' - $ref: '#/components/parameters/per_page' - $ref: '#/components/parameters/page' responses: '200': $ref: '#/components/responses/all_firewalls' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found' '429': $ref: '#/components/responses/too_many_requests' '500': $ref: '#/components/responses/server_error' default: $ref: '#/components/responses/unexpected_error' security: - bearer_auth: - firewall:read /v2/droplets/{droplet_id}/neighbors: get: operationId: droplets_list_neighbors summary: List Neighbors for a Droplet description: 'To retrieve a list of any "neighbors" (i.e. Droplets that are co-located on the same physical hardware) for a specific Droplet, send a GET request to `/v2/droplets/$DROPLET_ID/neighbors`. The results will be returned as a JSON object with a key of `droplets`. This will be set to an array containing objects representing any other Droplets that share the same physical hardware. An empty array indicates that the Droplet is not co-located any other Droplets associated with your account. ' tags: - Droplets parameters: - $ref: '#/components/parameters/droplet_id' responses: '200': $ref: '#/components/responses/neighbor_droplets' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found' '429': $ref: '#/components/responses/too_many_requests' '500': $ref: '#/components/responses/server_error' default: $ref: '#/components/responses/unexpected_error' x-codeSamples: - lang: cURL source: "curl -X GET \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/droplets/3164494/neighbors\"" - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.droplets.list_neighbors(droplet_id=594828)' security: - bearer_auth: - droplet:read /v2/droplets/{droplet_id}/destroy_with_associated_resources: get: operationId: droplets_list_associatedResources summary: List Associated Resources for a Droplet description: 'To list the associated billable resources that can be destroyed along with a Droplet, send a GET request to the `/v2/droplets/$DROPLET_ID/destroy_with_associated_resources` endpoint. The response will be a JSON object containing `snapshots`, `volumes`, and `volume_snapshots` keys. Each will be set to an array of objects containing information about the associated resources. ' tags: - Droplets parameters: - $ref: '#/components/parameters/droplet_id' responses: '200': $ref: '#/components/responses/associated_resources_list' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found' '429': $ref: '#/components/responses/too_many_requests' '500': $ref: '#/components/responses/server_error' default: $ref: '#/components/responses/unexpected_error' x-codeSamples: - lang: cURL source: "curl -X GET \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/droplets/3164494/destroy_with_associated_resources\"" - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.droplets.list_associated_resources(droplet_id=594828)' security: - bearer_auth: - droplet:delete /v2/droplets/{droplet_id}/destroy_with_associated_resources/selective: delete: operationId: droplets_destroy_withAssociatedResourcesSelective summary: Selectively Destroy a Droplet and its Associated Resources description: 'To destroy a Droplet along with a sub-set of its associated resources, send a DELETE request to the `/v2/droplets/$DROPLET_ID/destroy_with_associated_resources/selective` endpoint. The JSON body of the request should include `reserved_ips`, `snapshots`, `volumes`, or `volume_snapshots` keys each set to an array of IDs for the associated resources to be destroyed. The IDs can be found by querying the Droplet''s associated resources. Any associated resource not included in the request will remain and continue to accrue changes on your account. A successful response will include a 202 response code and no content. Use the status endpoint to check on the success or failure of the destruction of the individual resources. ' tags: - Droplets parameters: - $ref: '#/components/parameters/droplet_id' requestBody: content: application/json: schema: $ref: '#/components/schemas/selective_destroy_associated_resource' responses: '202': $ref: '#/components/responses/accepted' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found' '429': $ref: '#/components/responses/too_many_requests' '500': $ref: '#/components/responses/server_error' default: $ref: '#/components/responses/unexpected_error' x-codeSamples: - lang: cURL source: "curl -X DELETE \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n -d '{\"reserved_ips\":[\"6186916\"],\"snapshots\": [\"61486916\"],\"volumes\": [\"ba49449a-7435-11ea-b89e-0a58ac14480f\"],\"volume_snapshots\": [\"edb0478d-7436-11ea-86e6-0a58ac144b91\"]}' \\\n \"https://api.digitalocean.com/v2/droplets/187000742/destroy_with_associated_resources/selective\"" - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.droplets.destroy_with_associated_resources_selective(droplet_id=524512)' security: - bearer_auth: - droplet:delete /v2/droplets/{droplet_id}/destroy_with_associated_resources/dangerous: delete: operationId: droplets_destroy_withAssociatedResourcesDangerous summary: Destroy a Droplet and All of its Associated Resources (Dangerous) description: 'To destroy a Droplet along with all of its associated resources, send a DELETE request to the `/v2/droplets/$DROPLET_ID/destroy_with_associated_resources/dangerous` endpoint. The headers of this request must include an `X-Dangerous` key set to `true`. To preview which resources will be destroyed, first query the Droplet''s associated resources. This operation _can not_ be reverse and should be used with caution. A successful response will include a 202 response code and no content. Use the status endpoint to check on the success or failure of the destruction of the individual resources. ' tags: - Droplets parameters: - $ref: '#/components/parameters/droplet_id' - $ref: '#/components/parameters/x_dangerous' responses: '202': $ref: '#/components/responses/accepted' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found' '429': $ref: '#/components/responses/too_many_requests' '500': $ref: '#/components/responses/server_error' default: $ref: '#/components/responses/unexpected_error' x-codeSamples: - lang: cURL source: "curl -X DELETE -H \"X-Dangerous: true\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/droplets/187000742/destroy_with_associated_resources/dangerous\"" - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.droplets.destroy_with_associated_resources_dangerous(droplet_id=524512)' security: - bearer_auth: - droplet:delete /v2/droplets/{droplet_id}/destroy_with_associated_resources/status: get: operationId: droplets_get_DestroyAssociatedResourcesStatus summary: Check Status of a Droplet Destroy with Associated Resources Request description: 'To check on the status of a request to destroy a Droplet with its associated resources, send a GET request to the `/v2/droplets/$DROPLET_ID/destroy_with_associated_resources/status` endpoint. ' tags: - Droplets parameters: - $ref: '#/components/parameters/droplet_id' responses: '200': $ref: '#/components/responses/associated_resources_status' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found' '429': $ref: '#/components/responses/too_many_requests' '500': $ref: '#/components/responses/server_error' default: $ref: '#/components/responses/unexpected_error' x-codeSamples: - lang: cURL source: "curl -X GET \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/droplets/3164494/destroy_with_associated_resources/status\"" - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.droplets.get_destroy_associated_resources_status(droplet_id=5624512)' security: - bearer_auth: - droplet:delete /v2/droplets/{droplet_id}/destroy_with_associated_resources/retry: post: operationId: droplets_destroy_retryWithAssociatedResources summary: Retry a Droplet Destroy with Associated Resources Request description: 'If the status of a request to destroy a Droplet with its associated resources reported any errors, it can be retried by sending a POST request to the `/v2/droplets/$DROPLET_ID/destroy_with_associated_resources/retry` endpoint. Only one destroy can be active at a time per Droplet. If a retry is issued while another destroy is in progress for the Droplet a 409 status code will be returned. A successful response will include a 202 response code and no content. ' tags: - Droplets parameters: - $ref: '#/components/parameters/droplet_id' responses: '202': $ref: '#/components/responses/accepted' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found' '409': $ref: '#/components/responses/conflict' '429': $ref: '#/components/responses/too_many_requests' '500': $ref: '#/components/responses/server_error' default: $ref: '#/components/responses/unexpected_error' x-codeSamples: - lang: cURL source: "curl -X POST \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/droplets/3164494/destroy_with_associated_resources/retry\"" - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.droplets.destroy_retry_with_associated_resources(droplet_id=524512)' security: - bearer_auth: - droplet:delete /v2/reports/droplet_neighbors_ids: get: operationId: droplets_list_neighborsIds summary: List All Droplet Neighbors description: 'To retrieve a list of all Droplets that are co-located on the same physical hardware, send a GET request to `/v2/reports/droplet_neighbors_ids`. The results will be returned as a JSON object with a key of `neighbor_ids`. This will be set to an array of arrays. Each array will contain a set of Droplet IDs for Droplets that share a physical server. An empty array indicates that all Droplets associated with your account are located on separate physical hardware. ' tags: - Droplets responses: '200': $ref: '#/components/responses/droplet_neighbors_ids' '401': $ref: '#/components/responses/unauthorized' '404': $ref: '#/components/responses/not_found' '429': $ref: '#/components/responses/too_many_requests' '500': $ref: '#/components/responses/server_error' default: $ref: '#/components/responses/unexpected_error' x-codeSamples: - lang: cURL source: "curl -X GET \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/reports/droplet_neighbors_ids\"" - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.droplets.list_neighbors_ids()' security: - bearer_auth: - droplet:read components: schemas: link_to_prev_page: type: object properties: prev: description: URI of the previous page of the results. type: string example: https://api.digitalocean.com/v2/images?page=1 destroyed_associated_resource: type: object description: An object containing information about a resource scheduled for deletion. properties: id: type: string example: '61486916' description: The unique identifier for the resource scheduled for deletion. name: type: string example: ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330 description: The name of the resource scheduled for deletion. destroyed_at: type: string format: date-time example: '2020-04-01T18:11:49Z' description: A time value given in ISO8601 combined date and time format indicating when the resource was destroyed if the request was successful. error_message: type: string example: ' ' description: A string indicating that the resource was not successfully destroyed and providing additional information. droplet_backup_policy_record: type: object properties: droplet_id: type: integer example: 7101383 description: The unique identifier for the Droplet. backup_enabled: type: boolean example: true description: A boolean value indicating whether backups are enabled for the Droplet. backup_policy: allOf: - $ref: '#/components/schemas/droplet_backup_policy' - description: An object specifying the backup policy for the Droplet. next_backup_window: allOf: - $ref: '#/components/schemas/droplet_next_backup_window' - description: An object containing keys with the start and end times of the window during which the backup will occur. image_description: type: string description: An optional free-form text field to describe an image. example: ' ' pagination: type: object properties: links: $ref: '#/components/schemas/page_links' backward_links: allOf: - $ref: '#/components/schemas/link_to_first_page' - $ref: '#/components/schemas/link_to_prev_page' kernel: type: object description: '**Note**: All Droplets created after March 2017 use internal kernels by default. These Droplets will have this attribute set to `null`. The current [kernel](https://docs.digitalocean.com/products/droplets/how-to/kernel/) for Droplets with externally managed kernels. This will initially be set to the kernel of the base image when the Droplet is created. ' nullable: true deprecated: true properties: id: type: integer example: 7515 description: A unique number used to identify and reference a specific kernel. name: type: string example: DigitalOcean GrubLoader v0.2 (20160714) description: 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: type: string example: 2016.07.13-DigitalOcean_loader_Ubuntu description: A standard kernel version string representing the version, patch, and release information. droplet: type: object properties: id: type: integer example: 3164444 description: A unique identifier for each Droplet instance. This is automatically generated upon Droplet creation. name: type: string example: example.com description: The human-readable name set for the Droplet instance. memory: type: integer multipleOf: 8 example: 1024 description: Memory of the Droplet in megabytes. vcpus: type: integer example: 1 description: The number of virtual CPUs. disk: type: integer example: 25 description: The size of the Droplet's disk in gigabytes. disk_info: type: array description: An array of objects containing information about the disks available to the Droplet. items: $ref: '#/components/schemas/disk_info' locked: type: boolean example: false description: A boolean value indicating whether the Droplet has been locked, preventing actions by users. status: type: string enum: - new - active - 'off' - archive example: active description: A status string indicating the state of the Droplet instance. This may be "new", "active", "off", or "archive". kernel: $ref: '#/components/schemas/kernel' created_at: type: string format: date-time example: '2020-07-21T18:37:44Z' description: A time value given in ISO8601 combined date and time format that represents when the Droplet was created. features: type: array items: type: string example: - backups - private_networking - ipv6 description: An array of features enabled on this Droplet. backup_ids: type: array items: type: integer example: - 53893572 description: 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. next_backup_window: allOf: - $ref: '#/components/schemas/droplet_next_backup_window' - description: 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. snapshot_ids: type: array items: type: integer example: - 67512819 description: An array of snapshot IDs of any snapshots created from the Droplet instance. image: $ref: '#/components/schemas/image' volume_ids: type: array items: type: string example: - 506f78a4-e098-11e5-ad9f-000f53306ae1 description: A flat array including the unique identifier for each Block Storage volume attached to the Droplet. size: $ref: '#/components/schemas/size' size_slug: type: string example: s-1vcpu-1gb description: The unique slug identifier for the size of this Droplet. networks: type: object description: 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. properties: v4: type: array items: $ref: '#/components/schemas/network_v4' v6: type: array items: $ref: '#/components/schemas/network_v6' region: $ref: '#/components/schemas/region' tags: type: array items: type: string example: - web - env:prod description: An array of Tags the Droplet has been tagged with. vpc_uuid: type: string example: 760e09ef-dc84-11e8-981e-3cfdfeaae000 description: A string specifying the UUID of the VPC to which the Droplet is assigned. gpu_info: $ref: '#/components/schemas/gpu_info' required: - id - name - memory - vcpus - disk - locked - status - created_at - features - backup_ids - next_backup_window - snapshot_ids - image - volume_ids - size - size_slug - networks - region - tags network_v4: type: object properties: ip_address: type: string format: ipv4 example: 104.236.32.182 description: The IP address of the IPv4 network interface. netmask: type: string format: ipv4 example: 255.255.192.0 description: The netmask of the IPv4 network interface. gateway: type: string example: 104.236.0.1 description: 'The gateway of the specified IPv4 network interface. For private interfaces, a gateway is not provided. This is denoted by returning `nil` as its value. ' type: type: string enum: - public - private example: public description: The type of the IPv4 network interface. regions_array: type: array items: $ref: '#/components/schemas/region_slug' description: This attribute is an array of the regions that the image is available in. The regions are represented by their identifying slug values. example: - nyc1 - nyc2 gpu_info: type: object description: An object containing information about the GPU capabilities of Droplets created with this size. properties: count: type: integer description: The number of GPUs allocated to the Droplet. example: 1 model: type: string description: The model of the GPU. example: nvidia_h100 vram: type: object properties: amount: type: integer description: The amount of VRAM allocated to the GPU. example: 25 unit: type: string description: The unit of measure for the VRAM. example: gib droplet_create: type: object properties: region: type: string example: nyc3 description: The slug identifier for the region that you wish to deploy the Droplet in. If the specific datacenter is not not important, a slug prefix (e.g. `nyc`) can be used to deploy the Droplet in any of the that region's locations (`nyc1`, `nyc2`, or `nyc3`). If the region is omitted from the create request completely, the Droplet may deploy in any region. size: type: string example: s-1vcpu-1gb description: The slug identifier for the size that you wish to select for this Droplet. image: oneOf: - type: string - type: integer example: ubuntu-20-04-x64 description: The image ID of a public or private image or the slug identifier for a public image. This image will be the base image for your Droplet. ssh_keys: type: array items: anyOf: - type: string - type: integer example: - 289794 - 3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45 default: [] description: 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: type: boolean example: true default: false description: A boolean indicating whether automated backups should be enabled for the Droplet. backup_policy: allOf: - $ref: '#/components/schemas/droplet_backup_policy' - description: An object specifying the backup policy for the Droplet. If omitted and `backups` is `true`, the backup plan will default to daily. ipv6: type: boolean example: true default: false description: A boolean indicating whether to enable IPv6 on the Droplet. monitoring: type: boolean example: true default: false description: A boolean indicating whether to install the DigitalOcean agent for monitoring. tags: type: array items: type: string nullable: true example: - env:prod - web default: [] description: 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. user_data: type: string example: "#cloud-config\nruncmd:\n - touch /test.txt\n" description: 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. private_networking: type: boolean example: true default: false deprecated: true description: This parameter has been deprecated. Use `vpc_uuid` instead to specify a VPC network for the Droplet. If no `vpc_uuid` is provided, the Droplet will be placed in your account's default VPC for the region. volumes: type: array items: type: string example: - 12e97116-7280-11ed-b3d0-0a58ac146812 default: [] description: An array of IDs for block storage volumes that will be attached to the Droplet once created. The volumes must not already be attached to an existing Droplet. vpc_uuid: type: string example: 760e09ef-dc84-11e8-981e-3cfdfeaae000 description: A string specifying the UUID of the VPC to which the Droplet will be assigned. If excluded, the Droplet will be assigned to your account's default VPC for the region. with_droplet_agent: type: boolean example: true description: A boolean indicating whether to install the DigitalOcean agent used for providing access to the Droplet web console in the control panel. By default, the agent is installed on new Droplets but installation errors (i.e. OS not supported) are ignored. To prevent it from being installed, set to `false`. To make installation errors fatal, explicitly set it to `true`. required: - size - image droplet_backup_policy: type: object properties: plan: type: string enum: - daily - weekly example: daily description: The backup plan used for the Droplet. The plan can be either `daily` or `weekly`. weekday: type: string enum: - SUN - MON - TUE - WED - THU - FRI - SAT example: SUN description: The day of the week on which the backup will occur. hour: type: integer enum: - 0 - 4 - 8 - 12 - 16 - 20 example: 0 description: The hour of the day that the backup window will start. window_length_hours: type: integer readOnly: true example: 4 description: The length of the backup window starting from `hour`. retention_period_days: type: integer readOnly: true example: 7 description: The number of days the backup will be retained. droplet_single_create: title: Single Droplet Request allOf: - type: object properties: name: type: string maxLength: 255 pattern: ^[a-zA-Z0-9]?[a-z0-9A-Z.\-]*[a-z0-9A-Z]$ example: example.com description: 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. required: - name - $ref: '#/components/schemas/droplet_create' firewall_rule_target: type: object properties: addresses: type: array items: type: string description: An array of strings containing the IPv4 addresses, IPv6 addresses, IPv4 CIDRs, and/or IPv6 CIDRs to which the firewall will allow traffic. example: - 1.2.3.4 - 18.0.0.0/8 droplet_ids: type: array items: type: integer description: An array containing the IDs of the Droplets to which the firewall will allow traffic. example: - 8043964 load_balancer_uids: type: array items: type: string description: An array containing the IDs of the load balancers to which the firewall will allow traffic. example: - 4de7ac8b-495b-4884-9a69-1050c6793cd6 kubernetes_ids: type: array items: type: string description: An array containing the IDs of the Kubernetes clusters to which the firewall will allow traffic. example: - 41b74c5d-9bd0-5555-5555-a57c495b81a3 tags: allOf: - $ref: '#/components/schemas/existing_tags_array' - description: An array containing the names of Tags corresponding to groups of Droplets to which the firewall will allow traffic. example: - frontend error: type: object properties: id: description: A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found." type: string example: not_found message: description: A message providing additional information about the error, including details to help resolve it when possible. type: string example: The resource you were accessing could not be found. request_id: description: Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue. type: string example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9 required: - id - message supported_droplet_backup_policy: type: object properties: name: type: string example: daily description: The name of the Droplet backup plan. possible_window_starts: type: array items: type: integer description: 'An array of integers representing the hours of the day that a backup can start. ' example: - 0 - 4 - 8 - 12 - 16 - 20 window_length_hours: type: integer example: 4 description: The number of hours that a backup window is open. retention_period_days: type: integer example: 7 description: The number of days that a backup will be kept. possible_days: type: array items: type: string example: - SUN - MON - TUE - WED - THU - FRI - SAT description: The day of the week the backup will occur. tags_array: type: array items: type: string nullable: true description: A flat array of tag names as strings to be applied to the resource. Tag names may be for either existing or new tags. example: - base-image - prod firewall: type: object allOf: - properties: id: type: string description: A unique ID that can be used to identify and reference a firewall. readOnly: true example: bb4b2611-3d72-467b-8602-280330ecd65c status: type: string description: A status string indicating the current state of the firewall. This can be "waiting", "succeeded", or "failed". enum: - waiting - succeeded - failed readOnly: true example: waiting created_at: type: string format: date-time description: A time value given in ISO8601 combined date and time format that represents when the firewall was created. readOnly: true example: '2020-05-23T21:24:00Z' pending_changes: type: array description: 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. items: type: object properties: droplet_id: type: integer example: 8043964 removing: type: boolean example: false status: type: string example: waiting readOnly: true example: - droplet_id: 8043964 removing: false status: waiting name: type: string description: A human-readable name for a firewall. The name must begin with an alphanumeric character. Subsequent characters must either be alphanumeric characters, a period (.), or a dash (-). pattern: ^[a-zA-Z0-9][a-zA-Z0-9\.-]+$ example: firewall droplet_ids: type: array description: An array containing the IDs of the Droplets assigned to the firewall. nullable: true items: type: integer example: - 8043964 tags: allOf: - $ref: '#/components/schemas/existing_tags_array' - description: An array containing the names of the Tags assigned to the firewall. example: gateway - $ref: '#/components/schemas/firewall_rules' size: type: object properties: slug: type: string example: s-1vcpu-1gb description: A human-readable string that is used to uniquely identify each size. memory: type: integer multipleOf: 8 minimum: 8 example: 1024 description: The amount of RAM allocated to Droplets created of this size. The value is represented in megabytes. vcpus: type: integer example: 1 description: The number of CPUs allocated to Droplets of this size. disk: type: integer example: 25 description: The amount of disk space set aside for Droplets of this size. The value is represented in gigabytes. transfer: type: number format: float example: 1 description: 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: type: number format: float example: 5 description: 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: type: number format: float example: 0.00743999984115362 description: This describes the price of the Droplet size as measured hourly. The value is measured in US dollars. regions: type: array items: type: string example: - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 description: An array containing the region slugs where this size is available for Droplet creates. available: type: boolean default: true example: true description: This is a boolean value that represents whether new Droplets can be created with this size. description: type: string example: Basic description: 'A string describing the class of Droplets created from this size. For example: Basic, General Purpose, CPU-Optimized, Memory-Optimized, or Storage-Optimized.' disk_info: type: array description: An array of objects containing information about the disks available to Droplets created with this size. items: $ref: '#/components/schemas/disk_info' gpu_info: $ref: '#/components/schemas/gpu_info' required: - available - disk - memory - price_hourly - price_monthly - regions - slug - transfer - vcpus - description snapshots_base: type: object properties: name: type: string example: web-01-1595954862243 description: A human-readable name for the snapshot. created_at: type: string format: date-time example: '2020-07-28T16:47:44Z' description: A time value given in ISO8601 combined date and time format that represents when the snapshot was created. regions: type: array items: type: string example: - nyc3 - sfo3 description: An array of the regions that the snapshot is available in. The regions are represented by their identifying slug values. min_disk_size: type: integer example: 25 description: The minimum size in GB required for a volume or Droplet to use this snapshot. size_gigabytes: type: number format: float example: 2.34 description: The billable size of the snapshot in gigabytes. required: - name - created_at - regions - min_disk_size - size_gigabytes associated_resource_status: type: object description: An objects containing information about a resources scheduled for deletion. properties: droplet: $ref: '#/components/schemas/destroyed_associated_resource' resources: type: object description: An object containing additional information about resource related to a Droplet requested to be destroyed. properties: reserved_ips: type: array items: $ref: '#/components/schemas/destroyed_associated_resource' floating_ips: type: array items: $ref: '#/components/schemas/destroyed_associated_resource' snapshots: type: array items: $ref: '#/components/schemas/destroyed_associated_resource' volumes: type: array items: $ref: '#/components/schemas/destroyed_associated_resource' volume_snapshots: type: array items: $ref: '#/components/schemas/destroyed_associated_resource' completed_at: type: string format: date-time example: '2020-04-01T18:11:49Z' description: A time value given in ISO8601 combined date and time format indicating when the requested action was completed. failures: type: integer example: 0 description: A count of the associated resources that failed to be destroyed, if any. neighbor_ids: type: object properties: neighbor_ids: type: array items: type: array items: type: integer description: An array of arrays. Each array will contain a set of Droplet IDs for Droplets that share a physical server. example: - - 168671828 - 168663509 - 168671815 - - 168671883 - 168671750 region_slug: type: string description: The slug identifier for the region where the resource will initially be available. enum: - ams1 - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 - syd1 example: nyc3 firewall_rules: type: object properties: inbound_rules: nullable: true type: array items: allOf: - $ref: '#/components/schemas/firewall_rule_base' - properties: sources: allOf: - $ref: '#/components/schemas/firewall_rule_target' - description: An object specifying locations from which inbound traffic will be accepted. required: - sources outbound_rules: nullable: true type: array items: allOf: - $ref: '#/components/schemas/firewall_rule_base' - properties: destinations: allOf: - $ref: '#/components/schemas/firewall_rule_target' - description: An object specifying locations to which outbound traffic that will be allowed. required: - destinations action_link: type: object description: The linked actions can be used to check the status of a Droplet's create event. properties: id: type: integer example: 7515 description: A unique numeric ID that can be used to identify and reference an action. rel: type: string example: create description: A string specifying the type of the related action. href: type: string format: uri example: https://api.digitalocean.com/v2/actions/7515 description: A URL that can be used to access the action. image_name: type: string description: 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. example: Nifty New Snapshot meta_properties: type: object description: Information about the response itself. properties: total: description: Number of objects returned by the request. type: integer example: 1 associated_resource: type: object description: An objects containing information about a resource associated with a Droplet. properties: id: type: string example: '61486916' description: The unique identifier for the resource associated with the Droplet. name: type: string example: ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330 description: The name of the resource associated with the Droplet. cost: type: string example: '0.05' description: The cost of the resource in USD per month if the resource is retained after the Droplet is destroyed. link_to_next_page: type: object properties: next: description: URI of the next page of the results. type: string example: https://api.digitalocean.com/v2/images?page=2 distribution: type: string description: 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`, `Rocky Linux`, `Ubuntu`, and `Unknown`. Any other value will be accepted but ignored, and `Unknown` will be used in its place. enum: - Arch Linux - CentOS - CoreOS - Debian - Fedora - Fedora Atomic - FreeBSD - Gentoo - openSUSE - RancherOS - Rocky Linux - Ubuntu - Unknown example: Ubuntu network_v6: type: object properties: ip_address: type: string format: ipv6 example: 2604:a880:0:1010::18a:a001 description: The IP address of the IPv6 network interface. netmask: type: integer example: 64 description: The netmask of the IPv6 network interface. gateway: type: string format: ipv6 example: 2604:a880:0:1010::1 description: The gateway of the specified IPv6 network interface. type: type: string enum: - public example: public description: 'The type of the IPv6 network interface. **Note**: IPv6 private networking is not currently supported. ' link_to_last_page: type: object properties: last: description: URI of the last page of the results. type: string example: https://api.digitalocean.com/v2/images?page=2 page_links: type: object properties: pages: anyOf: - $ref: '#/components/schemas/forward_links' - $ref: '#/components/schemas/backward_links' - {} example: pages: first: https://api.digitalocean.com/v2/account/keys?page=1 prev: https://api.digitalocean.com/v2/account/keys?page=2 existing_tags_array: type: array items: type: string nullable: true description: A flat array of tag names as strings to be applied to the resource. Tag names must exist in order to be referenced in a request. example: - base-image - prod droplet_snapshot: allOf: - type: object properties: id: type: integer example: 6372321 description: The unique identifier for the snapshot or backup. required: - id - $ref: '#/components/schemas/snapshots_base' - type: object properties: type: type: string enum: - snapshot - backup example: snapshot description: Describes the kind of image. It may be one of `snapshot` or `backup`. This specifies whether an image is a user-generated Droplet snapshot or automatically created Droplet backup. required: - type droplet_multi_create: title: Multiple Droplet Request allOf: - type: object properties: names: type: array items: type: string maxLength: 255 pattern: ^[a-zA-Z0-9]?[a-z0-9A-Z.\-]*[a-z0-9A-Z]$ example: - sub-01.example.com - sub-02.example.com description: 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. required: - names - $ref: '#/components/schemas/droplet_create' forward_links: allOf: - $ref: '#/components/schemas/link_to_last_page' - $ref: '#/components/schemas/link_to_next_page' region: type: object properties: name: type: string description: The display name of the region. This will be a full name that is used in the control panel and other interfaces. example: New York 3 slug: type: string description: A human-readable string that is used as a unique identifier for each region. example: nyc3 features: items: type: string description: This attribute is set to an array which contains features available in this region example: - private_networking - backups - ipv6 - metadata - install_agent - storage - image_transfer available: type: boolean description: This is a boolean value that represents whether new Droplets can be created in this region. example: true sizes: items: type: string description: This attribute is set to an array which contains the identifying slugs for the sizes available in this region. example: - s-1vcpu-1gb - s-1vcpu-2gb - s-1vcpu-3gb - s-2vcpu-2gb - s-3vcpu-1gb - s-2vcpu-4gb - s-4vcpu-8gb - s-6vcpu-16gb - s-8vcpu-32gb - s-12vcpu-48gb - s-16vcpu-64gb - s-20vcpu-96gb - s-24vcpu-128gb - s-32vcpu-192g required: - available - features - name - sizes - slug selective_destroy_associated_resource: type: object description: An object containing information about a resource to be scheduled for deletion. properties: floating_ips: type: array deprecated: true description: An array of unique identifiers for the floating IPs to be scheduled for deletion. items: type: string example: - '6186916' reserved_ips: type: array description: An array of unique identifiers for the reserved IPs to be scheduled for deletion. items: type: string example: - '6186916' snapshots: type: array description: An array of unique identifiers for the snapshots to be scheduled for deletion. items: type: string example: - '61486916' volumes: type: array description: An array of unique identifiers for the volumes to be scheduled for deletion. items: type: string example: - ba49449a-7435-11ea-b89e-0a58ac14480f volume_snapshots: type: array description: An array of unique identifiers for the volume snapshots to be scheduled for deletion. items: type: string example: - edb0478d-7436-11ea-86e6-0a58ac144b91 link_to_first_page: type: object properties: first: description: URI of the first page of the results. type: string example: https://api.digitalocean.com/v2/images?page=1 disk_info: type: object properties: type: type: string enum: - local - scratch description: The type of disk. All Droplets contain a `local` disk. Additionally, GPU Droplets can also have a `scratch` disk for non-persistent data. example: local size: type: object properties: amount: type: integer description: The amount of space allocated to the disk. example: 25 unit: type: string description: The unit of measure for the disk size. example: gib meta: type: object properties: meta: allOf: - $ref: '#/components/schemas/meta_properties' - required: - total required: - meta droplet_next_backup_window: type: object nullable: true properties: start: type: string format: date-time example: '2019-12-04T00:00:00Z' description: A time value given in ISO8601 combined date and time format specifying the start of the Droplet's backup window. end: type: string format: date-time example: '2019-12-04T23:00:00Z' description: A time value given in ISO8601 combined date and time format specifying the end of the Droplet's backup window. image: type: object properties: id: type: integer description: A unique number that can be used to identify and reference a specific image. example: 7555620 readOnly: true name: $ref: '#/components/schemas/image_name' type: type: string description: Describes the kind of image. It may be one of `base`, `snapshot`, `backup`, `custom`, or `admin`. Respectively, this specifies whether an image is a DigitalOcean base OS image, user-generated Droplet snapshot, automatically created Droplet backup, user-provided virtual machine image, or an image used for DigitalOcean managed resources (e.g. DOKS worker nodes). enum: - base - snapshot - backup - custom - admin example: snapshot distribution: $ref: '#/components/schemas/distribution' slug: type: string nullable: true description: 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. example: nifty1 public: type: boolean description: 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. example: true regions: $ref: '#/components/schemas/regions_array' created_at: type: string format: date-time description: A time value given in ISO8601 combined date and time format that represents when the image was created. example: '2020-05-04T22:23:02Z' min_disk_size: type: integer description: The minimum disk size in GB required for a Droplet to use this image. example: 20 nullable: true minimum: 0 size_gigabytes: type: number format: float nullable: true description: The size of the image in gigabytes. example: 2.34 description: $ref: '#/components/schemas/image_description' tags: $ref: '#/components/schemas/tags_array' status: type: string description: "A status string indicating the state of a custom image. This may be `NEW`,\n `available`, `pending`, `deleted`, or `retired`." enum: - NEW - available - pending - deleted - retired example: NEW error_message: type: string description: "A string containing information about errors that may occur when importing\n a custom image." example: ' ' firewall_rule_base: type: object properties: protocol: type: string enum: - tcp - udp - icmp description: The type of traffic to be allowed. This may be one of `tcp`, `udp`, or `icmp`. example: tcp ports: type: string description: The ports on which traffic will be allowed specified as a string containing a single port, a range (e.g. "8000-9000"), or "0" when all ports are open for a protocol. For ICMP rules this parameter will always return "0". example: '8000' required: - protocol - ports responses: unauthorized: description: Unauthorized headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/error' example: id: unauthorized message: Unable to authenticate you. all_firewalls: description: A JSON object that has a key called `firewalls`. headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: allOf: - type: object properties: firewalls: type: array items: $ref: '#/components/schemas/firewall' - $ref: '#/components/schemas/pagination' - $ref: '#/components/schemas/meta' example: firewalls: - id: bb4b2611-3d72-467b-8602-280330ecd65c status: succeeded created_at: '2020-05-23T21:24:00Z' pending_changes: - droplet_id: 8043964 removing: true status: waiting name: firewall droplet_ids: - 89989 - 33322 tags: - base-image - prod inbound_rules: - protocol: udp ports: 8000-9000 sources: addresses: - 1.2.3.4 - 18.0.0.0/8 droplet_ids: - 8282823 - 3930392 load_balancer_uids: - 4de7ac8b-495b-4884-9a69-1050c6793cd6 tags: - base-image - dev outbound_rules: - protocol: tcp ports: 7000-9000 destinations: addresses: - 1.2.3.4 - 18.0.0.0/8 droplet_ids: - 3827493 - 213213 load_balancer_uids: - 4de7ac8b-495b-4884-9a69-1050c6793cd6 tags: - base-image - prod links: pages: {} meta: total: 1 conflict: description: Conflict headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/error' example: id: conflict message: The request could not be completed due to a conflict. associated_resources_status: description: A JSON object containing containing the status of a request to destroy a Droplet and its associated resources. headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/associated_resource_status' example: droplet: id: '187000742' name: ubuntu-s-1vcpu-1gb-nyc1-01 destroyed_at: '2020-04-01T18:11:49Z' resources: reserved_ips: - id: '6186916' name: 45.55.96.47 destroyed_at: '2020-04-01T18:11:44Z' floating_ips: - id: '6186916' name: 45.55.96.47 destroyed_at: '2020-04-01T18:11:44Z' snapshots: - id: '61486916' name: ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330 destroyed_at: '2020-04-01T18:11:44Z' volumes: [] volume_snapshots: - id: edb0478d-7436-11ea-86e6-0a58ac144b91 name: volume-nyc1-01-1585758983629 destroyed_at: '2020-04-01T18:11:44Z' completed_at: '2020-04-01T18:11:49Z' failures: 0 droplet_backup_policy: description: 'The response will be a JSON object with a key called `policy`. This will be set to a JSON object that contains the standard Droplet backup policy attributes. ' headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: properties: policy: $ref: '#/components/schemas/droplet_backup_policy_record' example: policy: droplet_id: 444909706 backup_enabled: true backup_policy: plan: weekly weekday: SUN hour: 20 window_length_hours: 4 retention_period_days: 28 next_backup_window: start: '2024-09-15T20:00:00Z' end: '2024-09-16T00:00:00Z' droplets_supported_backup_policies: description: A JSON object with an `supported_policies` key set to an array of objects describing each supported backup policy. headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: type: object properties: supported_policies: type: array items: $ref: '#/components/schemas/supported_droplet_backup_policy' example: supported_policies: - name: weekly possible_window_starts: - 0 - 4 - 8 - 12 - 16 - 20 window_length_hours: 4 retention_period_days: 28 possible_days: - SUN - MON - TUE - WED - THU - FRI - SAT - name: daily possible_window_starts: - 0 - 4 - 8 - 12 - 16 - 20 window_length_hours: 4 retention_period_days: 7 possible_days: [] all_droplet_backups: description: A JSON object with an `backups` key. headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: allOf: - type: object properties: backups: type: array items: $ref: '#/components/schemas/droplet_snapshot' - $ref: '#/components/schemas/pagination' - $ref: '#/components/schemas/meta' example: backups: - id: 67539192 name: web-01- 2020-07-29 distribution: Ubuntu slug: null public: false regions: - nyc3 created_at: '2020-07-29T01:44:35Z' min_disk_size: 50 size_gigabytes: 2.34 type: backup links: {} meta: total: 1 all_droplet_backup_policies: description: A JSON object with a `policies` key set to a map. The keys are Droplet IDs and the values are objects containing the backup policy information for each Droplet. headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: allOf: - type: object properties: policies: description: 'A map where the keys are the Droplet IDs and the values are objects containing the backup policy information for each Droplet. ' additionalProperties: $ref: '#/components/schemas/droplet_backup_policy_record' - $ref: '#/components/schemas/pagination' - $ref: '#/components/schemas/meta' example: policies: '436444618': droplet_id: 436444618 backup_enabled: false '444909314': droplet_id: 444909314 backup_enabled: true backup_policy: plan: daily hour: 20 window_length_hours: 4 retention_period_days: 7 next_backup_window: start: '2024-09-13T20:00:00Z' end: '2024-09-14T00:00:00Z' '444909706': droplet_id: 444909706 backup_enabled: true backup_policy: plan: weekly weekday: SUN hour: 20 window_length_hours: 4 retention_period_days: 28 next_backup_window: start: '2024-09-15T20:00:00Z' end: '2024-09-16T00:00:00Z' links: {} meta: total: 3 existing_droplet: description: 'The response will be a JSON object with a key called `droplet`. This will be set to a JSON object that contains the standard Droplet attributes. ' headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: properties: droplet: $ref: '#/components/schemas/droplet' examples: Single Droplet: $ref: '#/components/examples/droplet_single' no_content_with_content_type: description: The action was successful and the response body is empty. This response has content-type set. headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content-type: $ref: '#/components/headers/content-type' all_droplets: description: A JSON object with a key of `droplets`. headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: allOf: - type: object properties: droplets: type: array items: $ref: '#/components/schemas/droplet' - $ref: '#/components/schemas/pagination' - $ref: '#/components/schemas/meta' examples: All Droplets: $ref: '#/components/examples/droplets_all' Droplets Filtered By Tag: $ref: '#/components/examples/droplets_tagged' GPU Droplets: $ref: '#/components/examples/gpu_droplets' all_kernels: description: A JSON object that has a key called `kernels`. headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: allOf: - type: object properties: kernels: type: array items: $ref: '#/components/schemas/kernel' - $ref: '#/components/schemas/pagination' - $ref: '#/components/schemas/meta' example: kernels: - id: 7515 name: DigitalOcean GrubLoader v0.2 (20160714) version: 2016.07.13-DigitalOcean_loader_Ubuntu links: pages: next: https://api.digitalocean.com/v2/droplets/3164444/kernels?page=2&per_page=1 last: https://api.digitalocean.com/v2/droplets/3164444/kernels?page=171&per_page=1 meta: total: 171 all_droplet_snapshots: description: A JSON object with an `snapshots` key. headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: allOf: - type: object properties: snapshots: type: array items: $ref: '#/components/schemas/droplet_snapshot' - $ref: '#/components/schemas/pagination' - $ref: '#/components/schemas/meta' example: snapshots: - id: 6372321 name: web-01-1595954862243 created_at: '2020-07-28T16:47:44Z' regions: - nyc3 - sfo3 min_disk_size: 25 size_gigabytes: 2.34 type: snapshot links: {} meta: total: 1 neighbor_droplets: description: A JSON object with an `droplets` key. headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: allOf: - type: object properties: droplets: type: array items: $ref: '#/components/schemas/droplet' associated_resources_list: description: A JSON object containing `snapshots`, `volumes`, and `volume_snapshots` keys. headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: allOf: - type: object properties: reserved_ips: type: array items: $ref: '#/components/schemas/associated_resource' floating_ips: type: array items: $ref: '#/components/schemas/associated_resource' snapshots: type: array items: $ref: '#/components/schemas/associated_resource' volumes: type: array items: $ref: '#/components/schemas/associated_resource' volume_snapshots: type: array items: $ref: '#/components/schemas/associated_resource' example: reserved_ips: - id: '6186916' name: 45.55.96.47 cost: '4.00' floating_ips: - id: '6186916' name: 45.55.96.47 cost: '4.00' snapshots: - id: '61486916' name: ubuntu-s-1vcpu-1gb-nyc1-01-1585758823330 cost: '0.05' volumes: - id: ba49449a-7435-11ea-b89e-0a58ac14480f name: volume-nyc1-01 cost: '10.00' volume_snapshots: - id: edb0478d-7436-11ea-86e6-0a58ac144b91 name: volume-nyc1-01-1585758983629 cost: '0.04' accepted: description: The does not indicate the success or failure of any operation, just that the request has been accepted for processing. headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' too_many_requests: description: API Rate limit exceeded headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/error' example: id: too_many_requests message: API Rate limit exceeded. unexpected_error: description: Unexpected error headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/error' example: id: example_error message: some error message droplet_create: description: Accepted headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: oneOf: - title: Single Droplet Response properties: droplet: $ref: '#/components/schemas/droplet' links: type: object properties: actions: type: array items: $ref: '#/components/schemas/action_link' required: - droplet - links - title: Multiple Droplet Response properties: droplets: type: array items: $ref: '#/components/schemas/droplet' links: type: object properties: actions: type: array items: $ref: '#/components/schemas/action_link' required: - droplets - links examples: Single Droplet Create Response: $ref: '#/components/examples/droplet_create_response' Multiple Droplet Create Response: $ref: '#/components/examples/droplet_multi_create_response' server_error: description: Server error. headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/error' example: id: server_error message: Unexpected server-side error not_found: description: The resource was not found. headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/error' example: id: not_found message: The resource you requested could not be found. droplet_neighbors_ids: description: A JSON object with an `neighbor_ids` key. headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' content: application/json: schema: $ref: '#/components/schemas/neighbor_ids' parameters: per_page: in: query name: per_page required: false description: Number of items returned per page schema: type: integer minimum: 1 default: 20 maximum: 200 example: 2 x_dangerous: in: header name: X-Dangerous description: Acknowledge this action will destroy the Droplet and all associated resources and _can not_ be reversed. schema: type: boolean example: true required: true page: in: query name: page required: false description: Which 'page' of paginated results to return. schema: type: integer minimum: 1 default: 1 example: 1 droplet_type: in: query name: type description: When `type` is set to `gpus`, only GPU Droplets will be returned. By default, only non-GPU Droplets are returned. Can not be combined with `tag_name`. required: false schema: type: string enum: - droplets - gpus example: droplets droplet_tag_name: in: query name: tag_name description: Used to filter Droplets by a specific tag. Can not be combined with `name` or `type`. required: false schema: type: string example: env:prod droplet_name: in: query name: name description: Used to filter list response by Droplet name returning only exact matches. It is case-insensitive and can not be combined with `tag_name`. required: false schema: type: string example: web-01 droplet_id: in: path name: droplet_id description: A unique identifier for a Droplet instance. required: true schema: type: integer minimum: 1 example: 3164444 droplet_delete_tag_name: in: query name: tag_name description: Specifies Droplets to be deleted by tag. required: true schema: type: string example: env:test examples: droplets_tagged: value: droplets: - id: 3164444 name: example.com memory: 1024 vcpus: 1 disk: 25 disk_info: - type: local size: amount: 25 unit: gib locked: false status: active kernel: null created_at: '2020-07-21T18:37:44Z' features: - backups - private_networking - ipv6 backup_ids: - 53893572 next_backup_window: start: '2020-07-30T00:00:00Z' end: '2020-07-30T23:00:00Z' snapshot_ids: - 67512819 image: id: 63663980 name: 20.04 (LTS) x64 distribution: Ubuntu slug: ubuntu-20-04-x64 public: true regions: - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 created_at: '2020-05-15T05:47:50Z' type: snapshot min_disk_size: 20 size_gigabytes: 2.36 description: '' tags: [] status: available error_message: '' volume_ids: [] size: slug: s-1vcpu-1gb memory: 1024 vcpus: 1 disk: 25 transfer: 1 price_monthly: 5 price_hourly: 0.00743999984115362 regions: - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 available: true description: Basic size_slug: s-1vcpu-1gb networks: v4: - ip_address: 10.128.192.124 netmask: 255.255.0.0 gateway: nil type: private - ip_address: 192.241.165.154 netmask: 255.255.255.0 gateway: 192.241.165.1 type: public v6: - ip_address: 2604:a880:0:1010::18a:a001 netmask: 64 gateway: 2604:a880:0:1010::1 type: public region: name: New York 3 slug: nyc3 features: - private_networking - backups - ipv6 - metadata - install_agent - storage - image_transfer available: true sizes: - s-1vcpu-1gb - s-1vcpu-2gb - s-1vcpu-3gb - s-2vcpu-2gb - s-3vcpu-1gb - s-2vcpu-4gb - s-4vcpu-8gb - s-6vcpu-16gb - s-8vcpu-32gb - s-12vcpu-48gb - s-16vcpu-64gb - s-20vcpu-96gb - s-24vcpu-128gb - s-32vcpu-192g tags: - web - env:prod vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 - id: 3164459 name: assets.example.com memory: 1024 vcpus: 1 disk: 25 disk_info: - type: local size: amount: 25 unit: gib locked: false status: active kernel: null created_at: '2020-07-21T18:42:27Z' features: - private_networking backup_ids: [] next_backup_window: start: '2020-07-30T00:00:00Z' end: '2020-07-30T23:00:00Z' snapshot_ids: [] image: id: 63663980 name: 20.04 (LTS) x64 distribution: Ubuntu slug: ubuntu-20-04-x64 public: true regions: - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 created_at: '2020-05-15T05:47:50Z' type: snapshot min_disk_size: 20 size_gigabytes: 2.36 description: '' tags: [] status: available error_message: '' volume_ids: - 506f78a4-e098-11e5-ad9f-000f53306ae1 size: slug: s-1vcpu-1gb memory: 1024 vcpus: 1 disk: 25 transfer: 1 price_monthly: 5 price_hourly: 0.00743999984115362 regions: - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 available: true description: Basic size_slug: s-1vcpu-1gb networks: v4: - ip_address: 10.128.192.138 netmask: 255.255.0.0 gateway: nil type: private - ip_address: 162.243.0.4 netmask: 255.255.255.0 gateway: 162.243.0.1 type: public v6: [] region: name: New York 3 slug: nyc3 features: - private_networking - backups - ipv6 - metadata - install_agent - storage - image_transfer available: true sizes: - s-1vcpu-1gb - s-1vcpu-2gb - s-1vcpu-3gb - s-2vcpu-2gb - s-3vcpu-1gb - s-2vcpu-4gb - s-4vcpu-8gb - s-6vcpu-16gb - s-8vcpu-32gb - s-12vcpu-48gb - s-16vcpu-64gb - s-20vcpu-96gb - s-24vcpu-128gb - s-32vcpu-192g tags: - storage - env:prod vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 links: pages: {} meta: total: 2 droplet_single: value: droplet: id: 3164444 name: example.com memory: 1024 vcpus: 1 disk: 25 disk_info: - type: local size: amount: 25 unit: gib locked: false status: active kernel: null created_at: '2020-07-21T18:37:44Z' features: - backups - private_networking - ipv6 backup_ids: - 53893572 next_backup_window: start: '2020-07-30T00:00:00Z' end: '2020-07-30T23:00:00Z' snapshot_ids: - 67512819 image: id: 63663980 name: 20.04 (LTS) x64 distribution: Ubuntu slug: ubuntu-20-04-x64 public: true regions: - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 created_at: '2020-05-15T05:47:50Z' type: snapshot min_disk_size: 20 size_gigabytes: 2.36 description: '' tags: [] status: available error_message: '' volume_ids: [] size: slug: s-1vcpu-1gb memory: 1024 vcpus: 1 disk: 25 transfer: 1 price_monthly: 5 price_hourly: 0.00743999984115362 regions: - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 available: true description: Basic size_slug: s-1vcpu-1gb networks: v4: - ip_address: 10.128.192.124 netmask: 255.255.0.0 gateway: nil type: private - ip_address: 192.241.165.154 netmask: 255.255.255.0 gateway: 192.241.165.1 type: public v6: - ip_address: 2604:a880:0:1010::18a:a001 netmask: 64 gateway: 2604:a880:0:1010::1 type: public region: name: New York 3 slug: nyc3 features: - private_networking - backups - ipv6 - metadata - install_agent - storage - image_transfer available: true sizes: - s-1vcpu-1gb - s-1vcpu-2gb - s-1vcpu-3gb - s-2vcpu-2gb - s-3vcpu-1gb - s-2vcpu-4gb - s-4vcpu-8gb - s-6vcpu-16gb - s-8vcpu-32gb - s-12vcpu-48gb - s-16vcpu-64gb - s-20vcpu-96gb - s-24vcpu-128gb - s-32vcpu-192g tags: - web - env:prod vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 droplets_all: value: droplets: - id: 3164444 name: example.com memory: 1024 vcpus: 1 disk: 25 disk_info: - type: local size: amount: 25 unit: gib locked: false status: active kernel: null created_at: '2020-07-21T18:37:44Z' features: - backups - private_networking - ipv6 backup_ids: - 53893572 next_backup_window: start: '2020-07-30T00:00:00Z' end: '2020-07-30T23:00:00Z' snapshot_ids: - 67512819 image: id: 63663980 name: 20.04 (LTS) x64 distribution: Ubuntu slug: ubuntu-20-04-x64 public: true regions: - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 created_at: '2020-05-15T05:47:50Z' type: snapshot min_disk_size: 20 size_gigabytes: 2.36 description: '' tags: [] status: available error_message: '' volume_ids: [] size: slug: s-1vcpu-1gb memory: 1024 vcpus: 1 disk: 25 transfer: 1 price_monthly: 5 price_hourly: 0.00743999984115362 regions: - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 available: true description: Basic size_slug: s-1vcpu-1gb networks: v4: - ip_address: 10.128.192.124 netmask: 255.255.0.0 gateway: nil type: private - ip_address: 192.241.165.154 netmask: 255.255.255.0 gateway: 192.241.165.1 type: public v6: - ip_address: 2604:a880:0:1010::18a:a001 netmask: 64 gateway: 2604:a880:0:1010::1 type: public region: name: New York 3 slug: nyc3 features: - private_networking - backups - ipv6 - metadata - install_agent - storage - image_transfer available: true sizes: - s-1vcpu-1gb - s-1vcpu-2gb - s-1vcpu-3gb - s-2vcpu-2gb - s-3vcpu-1gb - s-2vcpu-4gb - s-4vcpu-8gb - s-6vcpu-16gb - s-8vcpu-32gb - s-12vcpu-48gb - s-16vcpu-64gb - s-20vcpu-96gb - s-24vcpu-128gb - s-32vcpu-192g tags: - web - env:prod vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 - id: 3164459 name: assets.example.com memory: 1024 vcpus: 1 disk: 25 disk_info: - type: local size: amount: 25 unit: gib locked: false status: active kernel: null created_at: '2020-07-21T18:42:27Z' features: - private_networking backup_ids: [] next_backup_window: start: '2020-07-30T00:00:00Z' end: '2020-07-30T23:00:00Z' snapshot_ids: [] image: id: 63663980 name: 20.04 (LTS) x64 distribution: Ubuntu slug: ubuntu-20-04-x64 public: true regions: - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 created_at: '2020-05-15T05:47:50Z' type: snapshot min_disk_size: 20 size_gigabytes: 2.36 description: '' tags: [] status: available error_message: '' volume_ids: - 506f78a4-e098-11e5-ad9f-000f53306ae1 size: slug: s-1vcpu-1gb memory: 1024 vcpus: 1 disk: 25 transfer: 1 price_monthly: 5 price_hourly: 0.00743999984115362 regions: - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 available: true description: Basic size_slug: s-1vcpu-1gb networks: v4: - ip_address: 10.128.192.138 netmask: 255.255.0.0 gateway: nil type: private - ip_address: 162.243.0.4 netmask: 255.255.255.0 gateway: 162.243.0.1 type: public v6: [] region: name: New York 3 slug: nyc3 features: - private_networking - backups - ipv6 - metadata - install_agent - storage - image_transfer available: true sizes: - s-1vcpu-1gb - s-1vcpu-2gb - s-1vcpu-3gb - s-2vcpu-2gb - s-3vcpu-1gb - s-2vcpu-4gb - s-4vcpu-8gb - s-6vcpu-16gb - s-8vcpu-32gb - s-12vcpu-48gb - s-16vcpu-64gb - s-20vcpu-96gb - s-24vcpu-128gb - s-32vcpu-192g tags: - storage - env:prod vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 - id: 3164412 name: stage.example.com memory: 1024 vcpus: 1 disk: 25 disk_info: - type: local size: amount: 25 unit: gib locked: false status: active kernel: null created_at: '2020-07-21T18:32:55Z' features: - private_networking backup_ids: [] next_backup_window: start: '2020-07-30T00:00:00Z' end: '2020-07-30T23:00:00Z' snapshot_ids: [] image: id: 63663980 name: 20.04 (LTS) x64 distribution: Ubuntu slug: ubuntu-20-04-x64 public: true regions: - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 created_at: '2020-05-15T05:47:50Z' type: snapshot min_disk_size: 20 size_gigabytes: 2.36 description: '' tags: [] status: available error_message: '' volume_ids: - 7724db7c-e098-11e5-b522-000f53304e51 size: slug: s-1vcpu-1gb memory: 1024 vcpus: 1 disk: 25 transfer: 1 price_monthly: 5 price_hourly: 0.00743999984115362 regions: - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 available: true description: Basic size_slug: s-1vcpu-1gb networks: v4: - ip_address: 10.128.192.125 netmask: 255.255.0.0 gateway: nil type: private - ip_address: 192.241.247.248 netmask: 255.255.255.0 gateway: 192.241.247.1 type: public v6: [] region: name: New York 3 slug: nyc3 features: - private_networking - backups - ipv6 - metadata - install_agent - storage - image_transfer available: true sizes: - s-1vcpu-1gb - s-1vcpu-2gb - s-1vcpu-3gb - s-2vcpu-2gb - s-3vcpu-1gb - s-2vcpu-4gb - s-4vcpu-8gb - s-6vcpu-16gb - s-8vcpu-32gb - s-12vcpu-48gb - s-16vcpu-64gb - s-20vcpu-96gb - s-24vcpu-128gb - s-32vcpu-192g tags: - env:stage vpc_uuid: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 links: pages: {} meta: total: 3 droplet_create_request: value: name: example.com region: nyc3 size: s-1vcpu-1gb image: ubuntu-20-04-x64 ssh_keys: - 289794 - 3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45 backups: true ipv6: true monitoring: true tags: - env:prod - web user_data: "#cloud-config\nruncmd:\n - touch /test.txt\n" vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 droplet_multi_create_response: value: droplets: - id: 3164444 name: sub-01.example.com memory: 1024 vcpus: 1 disk: 25 disk_info: - type: local size: amount: 25 unit: gib locked: false status: new kernel: null created_at: '2020-07-21T18:37:44Z' features: - backups - private_networking - ipv6 - monitoring backup_ids: [] next_backup_window: null snapshot_ids: [] image: id: 63663980 name: 20.04 (LTS) x64 distribution: Ubuntu slug: ubuntu-20-04-x64 public: true regions: - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 created_at: '2020-05-15T05:47:50Z' type: snapshot min_disk_size: 20 size_gigabytes: 2.36 description: '' tags: [] status: available error_message: '' volume_ids: [] size: slug: s-1vcpu-1gb memory: 1024 vcpus: 1 disk: 25 transfer: 1 price_monthly: 5 price_hourly: 0.00743999984115362 regions: - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 available: true description: Basic size_slug: s-1vcpu-1gb networks: v4: [] v6: [] region: name: New York 3 slug: nyc3 features: - private_networking - backups - ipv6 - metadata - install_agent - storage - image_transfer available: true sizes: - s-1vcpu-1gb - s-1vcpu-2gb - s-1vcpu-3gb - s-2vcpu-2gb - s-3vcpu-1gb - s-2vcpu-4gb - s-4vcpu-8gb - s-6vcpu-16gb - s-8vcpu-32gb - s-12vcpu-48gb - s-16vcpu-64gb - s-20vcpu-96gb - s-24vcpu-128gb - s-32vcpu-192g tags: - web - env:prod - id: 3164445 name: sub-02.example.com memory: 1024 vcpus: 1 disk: 25 disk_info: - type: local size: amount: 25 unit: gib locked: false status: new kernel: null created_at: '2020-07-21T18:37:44Z' features: - backups - private_networking - ipv6 - monitoring backup_ids: [] next_backup_window: null snapshot_ids: [] image: id: 63663980 name: 20.04 (LTS) x64 distribution: Ubuntu slug: ubuntu-20-04-x64 public: true regions: - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 created_at: '2020-05-15T05:47:50Z' type: snapshot min_disk_size: 20 size_gigabytes: 2.36 description: '' tags: [] status: available error_message: '' volume_ids: [] size: slug: s-1vcpu-1gb memory: 1024 vcpus: 1 disk: 25 transfer: 1 price_monthly: 5 price_hourly: 0.00743999984115362 regions: - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 available: true description: Basic size_slug: s-1vcpu-1gb networks: v4: [] v6: [] region: name: New York 3 slug: nyc3 features: - private_networking - backups - ipv6 - metadata - install_agent - storage - image_transfer available: true sizes: - s-1vcpu-1gb - s-1vcpu-2gb - s-1vcpu-3gb - s-2vcpu-2gb - s-3vcpu-1gb - s-2vcpu-4gb - s-4vcpu-8gb - s-6vcpu-16gb - s-8vcpu-32gb - s-12vcpu-48gb - s-16vcpu-64gb - s-20vcpu-96gb - s-24vcpu-128gb - s-32vcpu-192g tags: - web - env:prod links: actions: - id: 7515 rel: create href: https://api.digitalocean.com/v2/actions/7515 - id: 7516 rel: create href: https://api.digitalocean.com/v2/actions/7516 gpu_droplets: value: droplets: - id: 448543583 name: ml-ai-ubuntu-gpu-h100x1-80gb-tor1 memory: 245760 vcpus: 20 disk: 720 disk_info: - type: local size: amount: 720 unit: gib - type: scratch size: amount: 5120 unit: gib locked: false status: active kernel: null created_at: '2024-09-30T15:23:36Z' features: - droplet_agent - private_networking backup_ids: [] next_backup_window: null snapshot_ids: [] image: id: 166407044 name: AI/ML Ready H100x1 distribution: Ubuntu slug: gpu-h100x1-base public: true regions: - nyc3 - nyc1 - sfo1 - nyc2 - ams2 - sgp1 - lon1 - ams3 - fra1 - tor1 - sfo2 - blr1 - sfo3 - syd1 created_at: '2024-09-27T15:35:19Z' min_disk_size: 25 type: base size_gigabytes: 18.47 description: GPU H100 1x Base Image tags: [] status: available volume_ids: [] size: slug: gpu-h100x1-80gb memory: 245760 vcpus: 20 disk: 720 transfer: 15 price_monthly: 4529.3 price_hourly: 6.74 regions: - tor1 available: true description: H100 GPU - 1X gpu_info: count: 1 vram: amount: 80 unit: gib model: nvidia_h100 disk_info: - type: local size: amount: 720 unit: gib - type: scratch size: amount: 5120 unit: gib size_slug: gpu-h100x1-80gb networks: v4: - ip_address: 10.128.192.124 netmask: 255.255.0.0 gateway: nil type: private - ip_address: 192.241.165.154 netmask: 255.255.255.0 gateway: 192.241.165.1 type: public v6: [] region: name: Toronto 1 slug: tor1 features: - backups - ipv6 - metadata - install_agent - storage - image_transfer - server_id - management_networking available: true sizes: - s-1vcpu-1gb - s-1vcpu-2gb - s-1vcpu-3gb - s-2vcpu-2gb - s-3vcpu-1gb - s-2vcpu-4gb - s-4vcpu-8gb - s-6vcpu-16gb - s-8vcpu-32gb - s-12vcpu-48gb - s-16vcpu-64gb - s-20vcpu-96gb - s-24vcpu-128gb - s-32vcpu-192g - gpu-h100x1-80gb - gpu-h100x8-640gb tags: [] vpc_uuid: e2fdd15c-6ae6-4c11-8c5d-72dae2ba1ad1 gpu_info: count: 1 vram: amount: 80 unit: gib model: nvidia_h100 links: {} meta: total: 1 droplet_create_response: value: droplet: id: 3164444 name: example.com memory: 1024 vcpus: 1 disk: 25 disk_info: - type: local size: amount: 25 unit: gib locked: false status: new kernel: null created_at: '2020-07-21T18:37:44Z' features: - backups - private_networking - ipv6 - monitoring backup_ids: [] next_backup_window: null snapshot_ids: [] image: id: 63663980 name: 20.04 (LTS) x64 distribution: Ubuntu slug: ubuntu-20-04-x64 public: true regions: - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 created_at: '2020-05-15T05:47:50Z' type: snapshot min_disk_size: 20 size_gigabytes: 2.36 description: '' tags: [] status: available error_message: '' volume_ids: [] size: slug: s-1vcpu-1gb memory: 1024 vcpus: 1 disk: 25 transfer: 1 price_monthly: 5 price_hourly: 0.00743999984115362 regions: - ams2 - ams3 - blr1 - fra1 - lon1 - nyc1 - nyc2 - nyc3 - sfo1 - sfo2 - sfo3 - sgp1 - tor1 available: true description: Basic size_slug: s-1vcpu-1gb networks: v4: [] v6: [] region: name: New York 3 slug: nyc3 features: - private_networking - backups - ipv6 - metadata - install_agent - storage - image_transfer available: true sizes: - s-1vcpu-1gb - s-1vcpu-2gb - s-1vcpu-3gb - s-2vcpu-2gb - s-3vcpu-1gb - s-2vcpu-4gb - s-4vcpu-8gb - s-6vcpu-16gb - s-8vcpu-32gb - s-12vcpu-48gb - s-16vcpu-64gb - s-20vcpu-96gb - s-24vcpu-128gb - s-32vcpu-192g tags: - web - env:prod links: actions: - id: 7515 rel: create href: https://api.digitalocean.com/v2/actions/7515 droplet_multi_create_request: value: names: - sub-01.example.com - sub-02.example.com region: nyc3 size: s-1vcpu-1gb image: ubuntu-20-04-x64 ssh_keys: - 289794 - 3b:16:e4:bf:8b:00:8b:b8:59:8c:a9:d3:f0:19:fa:45 backups: true ipv6: true monitoring: true tags: - env:prod - web user_data: "#cloud-config\nruncmd:\n - touch /test.txt\n" vpc_uuid: 760e09ef-dc84-11e8-981e-3cfdfeaae000 headers: ratelimit-reset: schema: type: integer example: 1444931833 description: The time when the oldest request will expire. The value is given in Unix epoch time. See https://developers.digitalocean.com/documentation/v2/#rate-limit for information about how requests expire. content-type: description: 'The type of data that is returned from a request. ' schema: type: string example: application/json; charset=utf-8 ratelimit-remaining: schema: type: integer example: 4816 description: The number of requests in your hourly quota that remain before you hit your request limit. See https://developers.digitalocean.com/documentation/v2/#rate-limit for information about how requests expire. ratelimit-limit: schema: type: integer example: 5000 description: The default limit on number of requests that can be made per hour and per minute. Current rate limits are 5000 requests per hour and 250 requests per minute. securitySchemes: bearer_auth: type: http scheme: bearer description: '## OAuth Authentication In order to interact with the DigitalOcean API, you or your application must authenticate. The DigitalOcean API handles this through OAuth, an open standard for authorization. OAuth allows you to delegate access to your account. Scopes can be used to grant full access, read-only access, or access to a specific set of endpoints. You can generate an OAuth token by visiting the [Apps & API](https://cloud.digitalocean.com/account/api/tokens) section of the DigitalOcean control panel for your account. An OAuth token functions as a complete authentication request. In effect, it acts as a substitute for a username and password pair. Because of this, it is absolutely **essential** that you keep your OAuth tokens secure. In fact, upon generation, the web interface will only display each token a single time in order to prevent the token from being compromised. DigitalOcean access tokens begin with an identifiable prefix in order to distinguish them from other similar tokens. - `dop_v1_` for personal access tokens generated in the control panel - `doo_v1_` for tokens generated by applications using [the OAuth flow](https://docs.digitalocean.com/reference/api/oauth-api/) - `dor_v1_` for OAuth refresh tokens ### Scopes Scopes act like permissions assigned to an API token. These permissions determine what actions the token can perform. You can create API tokens that grant read-only access, full access, or limited access to specific endpoints by using custom scopes. Generally, scopes are designed to match HTTP verbs and common CRUD operations (Create, Read, Update, Delete). | HTTP Verb | CRUD Operation | Scope | |---|---|---| | GET | Read | `:read` | | POST | Create | `:create` | | PUT/PATCH | Update | `:update` | | DELETE | Delete | `:delete` | For example, creating a new Droplet by making a `POST` request to the `/v2/droplets` endpoint requires the `droplet:create` scope while listing Droplets by making a `GET` request to the `/v2/droplets` endpoint requires the `droplet:read` scope. Each endpoint below specifies which scope is required to access it when using custom scopes. ### How to Authenticate with OAuth In order to make an authenticated request, include a bearer-type `Authorization` header containing your OAuth token. All requests must be made over HTTPS. ### Authenticate with a Bearer Authorization Header ``` curl -X $HTTP_METHOD -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" "https://api.digitalocean.com/v2/$OBJECT" ``` '