Digital Ocean Snapshots API

openapi: 3.2.0
info:
  title: DigitalOcean Snapshots 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: Snapshots
  description: 'Snapshots are saved

    instances of a Droplet or a block storage volume, which is reflected in

    the `resource_type` attribute. In order to avoid problems with compressing

    filesystems, each defines a `min_disk_size` attribute which is the minimum

    size of the Droplet or volume disk when creating a new resource from the

    saved snapshot.


    To interact with snapshots, you will generally send requests to the

    snapshots endpoint at `/v2/snapshots`.'
paths:
  /v2/snapshots:
    get:
      operationId: snapshots_list
      summary: List All Snapshots
      description: 'To list all of the snapshots available on your account, send a GET request to

        `/v2/snapshots`.


        The response will be a JSON object with a key called `snapshots`. This will be

        set to an array of `snapshot` objects, each of which will contain the standard

        snapshot attributes.


        ### Filtering Results by Resource Type


        It''s possible to request filtered results by including certain query parameters.


        #### List Droplet Snapshots


        To retrieve only snapshots based on Droplets, include the `resource_type`

        query parameter set to `droplet`. For example, `/v2/snapshots?resource_type=droplet`.


        #### List Volume Snapshots


        To retrieve only snapshots based on volumes, include the `resource_type`

        query parameter set to `volume`. For example, `/v2/snapshots?resource_type=volume`.'
      tags:
      - Snapshots
      parameters:
      - $ref: '#/components/parameters/per_page'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/snapshot_resource_type'
      responses:
        '200':
          $ref: '#/components/responses/snapshots'
        '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 snapshots\ncurl -X GET \\\n  -H 'Content-Type: application/json' \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n  \"https://api.digitalocean.com/v2/snapshots?page=1&per_page=1\"\n\n# List all Droplet snapshots\ncurl -X GET \\\n  -H 'Content-Type: application/json' \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n  \"https://api.digitalocean.com/v2/snapshots?page=1&per_page=1&resource_type=droplet\"\n\n# List volume snapshots\ncurl -X GET \\\n  -H 'Content-Type: application/json' \\\n  -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n  \"https://api.digitalocean.com/v2/snapshots?page=1&per_page=1&resource_type=volume\""
      - 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// List all snapshots\n    snapshots, _, err := client.Snapshots.List(ctx, opt)\n\n// List all Droplet snapshots\n//  snapshots, _, err := client.Snapshots.ListDroplet(ctx, opt)\n\n// List all volume snapshots\n//  snapshots, _, err := client.Snapshots.ListVolume(ctx, opt)\n}"
      - lang: Ruby
        source: 'require ''droplet_kit''

          token = ENV[''DIGITALOCEAN_TOKEN'']

          client = DropletKit::Client.new(access_token: token)


          # List all snapshots

          snapshots = client.snapshots.all

          snapshots.each


          # List all Droplet snapshots

          # snapshots = client.snapshots.all(resource_type: ''droplet'')

          # snapshots.each


          # List volume snapshots

          # snapshots = client.snapshots.all(resource_type: ''volume'')

          # snapshots.each'
      - lang: Python
        source: 'import os

          from pydo import Client


          client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))


          resp = client.snapshots.list()'
      security:
      - bearer_auth:
        - snapshot:read
  /v2/snapshots/{snapshot_id}:
    get:
      operationId: snapshots_get
      summary: Retrieve an Existing Snapshot
      description: 'To retrieve information about a snapshot, send a GET request to

        `/v2/snapshots/$SNAPSHOT_ID`.


        The response will be a JSON object with a key called `snapshot`. The value of

        this will be an snapshot object containing the standard snapshot attributes.'
      tags:
      - Snapshots
      parameters:
      - $ref: '#/components/parameters/snapshot_id'
      responses:
        '200':
          $ref: '#/components/responses/snapshots_existing'
        '400':
          $ref: '#/components/responses/not_a_snapshot'
        '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/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    snapshot, _, err := client.Snapshots.Get(ctx, 'fbe805e8-866b-11e6-96bf-000f53315a41')\n}"
      - lang: Ruby
        source: 'require ''droplet_kit''

          token = ENV[''DIGITALOCEAN_TOKEN'']

          client = DropletKit::Client.new(access_token: token)


          snapshot = client.snapshots.find(id: ''fbe805e8-866b-11e6-96bf-000f53315a41'')'
      - lang: cURL
        source: 'import os

          from pydo import Client


          client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))


          resp = client.snapshots.get(snapshot_id="fbe805e8")'
      security:
      - bearer_auth:
        - snapshot:read
    delete:
      operationId: snapshots_delete
      summary: Delete a Snapshot
      description: 'Both Droplet and volume snapshots are managed through the `/v2/snapshots/`

        endpoint. To delete a snapshot, send a DELETE request to

        `/v2/snapshots/$SNAPSHOT_ID`.


        A status of 204 will be given. This indicates that the request was processed

        successfully, but that no response body is needed.'
      tags:
      - Snapshots
      parameters:
      - $ref: '#/components/parameters/snapshot_id'
      responses:
        '204':
          $ref: '#/components/responses/no_content'
        '400':
          $ref: '#/components/responses/not_a_snapshot'
        '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.Snapshots.Delete(ctx, 'fbe805e8-866b-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

          from pydo import Client


          client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))


          resp = client.snapshots.delete(snapshot_id="fbe805e8")'
      security:
      - bearer_auth:
        - image:delete
        - snapshot:delete
