Initiate

Initiate a Droplet Action

gpu_droplets.actions.initiate(, ) -> ActionInitiateResponse

post/v2/droplets/{droplet_id}/actions

To initiate an action on a Droplet send a POST request to /v2/droplets/$DROPLET_ID/actions. In the JSON body to the request, set the type attribute to on of the supported action types:

Action	Details	Additionally Required Permission
`enable_backups`	Enables backups for a Droplet
`disable_backups`	Disables backups for a Droplet
`change_backup_policy`	Update the backup policy for a Droplet
`reboot`	Reboots a Droplet. A `reboot` action is an attempt to reboot the Droplet in a graceful way, similar to using the `reboot` command from the console.
`power_cycle`	Power cycles a Droplet. A `powercycle` action is similar to pushing the reset button on a physical machine, it's similar to booting from scratch.
`shutdown`	Shutsdown a Droplet. A shutdown action is an attempt to shutdown the Droplet in a graceful way, similar to using the `shutdown` command from the console. Since a `shutdown` command can fail, this action guarantees that the command is issued, not that it succeeds. The preferred way to turn off a Droplet is to attempt a shutdown, with a reasonable timeout, followed by a `power_off` action to ensure the Droplet is off.
`power_off`	Powers off a Droplet. A `power_off` event is a hard shutdown and should only be used if the `shutdown` action is not successful. It is similar to cutting the power on a server and could lead to complications.
`power_on`	Powers on a Droplet.
`restore`	Restore a Droplet using a backup image. The image ID that is passed in must be a backup of the current Droplet instance. The operation will leave any embedded SSH keys intact.	droplet:admin
`password_reset`	Resets the root password for a Droplet. A new password will be provided via email. It must be changed after first use.	droplet:admin
`resize`	Resizes a Droplet. Set the `size` attribute to a size slug. If a permanent resize with disk changes included is desired, set the `disk` attribute to `true`.	droplet:create
`rebuild`	Rebuilds a Droplet from a new base image. Set the `image` attribute to an image ID or slug.	droplet:admin
`rename`	Renames a Droplet.
`change_kernel`	Changes a Droplet's kernel. Only applies to Droplets with externally managed kernels. All Droplets created after March 2017 use internal kernels by default.
`enable_ipv6`	Enables IPv6 for a Droplet. Once enabled for a Droplet, IPv6 can not be disabled. When enabling IPv6 on an existing Droplet, additional OS-level configuration is required.
`snapshot`	Takes a snapshot of a Droplet.	image:create

ParametersExpand Collapse

droplet_id: int

minimum1

type: Literal["enable_backups", "disable_backups", "reboot", 12 more]

The type of action to initiate for the Droplet.

Accepts one of the following:

"enable_backups"

"disable_backups"

"reboot"

"power_cycle"

"shutdown"

"power_off"

"power_on"

"restore"

"password_reset"

"resize"

"rebuild"

"rename"

"change_kernel"

"enable_ipv6"

"snapshot"

ReturnsExpand Collapse

class ActionInitiateResponse: …

action: Optional[Action]

id: Optional[int]

A unique numeric ID that can be used to identify and reference an action.

completed_at: Optional[datetime]

A time value given in ISO8601 combined date and time format that represents when the action was completed.

formatdate-time

region: Optional[Region]

available: bool

This is a boolean value that represents whether new Droplets can be created in this region.

features: List[str]

This attribute is set to an array which contains features available in this region

name: str

The display name of the region. This will be a full name that is used in the control panel and other interfaces.

sizes: List[str]

This attribute is set to an array which contains the identifying slugs for the sizes available in this region. sizes:read is required to view.

slug: str

A human-readable string that is used as a unique identifier for each region.

region_slug: Optional[str]

A human-readable string that is used as a unique identifier for each region.

resource_id: Optional[int]

A unique identifier for the resource that the action is associated with.

resource_type: Optional[str]

The type of resource that the action is associated with.

started_at: Optional[datetime]

A time value given in ISO8601 combined date and time format that represents when the action was initiated.

formatdate-time

status: Optional[Literal["in-progress", "completed", "errored"]]

The current status of the action. This can be "in-progress", "completed", or "errored".

Accepts one of the following:

"in-progress"

"completed"

"errored"

type: Optional[str]

This is the type of action that the object represents. For example, this could be "transfer" to represent the state of an image transfer action.

Initiate a Droplet Action

from gradient import Gradient

client = Gradient(
    access_token="My Access Token",
)
response = client.gpu_droplets.actions.initiate(
    droplet_id=3164444,
    type="reboot",
)
print(response.action)

{
  "action": {
    "id": 36804636,
    "completed_at": "2020-11-14T16:30:06Z",
    "region": {
      "available": true,
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata",
        "install_agent",
        "storage",
        "image_transfer"
      ],
      "name": "New York 3",
      "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"
      ],
      "slug": "nyc3"
    },
    "region_slug": "nyc3",
    "resource_id": 3164444,
    "resource_type": "droplet",
    "started_at": "2020-11-14T16:29:21Z",
    "status": "completed",
    "type": "create"
  }
}

Returns Examples

{
  "action": {
    "id": 36804636,
    "completed_at": "2020-11-14T16:30:06Z",
    "region": {
      "available": true,
      "features": [
        "private_networking",
        "backups",
        "ipv6",
        "metadata",
        "install_agent",
        "storage",
        "image_transfer"
      ],
      "name": "New York 3",
      "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"
      ],
      "slug": "nyc3"
    },
    "region_slug": "nyc3",
    "resource_id": 3164444,
    "resource_type": "droplet",
    "started_at": "2020-11-14T16:29:21Z",
    "status": "completed",
    "type": "create"
  }
}