Give Feedback

pydo.droplet_actions.post()

Generated on 9 Jun 2026 from pydo version v0.36.0

Copy page as Markdown View page as Markdown

Usage

client.droplet_actions.post(
    droplet_id=3164444,
    body={
        "type": "reboot",
        "backup_policy": {...},
        "image": "ubuntu-20-04-x64",
        ...,
    },
)

Returns JSONRaises HttpResponseError

Description

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 one of the supported action types:

Action	Details	Required Permissions
`enable_backups`	Enables backups for a Droplet	`droplet:update`
`disable_backups`	Disables backups for a Droplet	`droplet:update`
`change_backup_policy`	Update the backup policy for a Droplet	`droplet:update`
`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.	`droplet:update`
`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.	`droplet:update`
`shutdown`	Shuts down 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.	`droplet:update`
`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.	`droplet:update`
`power_on`	Powers on a Droplet.	`droplet:update`
`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:update` `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:update` `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:update` `droplet:create`
`rebuild`	Rebuilds a Droplet from a new base image. Set the `image` attribute to an image ID or slug.	`droplet:update` `droplet:admin`
`rename`	Renames a Droplet.	`droplet:update`
`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.	`droplet:update`
`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.	`droplet:update`
`snapshot`	Takes a snapshot of a Droplet.	`droplet:update` `image:create`

Parameters

droplet_id integer required

A unique identifier for a Droplet instance.

Min: 1

type string required

The type of action to initiate for the Droplet.

One of: enable_backups, disable_backups, reboot, power_cycle, shutdown, power_off, power_on, restore, password_reset, resize, rebuild, rename, change_kernel, enable_ipv6, snapshot

backup_policy object optional

Show child properties

plan string optional

The backup plan used for the Droplet. The plan can be either daily or weekly.

One of: daily, weekly

weekday string optional

The day of the week on which the backup will occur.

One of: SUN, MON, TUE, WED, THU, FRI, SAT

hour integer optional

The hour of the day that the backup window will start.

One of: 0, 4, 8, 12, 16, 20

window_length_hours integer optional read-only

Example: 4

The length of the backup window starting from hour.

retention_period_days integer optional read-only

Example: 7

The number of days the backup will be retained.

image object optional

Example: ubuntu-20-04-x64

The image ID of a public or private image or the slug identifier for a public image. The Droplet will be rebuilt using this image as its base.

disk boolean optional

Example: True

When true, the Droplet's disk will be resized in addition to its RAM and CPU. This is a permanent change and cannot be reversed as a Droplet's disk size cannot be decreased.

size string optional

Example: s-2vcpu-2gb

The slug identifier for the size to which you wish to resize the Droplet.

name string optional

Example: Nifty New Snapshot

The name to give the new snapshot of the Droplet.

kernel integer optional

Example: 12389723

A unique number used to identify and reference a specific kernel.

Request Sample

Show Request Sample

import os
from pydo import Client

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

# enable back ups example
req = {
  "type": "enable_backups"
}

resp = client.droplet_actions.post(droplet_id=346652, body=req)

Response Example

Show Response Example

{
  "action": {
    "id": 36804636,
    "status": "completed",
    "type": "create",
    "started_at": "2020-11-14T16:29:21Z",
    "completed_at": "2020-11-14T16:30:06Z",
    "resource_id": 3164444,
    "resource_type": "droplet",
    "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"
      ]
    },
    "region_slug": "nyc3"
  }
}

More Information

See /v2/droplets/{droplet_id}/actions in the API reference for additional detail on responses, headers, parameters, and more.