DigitalOcean API (unofficial showcase)
POST/v2/images/{image_id}/actions

Trigger an image action

Triggers an action on an image to convert it to a snapshot or transfer it to another region. Set type to convert or transfer, and provide region when transferring. The 201 response includes an action object you can use to track the action's status.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 1 body field
image_idintegerrequired
The unique numeric identifier of the image to act on.

Image action details. Set type to convert or transfer; include region for a transfer.

typestringrequired
The action to be taken on the image. Can be either `convert` or `transfer`.
Allowed:converttransfer

6 status codes
201Returns an action object with its identifier, status, type, start and completion times, associated resource, and region details.
idintegeroptional
A unique numeric ID that can be used to identify and reference an action.
statusstringoptional
The current status of the action. This can be "in-progress", "completed", or "errored".
Allowed:in-progresscompletederroredDefault:in-progress
typestringoptional
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.
started_atstringoptional
A time value given in ISO8601 combined date and time format that represents when the action was initiated.
completed_atstringoptional
A time value given in ISO8601 combined date and time format that represents when the action was completed.
resource_idintegeroptional
A unique identifier for the resource that the action is associated with.
resource_typestringoptional
The type of resource that the action is associated with.
regionobjectoptional
region_slugstringoptional
A human-readable string that is used as a unique identifier for each region.
401Returned when authentication fails because the credentials are invalid.
idstringrequired
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."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
404Returned when the image resource is not found.
idstringrequired
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."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429Returned when the API rate limit has been exceeded.
idstringrequired
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."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500Returned when a server error occurs.
idstringrequired
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."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultReturned when an unexpected error occurs.
idstringrequired
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."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 401 is returned when authentication fails, a 404 when the image is not found, a 429 when the API rate limit is exceeded, and a 500 when a server error occurs. The image_id path parameter must identify an existing image; type must be convert or transfer, and region must be provided for a transfer.