pydo.droplet_actions.post()

Generated on 25 November 2024 from pydo version v0.6.0

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

Action Details
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.
password_reset Resets the root password for a Droplet. A new password will be provided via email. It must be changed after first use.
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.
rebuild Rebuilds a Droplet from a new base image. Set the image attribute to an image ID or slug.
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.

Parameters

Name Type Required Description Default Value
droplet_id integer True A unique identifier for a Droplet instance.
body JSON or IO[bytes] False The type attribute set in the request body will specify the action that
will be taken on the Droplet. Some actions will require additional
attributes to be set as well.

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)

Responses

See the API spec for this endpoint to view additional detail on responses, headers, parameters, and more.

The response will be a JSON object with a key called action.

Click to expand an example response. 
{
  "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"
  }
}

Unauthorized

Click to expand an example response. 
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}

The resource was not found.

Click to expand an example response. 
{
  "id": "not_found",
  "message": "The resource you requested could not be found."
}

API Rate limit exceeded

Click to expand an example response. 
{
  "id": "too_many_requests",
  "message": "API Rate limit exceeded."
}

Server error.

Click to expand an example response. 
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}

Unexpected error

Click to expand an example response. 
{
  "id": "example_error",
  "message": "some error message"
}
Control Panel Blog Pricing Careers Terms Privacy Status API Docs Tutorials Support