components:
  schemas:
    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_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
    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
    backward_links:
      allOf:
      - $ref: '#/components/schemas/link_to_first_page'
      - $ref: '#/components/schemas/link_to_prev_page'
    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
    meta:
      type: object
      properties:
        meta:
          allOf:
          - $ref: '#/components/schemas/meta_properties'
          - required:
            - total
      required:
      - meta
    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
    pagination:
      type: object
      properties:
        links:
          $ref: '#/components/schemas/page_links'
    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
    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
    forward_links:
      allOf:
      - $ref: '#/components/schemas/link_to_last_page'
      - $ref: '#/components/schemas/link_to_next_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
    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
  responses:
    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
    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
    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'
    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.
    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.
    not_a_snapshot:
      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: the resource is not a snapshot
            request_id: bbd8d7d4-2beb-4be1-a374-338e6165e32d
    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.
    snapshots:
      description: A JSON object with a key of `snapshots`.
      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'
          examples:
            All Snapshots:
              $ref: '#/components/examples/snapshots_all'
            Droplets Snapshots:
              $ref: '#/components/examples/snapshots_droplets_only'
            Volume Snapshots:
              $ref: '#/components/examples/snapshots_volumes_only'
    snapshots_existing:
      description: 'A JSON object with a key called `snapshot`.

        '
      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'
  examples:
    snapshots_droplets_only:
      value:
        snapshots:
        - id: '6372321'
          name: web-01-1595954862243
          created_at: '2020-07-28T16:47:44Z'
          regions:
          - nyc3
          - sfo3
          resource_id: '200776916'
          resource_type: droplet
          min_disk_size: 25
          size_gigabytes: 2.34
          tags:
          - web
          - env:prod
        links: {}
        meta:
          total: 1
    snapshots_volumes_only:
      value:
        snapshots:
        - id: fbe805e8-866b-11e6-96bf-000f53315a41
          name: pvc-01-1595954862243
          created_at: '2019-09-28T23:14:30Z'
          regions:
          - nyc1
          resource_id: 89bcc42f-85cf-11e6-a004-000f53315871
          resource_type: volume
          min_disk_size: 2
          size_gigabytes: 0.1008
          tags:
          - k8s
        links: {}
        meta:
          total: 1
    snapshots_all:
      value:
        snapshots:
        - id: '6372321'
          name: web-01-1595954862243
          created_at: '2020-07-28T16:47:44Z'
          regions:
          - nyc3
          - sfo3
          resource_id: '200776916'
          resource_type: droplet
          min_disk_size: 25
          size_gigabytes: 2.34
          tags:
          - web
          - env:prod
        - id: fbe805e8-866b-11e6-96bf-000f53315a41
          name: pvc-01-1595954862243
          created_at: '2019-09-28T23:14:30Z'
          regions:
          - nyc1
          resource_id: 89bcc42f-85cf-11e6-a004-000f53315871
          resource_type: volume
          min_disk_size: 2
          size_gigabytes: 0.1008
          tags:
          - k8s
        links: {}
        meta:
          total: 2
  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
    snapshot_id:
      in: path
      name: snapshot_id
      required: true
      description: Either the ID of an existing snapshot. This will be an integer for a Droplet snapshot or a string for a volume snapshot.
      schema:
        anyOf:
        - type: integer
          description: The ID of a Droplet snapshot.
          example: 6372321
        - type: string
          description: The ID of a volume snapshot.
          example: fbe805e8-866b-11e6-96bf-000f53315a41
      example: 6372321
    snapshot_resource_type:
      in: query
      name: resource_type
      description: Used to filter snapshots by a resource type.
      required: false
      schema:
        type: string
        enum:
        - droplet
        - volume
      example: droplet
    page:
      in: query
      name: page
      required: false
      description: Which 'page' of paginated results to return.
      schema:
        type: integer
        minimum: 1
        default: 1
      example: 1
  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.
    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 | `<resource>:read` |

        | POST | Create | `<resource>:create` |

        | PUT/PATCH | Update | `<resource>:update` |

        | DELETE | Delete | `<resource>: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"

        ```

        '