Image actions are commands that can be given to a DigitalOcean image. In general, these requests are made on the actions endpoint of a specific image. An image action object is returned. These objects hold the current status of the requested action.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/digital-ocean-image-actions-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: DigitalOcean Image Actions 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: Image Actions
description: 'Image actions are commands that can be given to a DigitalOcean image. In
general, these requests are made on the actions endpoint of a specific
image.
An image action object is returned. These objects hold the current status
of the requested action.'
paths:
/v2/images/{image_id}/actions:
get:
operationId: imageActions_list
summary: List All Actions for an Image
description: To retrieve all actions that have been executed on an image, send a GET request to `/v2/images/$IMAGE_ID/actions`.
tags:
- Image Actions
parameters:
- $ref: '#/components/parameters/image_id'
responses:
'200':
$ref: '#/components/responses/get_image_actions_response'
'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/images/7555620/actions?page=1&per_page=1\""
- 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 \n}"
- lang: Python
source: 'import os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.image_actions.list(image_id=7938269)'
security:
- bearer_auth:
- image:read
post:
operationId: imageActions_post
summary: Initiate an Image Action
description: 'The following actions are available on an Image.
## Convert an Image to a Snapshot
To convert an image, for example, a backup to a snapshot, send a POST request
to `/v2/images/$IMAGE_ID/actions`. Set the `type` attribute to `convert`.
## Transfer an Image
To transfer an image to another region, send a POST request to
`/v2/images/$IMAGE_ID/actions`. Set the `type` attribute to `transfer` and set
`region` attribute to the slug identifier of the region you wish to transfer
to.'
tags:
- Image Actions
parameters:
- $ref: '#/components/parameters/image_id'
requestBody:
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/image_action_base'
- $ref: '#/components/schemas/image_action_transfer'
discriminator:
propertyName: type
mapping:
convert: '#/components/schemas/image_action_base'
transfer: '#/components/schemas/image_action_transfer'
responses:
'201':
$ref: '#/components/responses/post_image_action_response'
'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: "# Transfer an Existing Image\ncurl -X POST \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n -d '{\"type\":\"transfer\",\"region\":\"nyc2\"}' \\\n \"https://api.digitalocean.com/v2/images/7938269/actions\"\n\n# Convert an Image into a Snapshot\ncurl -X POST \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $DIGITALOCEAN_TOKEN\" \\\n -d '{\"type\":\"convert\"}' \\\n \"https://api.digitalocean.com/v2/images/7938291/actions\""
- 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 // Transfer an existing image\n transferRequest := &godo.ActionRequest{\n \"type\": \"transfer\",\n \"region\": \"nyc2\",\n }\n # Transfer an Image\n transfer, _, err := client.ImageActions.Transfer(ctx, 7938269, transferRequest)\n\n # Convert an Image to a Snapshot\n # client.image_actions.convert(image_id: 7938269)\n\n}"
- lang: Ruby
source: 'require ''droplet_kit''
token = ENV[''DIGITALOCEAN_TOKEN'']
client = DropletKit::Client.new(access_token: token)
# Transfer an Image
client.image_actions.transfer(image_id: 7938269, region: ''nyc2'')
# Convert an Image to a Snapshot
# client.image_actions.convert(image_id: 7938269)'
- lang: Python
source: "import os\nfrom pydo import Client\n\nclient = Client(token=os.environ.get(\"DIGITALOCEAN_TOKEN\"))\n\nreq = {\n \"type\": \"convert\"\n}\nresp = client.image_actions.post(image_id=342341, body=req)"
security:
- bearer_auth:
- image:create
/v2/images/{image_id}/actions/{action_id}:
get:
operationId: imageActions_get
summary: Retrieve an Existing Action
description: To retrieve the status of an image action, send a GET request to `/v2/images/$IMAGE_ID/actions/$IMAGE_ACTION_ID`.
tags:
- Image Actions
parameters:
- $ref: '#/components/parameters/image_id'
- $ref: '#/components/parameters/action_id'
responses:
'200':
$ref: '#/components/responses/get_image_action_response'
'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/images/7938269/actions/36805527\""
- 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 action, _, err := client.ImageActions.Get(ctx, 7938269, 36805527)\n}"
- lang: Ruby
source: 'require ''droplet_kit''
token = ENV[''DIGITALOCEAN_TOKEN'']
client = DropletKit::Client.new(access_token: token)
client.image_actions.find(image_id: 7938269, id: 36805527)'
- lang: Python
source: 'import os
from pydo import Client
client = Client(token=os.environ.get("DIGITALOCEAN_TOKEN"))
resp = client.image_actions.get(action_id=36805527, image_id=7938269)'
security:
- bearer_auth:
- image:read
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
region:
type: object
properties:
name:
type: string
description: The display name of the region. This will be a full name that is used in the control panel and other interfaces.
example: New York 3
slug:
type: string
description: A human-readable string that is used as a unique identifier for each region.
example: nyc3
features:
items:
type: string
description: This attribute is set to an array which contains features available in this region
example:
- private_networking
- backups
- ipv6
- metadata
- install_agent
- storage
- image_transfer
available:
type: boolean
description: This is a boolean value that represents whether new Droplets can be created in this region.
example: true
sizes:
items:
type: string
description: This attribute is set to an array which contains the identifying slugs for the sizes available in this region.
example:
- 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
required:
- available
- features
- name
- sizes
- slug
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'
image_action_transfer:
allOf:
- $ref: '#/components/schemas/image_action_base'
- type: object
properties:
region:
$ref: '#/components/schemas/region_slug'
required:
- type
- region
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
image_action_base:
type: object
properties:
type:
type: string
description: The action to be taken on the image. Can be either `convert` or `transfer`.
enum:
- convert
- transfer
example: convert
required:
- type
action:
type: object
properties:
id:
type: integer
description: A unique numeric ID that can be used to identify and reference an action.
example: 36804636
status:
type: string
description: The current status of the action. This can be "in-progress", "completed", or "errored".
enum:
- in-progress
- completed
- errored
example: completed
default: in-progress
type:
type: string
description: 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.
example: create
started_at:
type: string
format: date-time
description: A time value given in ISO8601 combined date and time format that represents when the action was initiated.
example: '2020-11-14T16:29:21Z'
completed_at:
type:
- string
- 'null'
format: date-time
description: A time value given in ISO8601 combined date and time format that represents when the action was completed.
example: '2020-11-14T16:30:06Z'
resource_id:
type:
- integer
- 'null'
description: A unique identifier for the resource that the action is associated with.
example: 3164444
resource_type:
type: string
description: The type of resource that the action is associated with.
example: droplet
region:
$ref: '#/components/schemas/region'
region_slug:
type:
- string
- 'null'
description: A human-readable string that is used as a unique identifier for each region.
example: nyc3
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
region_slug:
type: string
description: The slug identifier for the region where the resource will initially be available.
enum:
- ams1
- ams2
- ams3
- blr1
- fra1
- lon1
- nyc1
- nyc2
- nyc3
- sfo1
- sfo2
- sfo3
- sgp1
- tor1
- syd1
example: nyc3
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'
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:
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
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.
get_image_action_response:
description: The response will be an object with a key called `action`. The value of this will be an object that contains the standard image action attributes.
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/action'
example:
action:
id: 36805527
status: in-progress
type: transfer
started_at: '2014-11-14T16:42:45Z'
completed_at: null
resource_id: 7938269
resource_type: image
region:
name: New York 3
slug: nyc3
sizes:
- s-1vcpu-3gb
- m-1vcpu-8gb
- s-3vcpu-1gb
- s-1vcpu-2gb
- s-2vcpu-2gb
- s-2vcpu-4gb
- s-4vcpu-8gb
- s-6vcpu-16gb
- s-8vcpu-32gb
- s-12vcpu-48gb
- s-16vcpu-64gb
- s-20vcpu-96gb
- s-1vcpu-1gb
- c-1vcpu-2gb
- s-24vcpu-128gb
features:
- private_networking
- backups
- ipv6
- metadata
- server_id
- install_agent
- storage
- image_transfer
available: true
region_slug: nyc3
get_image_actions_response:
description: The results will be returned as a JSON object with an `actions` key. This will be set to an array filled with action objects containing the standard action attributes.
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:
actions:
type: array
items:
$ref: '#/components/schemas/action'
- $ref: '#/components/schemas/pagination'
- $ref: '#/components/schemas/meta'
example:
actions:
- id: 29410565
status: completed
type: transfer
started_at: '2014-07-25T15:04:21Z'
completed_at: '2014-07-25T15:10:20Z'
resource_id: 7555620
resource_type: image
region:
name: New York 2
slug: nyc2
sizes:
- s-1vcpu-3gb
- m-1vcpu-8gb
- s-3vcpu-1gb
- s-1vcpu-2gb
- s-2vcpu-2gb
- s-2vcpu-4gb
- s-4vcpu-8gb
- s-6vcpu-16gb
- s-8vcpu-32gb
- s-12vcpu-48gb
- s-16vcpu-64gb
- s-20vcpu-96gb
- s-1vcpu-1gb
- c-1vcpu-2gb
- s-24vcpu-128gb
features:
- private_networking
- backups
- ipv6
- metadata
- server_id
- install_agent
- storage
- image_transfer
available: true
region_slug: nyc2
links:
pages:
last: https://api.digitalocean.com/v2/images/7555620/actions?page=5&per_page=1
next: https://api.digitalocean.com/v2/images/7555620/actions?page=2&per_page=1
meta:
total: 5
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.
post_image_action_response:
description: The response will be a JSON object with a key called `action`. The value of this will be an object containing the standard image action attributes.
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/action'
example:
action:
id: 36805527
status: in-progress
type: transfer
started_at: '2014-11-14T16:42:45Z'
completed_at: null
resource_id: 7938269
resource_type: image
region:
name: New York 3
slug: nyc3
sizes:
- s-1vcpu-3gb
- m-1vcpu-8gb
- s-3vcpu-1gb
- s-1vcpu-2gb
- s-2vcpu-2gb
- s-2vcpu-4gb
- s-4vcpu-8gb
- s-6vcpu-16gb
- s-8vcpu-32gb
- s-12vcpu-48gb
- s-16vcpu-64gb
- s-20vcpu-96gb
- s-1vcpu-1gb
- c-1vcpu-2gb
- s-24vcpu-128gb
features:
- private_networking
- backups
- ipv6
- metadata
- server_id
- install_agent
- storage
- image_transfer
available: true
region_slug: nyc3
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
parameters:
image_id:
in: path
name: image_id
description: A unique number that can be used to identify and reference a specific image.
required: true
schema:
type: integer
example: 62137902
action_id:
in: path
name: action_id
description: A unique numeric ID that can be used to identify and reference an action.
required: true
schema:
type: integer
minimum: 1
example: 36804636
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"
```
'