openapi: 3.2.0 info: title: DigitalOcean Block Storage API version: '2.0' description: '# Introduction The DigitalOcean API allows you to manage Droplets and resources within the DigitalOcean cloud in a simple, programmatic way using conventional HTTP requests.' 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: blockstorage description: 'DigitalOcean Block Storage Volumes provide expanded storage capacity for your Droplets and can be moved between Droplets within a specific region.' paths: /v2/volumes: get: operationId: volumes_list summary: List All Block Storage Volumes description: 'To list all of the block storage volumes available on your account, send a GET request to `/v2/volumes`. ## Filtering Results ### By Region The `region` may be provided as query parameter in order to restrict results to volumes available in a specific region. For example: `/v2/volumes?region=nyc1` ### By Name It is also possible to list volumes on your account that match a specified name. To do so, send a GET request with the volume''s name as a query parameter to `/v2/volumes?name=$VOLUME_NAME`. **Note:** You can only create one volume per region with the same name. ### By Name and Region It is also possible to retrieve information about a block storage volume by name. To do so, send a GET request with the volume''s name and the region slug for the region it is located in as query parameters to `/v2/volumes?name=$VOLUME_NAME®ion=nyc1`.' tags: - blockstorage parameters: - $ref: '#/components/parameters/volume_name' - $ref: '#/components/parameters/region' - $ref: '#/components/parameters/per_page' - $ref: '#/components/parameters/page' responses: '200': $ref: '#/components/responses/volumes' '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: "# List all volumes\ncurl -X GET \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/volumes?region=nyc1\"\n\n# List volumes filtered by name\ncurl -X GET \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/volumes?name=example\"" - 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 volumes, _, err := client.Storage.ListVolumes(ctx, opt)\n}" - lang: Ruby source: 'require ''droplet_kit'' token = ENV[''DIGITALOCEAN_TOKEN''] client = DropletKit::Client.new(access_token: token) volumes = client.volumes.all volumes.each' - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.volumes.list(region="nyc3")' security: - bearer_auth: - block_storage:read post: operationId: volumes_create summary: Create a New Block Storage Volume description: To create a new volume, send a POST request to `/v2/volumes`. Optionally, a `filesystem_type` attribute may be provided in order to automatically format the volume's filesystem. Pre-formatted volumes are automatically mounted when attached to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018. Attaching pre-formatted volumes to Droplets without support for auto-mounting is not recommended. tags: - blockstorage requestBody: required: true content: application/json: schema: anyOf: - $ref: '#/components/schemas/volumes_ext4' - $ref: '#/components/schemas/volumes_xfs' examples: ext4 volume: value: size_gigabytes: 10 name: ext4-example description: Block store for examples region: nyc1 filesystem_type: ext4 filesystem_label: ext4_volume_01 xfs volume: value: size_gigabytes: 10 name: xfs_example description: Block store for examples region: nyc1 filesystem_type: xfs filesystem_label: xfs_volume01 Volume from a snapshot: value: size_gigabytes: 10 name: snapshot_example snapshot_id: b0798135-fb76-11eb-946a-0a58ac146f33 region: nyc1 description: A new volume based on a snapshot filesystem_type: ext4 filesystem_label: ext4_volume_01 responses: '201': $ref: '#/components/responses/volume' '400': $ref: '#/components/responses/bad_request' '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 POST \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n -d '{\"size_gigabytes\":10, \"name\": \"example\", \"description\": \"Block store for examples\", \"region\": \"nyc1\", \"filesystem_type\": \"ext4\", \"filesystem_label\": \"example\"}' \\\n \"https://api.digitalocean.com/v2/volumes\"" - 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 := &VolumeCreateRequest{\n Region: \"nyc1\",\n Name: \"example\",\n Description: \"Block store for examples\",\n SizeGigaBytes: 10,\n }\n\n volume, _, err := client.Storage.CreateVolume(ctx, createRequest)\n}" - lang: Ruby source: "require 'droplet_kit'\ntoken = ENV['DIGITALOCEAN_TOKEN']\nclient = DropletKit::Client.new(access_token: token)\n\nvolume = DropletKit::Volume.new(\n size_gigabytes: 10,\n name: 'Example',\n description: 'Block store for examples',\n region: 'nyc1'\n)\nclient.volumes.create(volume)" - lang: Python source: "import os\nfrom pydo import Client\n\nclient = Client(token=os.environ.get(\"DIGITALOCEAN_TOKEN\"))\n\nreq = {\n \"size_gigabytes\": 10,\n \"name\": \"ext4-example\",\n \"description\": \"Block store for examples\",\n \"region\": \"nyc1\",\n \"filesystem_type\": \"ext4\",\n \"filesystem_label\": \"ext4_volume_01\"\n}\n\nresp = client.volumes.create(body=req)" security: - bearer_auth: - block_storage:create delete: operationId: volumes_delete_byName summary: Delete a Block Storage Volume by Name description: 'Block storage volumes may also be deleted by name by sending a DELETE request with the volume''s **name** and the **region slug** for the region it is located in as query parameters to `/v2/volumes?name=$VOLUME_NAME®ion=nyc1`. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.' tags: - blockstorage parameters: - $ref: '#/components/parameters/volume_name' - $ref: '#/components/parameters/region' responses: '204': $ref: '#/components/responses/no_content' '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/volumes?name=example®ion=nyc1\" " - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.volumes.delete_by_name(name="ext4-ex")' security: - bearer_auth: - block_storage:delete /v2/volumes/snapshots/{snapshot_id}: get: operationId: volumeSnapshots_get_byId summary: Retrieve an Existing Volume Snapshot description: To retrieve the details of a snapshot that has been created from a volume, send a GET request to `/v2/volumes/snapshots/$VOLUME_SNAPSHOT_ID`. tags: - blockstorage parameters: - $ref: '#/components/parameters/volume_snapshot_id' responses: '200': $ref: '#/components/responses/volumeSnapshot' '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/volumes/snapshots/fbe805e8-866b-11e6-96bf-000f53315a41\"" - lang: Python source: "import os\nfrom pydo import Client\n\nclient = Client(token=os.environ.get(\"DIGITALOCEAN_TOKEN\"))\n\nreq = {\n \"name\": \"big-data-snapshot1475261774\"\n}\n\nresp = client.volume_snapshots.get_by_id(snapshot_id=\"da3aa3a\")" security: - bearer_auth: - block_storage_snapshot:read delete: operationId: volumeSnapshots_delete_byId summary: Delete a Volume Snapshot description: 'To delete a volume snapshot, send a DELETE request to `/v2/volumes/snapshots/$VOLUME_SNAPSHOT_ID`. A status of 204 will be given. This indicates that the request was processed successfully, but that no response body is needed.' tags: - blockstorage parameters: - $ref: '#/components/parameters/volume_snapshot_id' responses: '204': $ref: '#/components/responses/no_content' '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/snapshots/fbe805e8-866b-11e6-96bf-000f53315a41\"" - 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.Storage.DeleteSnapshot(ctx, \"82a48a18-873f-11e6-96bf-000f53315a41\")\n}" - lang: Ruby source: 'require ''droplet_kit'' token = ENV[''DIGITALOCEAN_TOKEN''] client = DropletKit::Client.new(access_token: token) client.snapshots.delete(id: "fbe805e8-866b-11e6-96bf-000f53315a41")' - lang: Python source: "import os\nfrom pydo import Client\n\nclient = Client(token=os.environ.get(\"DIGITALOCEAN_TOKEN\"))\n\nreq = {\n \"name\": \"big-data-snapshot1475261774\"\n}\n\nresp = client.volume_snapshots.delete_by_id(snapshot_id=\"da3aa3a\")" security: - bearer_auth: - block_storage_snapshot:delete /v2/volumes/{volume_id}: get: operationId: volumes_get summary: Retrieve an Existing Block Storage Volume description: To show information about a block storage volume, send a GET request to `/v2/volumes/$VOLUME_ID`. tags: - blockstorage parameters: - $ref: '#/components/parameters/volume_id' responses: '200': $ref: '#/components/responses/volume' '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: "# Retrieve an existing volume\ncurl -X GET \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/volumes/7724db7c-e098-11e5-b522-000f53304e51\"\n\n# Retrieve and existing volume by name\ncurl -X GET \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n \"https://api.digitalocean.com/v2/volumes?name=example®ion=nyc1\"" - 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 volume, _, err := client.Storage.GetVolume(ctx, \"7724db7c-e098-11e5-b522-000f53304e51\")\n}" - lang: Ruby source: 'require ''droplet_kit'' token = ENV[''DIGITALOCEAN_TOKEN''] client = DropletKit::Client.new(access_token: token) client.volumes.find(id: ''7724db7c-e098-11e5-b522-000f53304e51'')' - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.volumes.get(volume_id="7724db7c")' security: - bearer_auth: - block_storage:read delete: operationId: volumes_delete summary: Delete a Block Storage Volume description: 'To delete a block storage volume, destroying all data and removing it from your account, send a DELETE request to `/v2/volumes/$VOLUME_ID`. No response body will be sent back, but the response code will indicate success. Specifically, the response code will be a 204, which means that the action was successful with no returned body data.' tags: - blockstorage parameters: - $ref: '#/components/parameters/volume_id' responses: '204': $ref: '#/components/responses/no_content' '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/volumes/7724db7c-e098-11e5-b522-000f53304e51\"" - 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.Storage.DeleteVolume(ctx, \"7724db7c-e098-11e5-b522-000f53304e51\")\n}" - lang: Ruby source: 'require ''droplet_kit'' token = ENV[''DIGITALOCEAN_TOKEN''] client = DropletKit::Client.new(access_token: token) client.volumes.delete(id: ''7724db7c-e098-11e5-b522-000f53304e51'')' - lang: Python source: 'import os from pydo import Client client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN")) resp = client.volumes.delete(volume_id="7724db7c")' security: - bearer_auth: - block_storage:delete /v2/volumes/{volume_id}/snapshots: get: operationId: volumeSnapshots_list summary: List Snapshots for a Volume description: To retrieve the snapshots that have been created from a volume, send a GET request to `/v2/volumes/$VOLUME_ID/snapshots`. tags: - blockstorage parameters: - $ref: '#/components/parameters/volume_id' - $ref: '#/components/parameters/per_page' - $ref: '#/components/parameters/page' responses: '200': $ref: '#/components/responses/volumeSnapshots' '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/volumes/82a48a18-873f-11e6-96bf-000f53315a41/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 volumes, _, err := client.Storage.ListSnapshots(ctx, '82a48a18-873f-11e6-96bf-000f53315a41', opt)\n}" - lang: Ruby source: 'require ''droplet_kit'' token = ENV[''DIGITALOCEAN_TOKEN''] client = DropletKit::Client.new(access_token: token) snapshots = client.volumes.snapshots(id: ''82a48a18-873f-11e6-96bf-000f53315a41'') snapshots.each' - lang: Python source: "import os\nfrom pydo import Client\n\nclient = Client(token=os.environ.get(\"DIGITALOCEAN_TOKEN\"))\n\nreq = {\n \"name\": \"big-data-snapshot1475261774\"\n}\n\nresp = client.volume_snapshots.list(snapshot_id=\"da3aa3a\")" security: - bearer_auth: - block_storage_snapshot:read post: operationId: volumeSnapshots_create summary: Create Snapshot from a Volume description: To create a snapshot from a volume, sent a POST request to `/v2/volumes/$VOLUME_ID/snapshots`. tags: - blockstorage parameters: - $ref: '#/components/parameters/volume_id' requestBody: required: true content: application/json: schema: properties: name: type: string description: A human-readable name for the volume snapshot. example: big-data-snapshot1475261774 tags: $ref: '#/components/schemas/tags_array' required: - name example: name: big-data-snapshot1475261774 responses: '201': $ref: '#/components/responses/volumeSnapshot' '400': $ref: '#/components/responses/bad_request' '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 POST \\\n -H 'Content-Type: application/json' \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n -d '{\"name\":\"big-data-snapshot1475261774\", \"tags\":[\"aninterestingtag\"]}' \\\n \"https://api.digitalocean.com/v2/volumes/82a48a18-873f-11e6-96bf-000f53315a41/snapshots\"" - 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 snapshot, _, err := client.Storage.CreateSnapshot(ctx, &godo.SnapshotCreateRequest{\n VolumeID: \"82a48a18-873f-11e6-96bf-000f53315a41\",\n Name: \"my snapshot\",\n Description: \"my description\",\n Tags: []string{\"one\", \"two\"},\n })\n}" - lang: Ruby source: 'require ''droplet_kit'' token = ENV[''DIGITALOCEAN_TOKEN''] client = DropletKit::Client.new(access_token: token) client.volumes.create_snapshot(id: "82a48a18-873f-11e6-96bf-000f53315a41", name: "big-data-snapshot1475261774")' - lang: Python source: "import os\nfrom pydo import Client\n\nclient = Client(token=os.environ.get(\"DIGITALOCEAN_TOKEN\"))\n\nreq = {\n \"name\": \"big-data-snapshot1475261774\"\n}\n\nresp = client.volume_snapshots.create(volume_id=\"da3aa3a\", body=req)" security: - bearer_auth: - block_storage_snapshot:create components: 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. 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. volumes: description: The response will be a JSON object with a key called `volumes`. This will be set to an array of volume objects, each of which will contain the standard volume attributes. 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: volumes: type: array items: $ref: '#/components/schemas/volume_full' description: Array of volumes. required: - volumes - $ref: '#/components/schemas/pagination' - $ref: '#/components/schemas/meta' examples: All Volumes: $ref: '#/components/examples/volumes_all' Filtered by Name: $ref: '#/components/examples/volumes_filtered_by_name' Filtered by Region: $ref: '#/components/examples/volumes_filtered_by_region' 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 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. 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 no_content: description: The action was successful and the response body is empty. headers: ratelimit-limit: $ref: '#/components/headers/ratelimit-limit' ratelimit-remaining: $ref: '#/components/headers/ratelimit-remaining' ratelimit-reset: $ref: '#/components/headers/ratelimit-reset' volumeSnapshot: description: You will get back a JSON object that has a `snapshot` key. This will contain the standard snapshot 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: snapshot: $ref: '#/components/schemas/snapshots' example: snapshot: id: 8fa70202-873f-11e6-8b68-000f533176b1 name: big-data-snapshot1475261774 regions: - nyc1 created_at: '2020-09-30T18:56:14Z' resource_id: 82a48a18-873f-11e6-96bf-000f53315a41 resource_type: volume min_disk_size: 10 size_gigabytes: 10 tags: - aninterestingtag volumeSnapshots: description: You will get back a JSON object that has a `snapshots` key. This will be set to an array of snapshot objects, each of which contain the standard snapshot attributes 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/snapshots' - $ref: '#/components/schemas/pagination' - $ref: '#/components/schemas/meta' example: snapshots: - id: 8eb4d51a-873f-11e6-96bf-000f53315a41 name: big-data-snapshot1475261752 regions: - nyc1 created_at: '2020-09-30T18:56:12Z' resource_id: 82a48a18-873f-11e6-96bf-000f53315a41 resource_type: volume min_disk_size: 10 size_gigabytes: 0 tags: null links: {} meta: total: 1 bad_request: description: Bad Request 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: bad_request message: error parsing request body request_id: 4851a473-1621-42ea-b2f9-5071c0ea8414 volume: description: The response will be a JSON object with a key called `volume`. The value will be an object containing the standard attributes associated with a volume. 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: volume: $ref: '#/components/schemas/volume_full' example: volume: id: 506f78a4-e098-11e5-ad9f-000f53306ae1 region: name: New York 1 slug: nyc1 sizes: - s-1vcpu-1gb - s-1vcpu-2gb - s-1vcpu-3gb - s-2vcpu-2gb - s-3vcpu-1gb - s-2vcpu-4gb - s-4vcpu-8gb - s-6vcpu-16gb - s-8vcpu-32gb - s-12vcpu-48gb - s-16vcpu-64gb - s-20vcpu-96gb - s-24vcpu-128gb - s-32vcpu-192gb features: - private_networking - backups - ipv6 - metadata available: true droplet_ids: [] name: example description: Block store for examples size_gigabytes: 10 filesystem_type: ext4 filesystem_label: example created_at: '2020-03-02T17:00:49Z' schemas: volumes_xfs: type: object allOf: - $ref: '#/components/schemas/volume_base' - $ref: '#/components/schemas/volume_snapshot_id' - $ref: '#/components/schemas/volume_write_file_system_type' - properties: region: $ref: '#/components/schemas/region_slug' filesystem_label: allOf: - $ref: '#/components/schemas/volume_write_file_system_label' - maxLength: 12 required: - name - size_gigabytes - region 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 snapshots: allOf: - type: object properties: id: type: string example: '6372321' description: The unique identifier for the snapshot. required: - id - $ref: '#/components/schemas/snapshots_base' - type: object properties: resource_id: type: string example: '200776916' description: The unique identifier for the resource that the snapshot originated from. resource_type: type: string enum: - droplet - volume example: droplet description: The type of resource that the snapshot originated from. tags: description: An array of Tags the snapshot has been tagged with. type: - array - 'null' items: type: string example: - web - env:prod required: - resource_id - resource_type - tags 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 volume_write_file_system_label: type: string description: The label applied to the filesystem. Labels for ext4 type filesystems may contain 16 characters while labels for xfs type filesystems are limited to 12 characters. May only be used in conjunction with filesystem_type. example: example meta_properties: type: object description: Information about the response itself. properties: total: description: Number of objects returned by the request. type: integer example: 1 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 pagination: type: object properties: links: $ref: '#/components/schemas/page_links' volume_base: type: object properties: id: type: string description: The unique identifier for the block storage volume. example: 506f78a4-e098-11e5-ad9f-000f53306ae1 readOnly: true droplet_ids: type: - array - 'null' items: type: integer description: An array containing the IDs of the Droplets the volume is attached to. Note that at this time, a volume can only be attached to a single Droplet. example: [] readOnly: true name: type: string description: A human-readable name for the block storage volume. Must be lowercase and be composed only of numbers, letters and "-", up to a limit of 64 characters. The name must begin with a letter. example: example description: type: string description: An optional free-form text field to describe a block storage volume. example: Block store for examples size_gigabytes: type: integer description: The size of the block storage volume in GiB (1024^3). This field does not apply when creating a volume from a snapshot. example: 10 created_at: type: string description: A time value given in ISO8601 combined date and time format that represents when the block storage volume was created. example: '2020-03-02T17:00:49Z' readOnly: true tags: $ref: '#/components/schemas/tags_array' meta: type: object properties: meta: allOf: - $ref: '#/components/schemas/meta_properties' - required: - total required: - meta 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 volume_full: type: object allOf: - $ref: '#/components/schemas/volume_base' - properties: region: allOf: - description: The region that the block storage volume is located in. When setting a region, the value should be the slug identifier for the region. When you query a block storage volume, the entire region object will be returned. - $ref: '#/components/schemas/region' example: name: New York 1 slug: nyc1 sizes: - s-1vcpu-1gb - s-1vcpu-2gb - s-1vcpu-3gb - s-2vcpu-2gb - s-3vcpu-1gb - s-2vcpu-4gb - s-4vcpu-8gb - s-6vcpu-16gb - s-8vcpu-32gb - s-12vcpu-48gb - s-16vcpu-64gb - s-20vcpu-96gb - s-24vcpu-128gb - s-32vcpu-192gb features: - private_networking - backups - ipv6 - metadata available: true readOnly: true filesystem_type: type: string description: The type of filesystem currently in-use on the volume. example: ext4 filesystem_label: type: string description: The label currently applied to the filesystem. example: example volumes_ext4: type: object allOf: - $ref: '#/components/schemas/volume_base' - $ref: '#/components/schemas/volume_snapshot_id' - $ref: '#/components/schemas/volume_write_file_system_type' - properties: region: $ref: '#/components/schemas/region_slug' filesystem_label: allOf: - $ref: '#/components/schemas/volume_write_file_system_label' - maxLength: 16 required: - name - size_gigabytes - region volume_write_file_system_type: type: object properties: filesystem_type: type: string description: The name of the filesystem type to be used on the volume. When provided, the volume will automatically be formatted to the specified filesystem type. Currently, the available options are `ext4` and `xfs`. Pre-formatted volumes are automatically mounted when attached to Ubuntu, Debian, Fedora, Fedora Atomic, and CentOS Droplets created on or after April 26, 2018. Attaching pre-formatted volumes to other Droplets is not recommended. example: ext4 forward_links: allOf: - $ref: '#/components/schemas/link_to_last_page' - $ref: '#/components/schemas/link_to_next_page' 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 backward_links: allOf: - $ref: '#/components/schemas/link_to_first_page' - $ref: '#/components/schemas/link_to_prev_page' 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 volume_snapshot_id: properties: snapshot_id: type: string description: The unique identifier for the volume snapshot from which to create the volume. example: b0798135-fb76-11eb-946a-0a58ac146f33 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 tags_array: type: - array - 'null' items: type: string 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 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 parameters: page: in: query name: page required: false description: Which 'page' of paginated results to return. schema: type: integer minimum: 1 default: 1 example: 1 volume_snapshot_id: name: snapshot_id in: path description: The unique identifier for the snapshot. schema: type: string required: true example: fbe805e8-866b-11e6-96bf-000f53315a41 volume_id: name: volume_id in: path required: true description: The ID of the block storage volume. schema: type: string format: uuid example: 7724db7c-e098-11e5-b522-000f53304e51 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 region: name: region in: query description: The slug identifier for the region where the resource is available. schema: $ref: '#/components/schemas/region_slug' example: nyc3 volume_name: name: name in: query description: The block storage volume's name. schema: type: string example: example examples: volumes_filtered_by_region: value: volumes: - id: 506f78a4-e098-11e5-ad9f-000f53306ae1 region: name: New York 1 slug: nyc1 sizes: - s-1vcpu-1gb - s-1vcpu-2gb - s-1vcpu-3gb - s-2vcpu-2gb - s-3vcpu-1gb - s-2vcpu-4gb - s-4vcpu-8gb - s-6vcpu-16gb - s-8vcpu-32gb - s-12vcpu-48gb - s-16vcpu-64gb - s-20vcpu-96gb - s-24vcpu-128gb - s-32vcpu-192gb features: - private_networking - backups - ipv6 - metadata available: true droplet_ids: [] name: example description: Block store for examples size_gigabytes: 10 created_at: '2016-03-02T17:00:49Z' filesystem_type: ext4 filesystem_label: example tags: - aninterestingtag links: {} meta: total: 1 volumes_all: value: volumes: - id: 506f78a4-e098-11e5-ad9f-000f53306ae1 region: name: New York 1 slug: nyc1 sizes: - s-1vcpu-1gb - s-1vcpu-2gb - s-1vcpu-3gb - s-2vcpu-2gb - s-3vcpu-1gb - s-2vcpu-4gb - s-4vcpu-8gb - s-6vcpu-16gb - s-8vcpu-32gb - s-12vcpu-48gb - s-16vcpu-64gb - s-20vcpu-96gb - s-24vcpu-128gb - s-32vcpu-192gb features: - private_networking - backups - ipv6 - metadata available: true droplet_ids: [] name: example description: Block store for examples size_gigabytes: 10 created_at: '2016-03-02T17:00:49Z' filesystem_type: ext4 filesystem_label: example tags: - aninterestingtag - id: 506f78a4-e098-11e5-ad9f-000f53305eb2 region: name: New York 3 slug: nyc3 sizes: - s-1vcpu-1gb - s-1vcpu-2gb - s-1vcpu-3gb - s-2vcpu-2gb - s-3vcpu-1gb - s-2vcpu-4gb - s-4vcpu-8gb - s-6vcpu-16gb - s-8vcpu-32gb - s-12vcpu-48gb - s-16vcpu-64gb - s-20vcpu-96gb - s-24vcpu-128gb - s-32vcpu-192gb features: - private_networking - backups - ipv6 - metadata available: true droplet_ids: [] name: example description: Block store for examples size_gigabytes: 10 created_at: '2016-03-02T17:01:49Z' filesystem_type: ext4 filesystem_label: example tags: - aninterestingtag links: {} meta: total: 2 volumes_filtered_by_name: value: volumes: - id: 506f78a4-e098-11e5-ad9f-000f53306ae1 region: name: New York 1 slug: nyc1 sizes: - s-1vcpu-1gb - s-1vcpu-2gb - s-1vcpu-3gb - s-2vcpu-2gb - s-3vcpu-1gb - s-2vcpu-4gb - s-4vcpu-8gb - s-6vcpu-16gb - s-8vcpu-32gb - s-12vcpu-48gb - s-16vcpu-64gb - s-20vcpu-96gb - s-24vcpu-128gb - s-32vcpu-192gb features: - private_networking - backups - ipv6 - metadata available: true droplet_ids: [] name: example description: Block store for examples size_gigabytes: 10 created_at: '2016-03-02T17:00:49Z' filesystem_type: ext4 filesystem_label: example tags: - aninterestingtag links: {} meta: total: 1 headers: 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. 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. 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. 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" ``` '