Initiate

Initiate a Droplet Action

client.gpuDroplets.actions.initiate(, , ?): ActionInitiateResponse { action }

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

dropletID: number

ActionInitiateParams = DropletAction | DropletActionEnableBackups | DropletActionChangeBackupPolicy | 6 more

ActionInitiateParamsBase { type }

type: "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"

DropletAction extends ActionInitiateParamsBase { type }

DropletActionEnableBackups extends ActionInitiateParamsBase { type }

DropletActionChangeBackupPolicy extends ActionInitiateParamsBase { type }

DropletActionRestore extends ActionInitiateParamsBase { type }

DropletActionResize extends ActionInitiateParamsBase { type }

DropletActionRebuild extends ActionInitiateParamsBase { type }

DropletActionRename extends ActionInitiateParamsBase { type }

DropletActionChangeKernel extends ActionInitiateParamsBase { type }

DropletActionSnapshot extends ActionInitiateParamsBase { type }

ReturnsExpand Collapse

ActionInitiateResponse { action }

action?: Action { id, completed_at, region, 6 more }

id?: number

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

completed_at?: string | null

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

formatdate-time

region?: Region { available, features, name, 2 more }

available: boolean

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

features: Array<string>

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

name: string

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

sizes: Array<string>

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: string

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

region_slug?: string | null

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

resource_id?: number | null

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

resource_type?: string

The type of resource that the action is associated with.

started_at?: string

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

formatdate-time

status?: "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?: string

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

Initiate a Droplet Action

import Gradient from '@digitalocean/gradient';

const client = new Gradient();

const response = await client.gpuDroplets.actions.initiate(3164444, { type: 'reboot' });

console.log(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"
  }
}