MicroVMs [Public Preview]

Generated on 13 Oct 2026

Copy page as Markdown View page as Markdown

DigitalOcean MicroVMs are lightweight virtual machines that run a linux/amd64 container image in an isolated kernel. A MicroVM pauses automatically when it is idle and resumes on the next HTTP request, command, or console session, with its memory, files, and processes intact. By sending requests to the /v2/microvms endpoints, you can create, list, pause, resume, and delete MicroVMs, run commands and open a console in them, and create checkpoints to start new MicroVMs from a saved state.

Each MicroVM serves its HTTP port at https://{microvm_id}.{region}.microvm.ondigitalocean.com. Requests to that endpoint require a token with the microvm:access scope.

Base URL https://api.digitalocean.com

Endpoints

GET List all MicroVMs POST Create a MicroVM GET List MicroVM options GET List checkpoints GET Retrieve a checkpoint DELETE Delete a checkpoint GET Retrieve a MicroVM DELETE Delete a MicroVM POST Pause a MicroVM POST Resume a MicroVM POST Run a command in a MicroVM GET Open a console in a MicroVM POST Create a checkpoint of a MicroVM

GET List all MicroVMs

/v2/microvms
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: microvm:read

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 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
  • 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"

To list all of the MicroVMs on your team, send a GET request to /v2/microvms.

The region, name, and tag_name filters combine with AND.

Query Parameters

page integer >= 1 optional
Example: 1

Which 'page' of paginated results to return.

Default: 1
per_page integer 1 – 200 optional
Example: 25

Number of items returned per page.

Default: 25
region string optional
Example: mkc1

Only return MicroVMs in this region.

name string optional
Example: example-microvm

Only return the MicroVM with this exact name.

tag_name string optional
Example: example

Only return MicroVMs with this tag. A tag that matches no MicroVMs returns an empty list.

Request: /v2/microvms
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/microvms?region=mkc1&tag_name=example"

Responses

200

The response will be a JSON object with a key called microvms. The value will be an array of MicroVM objects.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
microvms array of object optional
Show child properties
auto_pause object optional

Automatic pause settings. A MicroVM always pauses after it is idle for idle_timeout. Sending enabled set to false is rejected.

Show child properties
enabled boolean optional
Example: true

Whether auto-pause is on. Always true.

idle_timeout string optional
Example: 5m0s

How long the MicroVM is idle before it pauses, as a duration such as 30s, 5m, or 1h. Defaults to 5m. The maximum is 4h. Responses show the duration in the form 5m0s.

auto_resume boolean optional
Example: true

Whether an HTTP request, command, or console session resumes the MicroVM when it is paused.

created_at string (date-time) optional read-only
Example: 2026-09-29T21:38:29Z

When the MicroVM was created, in ISO 8601 format.

failure_reason string optional read-only
Example: workload container exited (code 0): exited with code 0

Why the MicroVM failed. Present only when state is failed.

http_protocol string, one of: http, http2 optional Nullable
Example: http

The protocol the MicroVM's HTTP port serves. null if the protocol was not set when the MicroVM was created.

id string (uuid) optional read-only
Example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a

The unique ID of the MicroVM.

name string optional
Example: example-microvm

The name of the MicroVM. Must be unique in the region and contain 1 to 63 lowercase letters, digits, and hyphens.

networking string, one of: public, vpc optional
Example: public

public sends outbound traffic through a shared NAT gateway. vpc places the MicroVM in the VPC network set by vpc_uuid.

ports array of integer optional
Example: [80]

The guest ports declared on the MicroVM, including the HTTP port. During the public preview, only the HTTP port is reachable through the MicroVM's endpoint.

region string optional
Example: mkc1

The slug of the region the MicroVM is in.

size object optional

The MicroVM's size. cpu and memory must be one of the pairs 1/2048, 2/4096, 8/16384, or 16/32768. The size sets the disk, which is returned in responses.

Show child properties
cpu integer required
Example: 1

The number of vCPUs.

disk integer optional read-only
Example: 50

The size of the disk, in GB. Set by the size.

memory integer required
Example: 2048

The amount of memory, in MiB.

source object optional

What the MicroVM runs. Set exactly one of oci_ref or checkpoint_id.

Show child properties
checkpoint_id string (uuid) optional
Example: 01a0ed98-0a74-75dd-a625-e4856adbc298

The ID of a checkpoint to create the MicroVM from. The new MicroVM inherits the checkpoint's region, size, container image, and environment variables.

oci_ref string optional
Example: docker.io/library/nginx:latest

A reference to a linux/amd64 container image in the form registry/repository:tag. The image can be public, such as an image on Docker Hub, or private in your team's DigitalOcean Container Registry.

state string (enum) optional read-only
Example: running

The MicroVM's current state.

tags array of string optional
Example: ["example"]

The tags applied to the MicroVM.

urls array of object optional read-only

The MicroVM's HTTPS endpoints. The entry with default set to true is the endpoint for the HTTP port.

Show child properties
default boolean optional
Example: true

Whether this is the endpoint for the MicroVM's HTTP port.

hostname string optional
Example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a.mkc1.microvm.ondigitalocean.com

The endpoint's hostname. Empty until provisioning finishes. Requests to the endpoint must include a DigitalOcean API token with the microvm:access scope in the Authorization header.

port integer optional
Example: 80

The guest port the endpoint serves.

status string, one of: PENDING, ACTIVE optional
Example: ACTIVE

PENDING until provisioning finishes, then ACTIVE.

vpc_uuid string (uuid) optional
Example: 5a4981aa-9653-4bd1-bef5-d6bff52042e4

The ID of a VPC network in the same region that belongs to your team. Present only when networking is vpc.

links object optional
Show child properties
pages anyOf optional
One of:
Forward Links
last string optional
Example: https://api.digitalocean.com/v2/images?page=2

URI of the last page of the results.

next string optional
Example: https://api.digitalocean.com/v2/images?page=2

URI of the next page of the results.

Backward Links
first string optional
Example: https://api.digitalocean.com/v2/images?page=1

URI of the first page of the results.

prev string optional
Example: https://api.digitalocean.com/v2/images?page=1

URI of the previous page of the results.

meta object required
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "links": {
    "pages": {
      "last": "/v2/microvms?page=4\u0026per_page=1",
      "next": "/v2/microvms?page=2\u0026per_page=1"
    }
  },
  "meta": {
    "page": 1,
    "per_page": 1,
    "total": 4
  },
  "microvms": [
    {
      "auto_pause": {
        "enabled": true,
        "idle_timeout": "5m0s"
      },
      "auto_resume": true,
      "created_at": "2026-09-29T21:38:29Z",
      "http_protocol": "http",
      "id": "01a0ef1a-d873-793d-ae6a-5dd6239be62a",
      "name": "example-microvm",
      "networking": "public",
      "ports": [
        80
      ],
      "region": "mkc1",
      "size": {
        "cpu": 1,
        "disk": 50,
        "memory": 2048
      },
      "source": {
        "oci_ref": "docker.io/library/nginx:latest"
      },
      "state": "paused",
      "tags": [
        "example"
      ],
      "urls": [
        {
          "default": true,
          "hostname": "01a0ef1a-d873-793d-ae6a-5dd6239be62a.mkc1.microvm.ondigitalocean.com",
          "port": 80,
          "status": "ACTIVE"
        }
      ]
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Create a MicroVM

/v2/microvms
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: microvm:create

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 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
  • 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"

To create a MicroVM, send a POST request to /v2/microvms.

name and source are required. Set source.oci_ref to create the MicroVM from a linux/amd64 container image, or source.checkpoint_id to create it from a checkpoint. With oci_ref, region and size are also required.

A MicroVM created from an image is returned with state set to creating. Poll GET /v2/microvms/{microvm_id} until state is running. A MicroVM created from a checkpoint is usually returned already running.

All settings are fixed at creation. There is no update endpoint.

Request Body: application/json

auto_pause object optional

Automatic pause settings. A MicroVM always pauses after it is idle for idle_timeout. Sending enabled set to false is rejected.

Show child properties
enabled boolean optional
Example: true

Whether auto-pause is on. Always true.

idle_timeout string optional
Example: 5m0s

How long the MicroVM is idle before it pauses, as a duration such as 30s, 5m, or 1h. Defaults to 5m. The maximum is 4h. Responses show the duration in the form 5m0s.

auto_resume boolean optional
Example: true

Whether an HTTP request, command, or console session resumes the MicroVM when it is paused. Set to false to require a manual resume.

environment object optional
Example: {"APP_ENV":"production"}

Environment variables passed into the MicroVM at boot, as key and value pairs. Not returned in responses.

http_port integer optional
Example: 80

The guest port the workload serves HTTP on. Defaults to 8080. Not returned in responses. When creating from a checkpoint without ports, must be one of the checkpoint's ports.

http_protocol string, one of: http, http2 optional
Example: http

The protocol the HTTP port serves.

name string required
Example: example-microvm

The name of the MicroVM. Must be unique in the region and contain 1 to 63 lowercase letters, digits, and hyphens.

networking string, one of: public, vpc optional
Example: public

public sends outbound traffic through a shared NAT gateway. vpc places the MicroVM in the VPC network set by vpc_uuid.

ports array of integer optional
Example: [80]

The guest ports to declare, up to five. Must include http_port. Defaults to only the HTTP port. During the public preview, only the HTTP port is reachable through the MicroVM's endpoint.

region string optional
Example: mkc1

The slug of the region to create the MicroVM in. Required with source.oci_ref.

size object optional

The MicroVM's size. cpu and memory must be one of the pairs 1/2048, 2/4096, 8/16384, or 16/32768. The size sets the disk, which is returned in responses.

Show child properties
cpu integer required
Example: 1

The number of vCPUs.

disk integer optional read-only
Example: 50

The size of the disk, in GB. Set by the size.

memory integer required
Example: 2048

The amount of memory, in MiB.

source object required

What the MicroVM runs. Set exactly one of oci_ref or checkpoint_id.

Show child properties
checkpoint_id string (uuid) optional
Example: 01a0ed98-0a74-75dd-a625-e4856adbc298

The ID of a checkpoint to create the MicroVM from. The new MicroVM inherits the checkpoint's region, size, container image, and environment variables.

oci_ref string optional
Example: docker.io/library/nginx:latest

A reference to a linux/amd64 container image in the form registry/repository:tag. The image can be public, such as an image on Docker Hub, or private in your team's DigitalOcean Container Registry.

tags array of string optional
Example: ["example"]

Tags to apply to the MicroVM.

vpc_uuid string (uuid) optional
Example: 5a4981aa-9653-4bd1-bef5-d6bff52042e4

The ID of a VPC network in the same region that belongs to your team. Required when networking is vpc.

Request: /v2/microvms
Content type application/json
Example 
{
  "name": "example-from-checkpoint",
  "source": {
    "checkpoint_id": "01a0ed98-0a74-75dd-a625-e4856adbc298"
  }
}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name": "example-microvm", "region": "mkc1", "size": {"cpu": 1, "memory": 2048}, "source": {"oci_ref": "docker.io/library/nginx:latest"}, "http_port": 80, "http_protocol": "http", "auto_pause": {"idle_timeout": "5m"}, "tags": ["example"]}' \
  "https://api.digitalocean.com/v2/microvms"

Responses

201

The response will be a JSON object with a key called microvm. A MicroVM created from a container image has state set to creating and an empty endpoint hostname until provisioning finishes. A MicroVM created from a checkpoint is usually already running.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
microvm object optional

A MicroVM. All fields are set at creation. There is no update endpoint.

Show child properties
auto_pause object optional

Automatic pause settings. A MicroVM always pauses after it is idle for idle_timeout. Sending enabled set to false is rejected.

Show child properties
enabled boolean optional
Example: true

Whether auto-pause is on. Always true.

idle_timeout string optional
Example: 5m0s

How long the MicroVM is idle before it pauses, as a duration such as 30s, 5m, or 1h. Defaults to 5m. The maximum is 4h. Responses show the duration in the form 5m0s.

auto_resume boolean optional
Example: true

Whether an HTTP request, command, or console session resumes the MicroVM when it is paused.

created_at string (date-time) optional read-only
Example: 2026-09-29T21:38:29Z

When the MicroVM was created, in ISO 8601 format.

failure_reason string optional read-only
Example: workload container exited (code 0): exited with code 0

Why the MicroVM failed. Present only when state is failed.

http_protocol string, one of: http, http2 optional Nullable
Example: http

The protocol the MicroVM's HTTP port serves. null if the protocol was not set when the MicroVM was created.

id string (uuid) optional read-only
Example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a

The unique ID of the MicroVM.

name string optional
Example: example-microvm

The name of the MicroVM. Must be unique in the region and contain 1 to 63 lowercase letters, digits, and hyphens.

networking string, one of: public, vpc optional
Example: public

public sends outbound traffic through a shared NAT gateway. vpc places the MicroVM in the VPC network set by vpc_uuid.

ports array of integer optional
Example: [80]

The guest ports declared on the MicroVM, including the HTTP port. During the public preview, only the HTTP port is reachable through the MicroVM's endpoint.

region string optional
Example: mkc1

The slug of the region the MicroVM is in.

size object optional

The MicroVM's size. cpu and memory must be one of the pairs 1/2048, 2/4096, 8/16384, or 16/32768. The size sets the disk, which is returned in responses.

Show child properties
cpu integer required
Example: 1

The number of vCPUs.

disk integer optional read-only
Example: 50

The size of the disk, in GB. Set by the size.

memory integer required
Example: 2048

The amount of memory, in MiB.

source object optional

What the MicroVM runs. Set exactly one of oci_ref or checkpoint_id.

Show child properties
checkpoint_id string (uuid) optional
Example: 01a0ed98-0a74-75dd-a625-e4856adbc298

The ID of a checkpoint to create the MicroVM from. The new MicroVM inherits the checkpoint's region, size, container image, and environment variables.

oci_ref string optional
Example: docker.io/library/nginx:latest

A reference to a linux/amd64 container image in the form registry/repository:tag. The image can be public, such as an image on Docker Hub, or private in your team's DigitalOcean Container Registry.

state string (enum) optional read-only
Example: running

The MicroVM's current state.

tags array of string optional
Example: ["example"]

The tags applied to the MicroVM.

urls array of object optional read-only

The MicroVM's HTTPS endpoints. The entry with default set to true is the endpoint for the HTTP port.

Show child properties
default boolean optional
Example: true

Whether this is the endpoint for the MicroVM's HTTP port.

hostname string optional
Example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a.mkc1.microvm.ondigitalocean.com

The endpoint's hostname. Empty until provisioning finishes. Requests to the endpoint must include a DigitalOcean API token with the microvm:access scope in the Authorization header.

port integer optional
Example: 80

The guest port the endpoint serves.

status string, one of: PENDING, ACTIVE optional
Example: ACTIVE

PENDING until provisioning finishes, then ACTIVE.

vpc_uuid string (uuid) optional
Example: 5a4981aa-9653-4bd1-bef5-d6bff52042e4

The ID of a VPC network in the same region that belongs to your team. Present only when networking is vpc.

400

The request was malformed, failed validation, or is not allowed in the resource's current state.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
code string required
Example: NOT_FOUND

A service-defined error code.

message string required
Example: MicroVM not found

A human-readable description of the error.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

403

The token does not have the required scope, or your team has reached a limit.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
code string required
Example: NOT_FOUND

A service-defined error code.

message string required
Example: MicroVM not found

A human-readable description of the error.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "microvm": {
    "auto_pause": {
      "enabled": true,
      "idle_timeout": "5m0s"
    },
    "auto_resume": true,
    "created_at": "2026-09-29T21:38:29Z",
    "http_protocol": "http",
    "id": "01a0ef1a-d873-793d-ae6a-5dd6239be62a",
    "name": "example-microvm",
    "networking": "public",
    "ports": [
      80
    ],
    "region": "mkc1",
    "size": {
      "cpu": 1,
      "disk": 50,
      "memory": 2048
    },
    "source": {
      "oci_ref": "docker.io/library/nginx:latest"
    },
    "state": "creating",
    "tags": [
      "example"
    ],
    "urls": [
      {
        "default": true,
        "hostname": "",
        "port": 80,
        "status": "PENDING"
      }
    ]
  }
}
Example 
{
  "code": "INVALID_AUTO_PAUSE",
  "message": "auto_pause.enabled cannot be false; omit it to keep the 5 minute default, or set idle_timeout up to the account maximum"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "code": "PERMISSION_DENIED",
  "message": "permission denied"
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List MicroVM options

/v2/microvms/options
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: microvm:read

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 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
  • 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"

To list the default region, sizes, prices, account limits, and features available to your team, send a GET request to /v2/microvms/options.

Request: /v2/microvms/options
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/microvms/options"

Responses

200

The response will be a JSON object with the default region, sizes, prices, account limits, and features available to your team.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
account_limits object optional

Your team's MicroVM limits.

Show child properties
max_disk_bytes integer (int64) optional
Example: 429496729600

The maximum disk per MicroVM, in bytes.

max_idle_timeout_seconds integer optional
Example: 14400

The maximum auto-pause idle timeout, in seconds.

max_memory_bytes integer (int64) optional
Example: 34359738368

The maximum memory per MicroVM, in bytes.

max_total_count integer optional
Example: 1000

The maximum number of MicroVMs, counting both running and paused MicroVMs.

default_region string optional
Example: mkc1

The slug of the region MicroVMs are created in by default.

features array of object optional

Features and whether they are enabled for your team.

Show child properties
enabled boolean optional
Example: true

Whether the feature is enabled.

name string optional
Example: exec_pty

The name of the feature.

resource_pricing object optional

Per-resource rates, in USD.

Show child properties
price_per_gib_bandwidth number optional
Example: 0.01

The price per GiB of outbound data transfer.

price_per_gib_memory_hour number optional
Example: 0.0085

The price per GiB of memory per hour of running time.

price_per_gib_storage_month number optional
Example: 0.05

The price per GiB-month of disk and checkpoint storage.

price_per_vcpu_hour number optional
Example: 0.022

The price per vCPU per hour of running time.

sizes array of object optional

The sizes available to your team.

Show child properties
available boolean optional
Example: true

Whether the size is available on your team's plan.

cpu integer optional
Example: 1

The number of vCPUs.

disk integer optional
Example: 50

The size of the disk, in GB.

memory integer optional
Example: 2048

The amount of memory, in MiB.

pricing object optional

The compute price of the size.

Show child properties
price_per_hour number optional
Example: 0.039

The price per hour of running time, in USD.

price_per_month number optional
Example: 28.47

The price for running continuously for a month (730 hours), in USD.

regions array of string optional
Example: ["mkc1"]

The slugs of the regions the size is available in.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "account_limits": {
    "max_disk_bytes": 429496729600,
    "max_idle_timeout_seconds": 14400,
    "max_memory_bytes": 34359738368,
    "max_total_count": 1000
  },
  "default_region": "mkc1",
  "features": [
    {
      "enabled": true,
      "name": "microvm"
    },
    {
      "enabled": true,
      "name": "exec_pty"
    }
  ],
  "resource_pricing": {
    "price_per_gib_bandwidth": 0.01,
    "price_per_gib_memory_hour": 0.0085,
    "price_per_gib_storage_month": 0.05,
    "price_per_vcpu_hour": 0.022
  },
  "sizes": [
    {
      "available": true,
      "cpu": 1,
      "disk": 50,
      "memory": 2048,
      "pricing": {
        "price_per_hour": 0.039,
        "price_per_month": 28.47
      },
      "regions": [
        "mkc1"
      ]
    },
    {
      "available": true,
      "cpu": 2,
      "disk": 80,
      "memory": 4096,
      "pricing": {
        "price_per_hour": 0.078,
        "price_per_month": 56.94
      },
      "regions": [
        "mkc1"
      ]
    },
    {
      "available": true,
      "cpu": 8,
      "disk": 320,
      "memory": 16384,
      "pricing": {
        "price_per_hour": 0.312,
        "price_per_month": 227.76
      },
      "regions": [
        "mkc1"
      ]
    },
    {
      "available": true,
      "cpu": 16,
      "disk": 400,
      "memory": 32768,
      "pricing": {
        "price_per_hour": 0.624,
        "price_per_month": 455.52
      },
      "regions": [
        "mkc1"
      ]
    }
  ]
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET List checkpoints

/v2/microvms/checkpoints
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: microvm:read

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 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
  • 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"

To list your team's checkpoints, newest first, send a GET request to /v2/microvms/checkpoints. To list one MicroVM's checkpoints, add the microvm_id query parameter.

Query Parameters

page integer >= 1 optional
Example: 1

Which 'page' of paginated results to return.

Default: 1
per_page integer 1 – 200 optional
Example: 25

Number of items returned per page.

Default: 25
microvm_id string (uuid) optional
Example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a

Only return checkpoints taken from this MicroVM.

Request: /v2/microvms/checkpoints
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/microvms/checkpoints?microvm_id=01a0ef1a-d873-793d-ae6a-5dd6239be62a"

Responses

200

The response will be a JSON object with a key called checkpoints. The value will be an array of checkpoint objects, newest first.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
checkpoints array of object optional
Show child properties
created_at string (date-time) optional read-only
Example: 2026-09-29T14:35:59Z

When the checkpoint was created, in ISO 8601 format.

disk_bytes integer (int64) optional read-only
Example: 1073741824

The stored size of the checkpoint's disk, in bytes.

id string (uuid) optional read-only
Example: 01a0ed98-0a74-75dd-a625-e4856adbc298

The unique ID of the checkpoint.

memory_bytes integer (int64) optional read-only
Example: 2147483648

The stored size of the checkpoint's memory, in bytes.

microvm_id string (uuid) optional read-only
Example: 01a0ed71-4efb-718f-9598-ca9cba942595

The ID of the MicroVM the checkpoint was taken from.

microvm_name string optional read-only
Example: example-microvm

The name of the MicroVM the checkpoint was taken from.

name string optional
Example: checkpoint-20260929-143559

The name of the checkpoint. If you do not set one, a name such as checkpoint-20260929-143559 is generated.

region string optional read-only
Example: mkc1

The slug of the checkpoint's region.

size object optional

The MicroVM's size. cpu and memory must be one of the pairs 1/2048, 2/4096, 8/16384, or 16/32768. The size sets the disk, which is returned in responses.

Show child properties
cpu integer required
Example: 1

The number of vCPUs.

disk integer optional read-only
Example: 50

The size of the disk, in GB. Set by the size.

memory integer required
Example: 2048

The amount of memory, in MiB.

status string, one of: CHECKPOINT_CREATING, CHECKPOINT_AVAILABLE, CHECKPOINT_FAILED, CHECKPOINT_DELETING, CHECKPOINT_DELETED optional read-only
Example: CHECKPOINT_AVAILABLE

The checkpoint's status. You can create MicroVMs from the checkpoint when it is CHECKPOINT_AVAILABLE.

links object optional
Show child properties
pages anyOf optional
One of:
Forward Links
last string optional
Example: https://api.digitalocean.com/v2/images?page=2

URI of the last page of the results.

next string optional
Example: https://api.digitalocean.com/v2/images?page=2

URI of the next page of the results.

Backward Links
first string optional
Example: https://api.digitalocean.com/v2/images?page=1

URI of the first page of the results.

prev string optional
Example: https://api.digitalocean.com/v2/images?page=1

URI of the previous page of the results.

meta object required
401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "checkpoints": [
    {
      "created_at": "2026-09-29T14:35:59Z",
      "disk_bytes": 1073741824,
      "id": "01a0ed98-0a74-75dd-a625-e4856adbc298",
      "memory_bytes": 2147483648,
      "microvm_id": "01a0ef1a-d873-793d-ae6a-5dd6239be62a",
      "microvm_name": "example-microvm",
      "name": "example-checkpoint",
      "region": "mkc1",
      "size": {
        "cpu": 1,
        "disk": 50,
        "memory": 2048
      },
      "status": "CHECKPOINT_AVAILABLE"
    }
  ],
  "links": {},
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve a checkpoint

/v2/microvms/checkpoints/{checkpoint_id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: microvm:read

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 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
  • 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"

To show information about a checkpoint, send a GET request to /v2/microvms/checkpoints/{checkpoint_id}.

Path Parameters

checkpoint_id string (uuid) required
Example: 01a0ed98-0a74-75dd-a625-e4856adbc298

The unique ID of the checkpoint.

Request: /v2/microvms/checkpoints/{checkpoint_id}
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/microvms/checkpoints/01a0ed98-0a74-75dd-a625-e4856adbc298"

Responses

200

The response will be a JSON object with a key called checkpoint. The value will be an object containing the standard attributes associated with a checkpoint.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
checkpoint object optional

A checkpoint of a MicroVM's memory and disk. New MicroVMs created from a checkpoint start from that state.

Show child properties
created_at string (date-time) optional read-only
Example: 2026-09-29T14:35:59Z

When the checkpoint was created, in ISO 8601 format.

disk_bytes integer (int64) optional read-only
Example: 1073741824

The stored size of the checkpoint's disk, in bytes.

id string (uuid) optional read-only
Example: 01a0ed98-0a74-75dd-a625-e4856adbc298

The unique ID of the checkpoint.

memory_bytes integer (int64) optional read-only
Example: 2147483648

The stored size of the checkpoint's memory, in bytes.

microvm_id string (uuid) optional read-only
Example: 01a0ed71-4efb-718f-9598-ca9cba942595

The ID of the MicroVM the checkpoint was taken from.

microvm_name string optional read-only
Example: example-microvm

The name of the MicroVM the checkpoint was taken from.

name string optional
Example: checkpoint-20260929-143559

The name of the checkpoint. If you do not set one, a name such as checkpoint-20260929-143559 is generated.

region string optional read-only
Example: mkc1

The slug of the checkpoint's region.

size object optional

The MicroVM's size. cpu and memory must be one of the pairs 1/2048, 2/4096, 8/16384, or 16/32768. The size sets the disk, which is returned in responses.

Show child properties
cpu integer required
Example: 1

The number of vCPUs.

disk integer optional read-only
Example: 50

The size of the disk, in GB. Set by the size.

memory integer required
Example: 2048

The amount of memory, in MiB.

status string, one of: CHECKPOINT_CREATING, CHECKPOINT_AVAILABLE, CHECKPOINT_FAILED, CHECKPOINT_DELETING, CHECKPOINT_DELETED optional read-only
Example: CHECKPOINT_AVAILABLE

The checkpoint's status. You can create MicroVMs from the checkpoint when it is CHECKPOINT_AVAILABLE.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The MicroVM or checkpoint does not exist, or it belongs to another team.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
code string required
Example: NOT_FOUND

A service-defined error code.

message string required
Example: MicroVM not found

A human-readable description of the error.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "checkpoint": {
    "created_at": "2026-09-29T14:35:59Z",
    "disk_bytes": 1073741824,
    "id": "01a0ed98-0a74-75dd-a625-e4856adbc298",
    "memory_bytes": 2147483648,
    "microvm_id": "01a0ef1a-d873-793d-ae6a-5dd6239be62a",
    "microvm_name": "example-microvm",
    "name": "example-checkpoint",
    "region": "mkc1",
    "size": {
      "cpu": 1,
      "disk": 50,
      "memory": 2048
    },
    "status": "CHECKPOINT_AVAILABLE"
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "code": "NOT_FOUND",
  "message": "MicroVM not found"
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete a checkpoint

/v2/microvms/checkpoints/{checkpoint_id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: microvm:delete

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 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
  • 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"

To delete a checkpoint, send a DELETE request to /v2/microvms/checkpoints/{checkpoint_id}. You can no longer create MicroVMs from a deleted checkpoint.

The request returns HTTP 400 while the checkpoint is still being captured. A successful request returns a 204 No Content status code.

Path Parameters

checkpoint_id string (uuid) required
Example: 01a0ed98-0a74-75dd-a625-e4856adbc298

The unique ID of the checkpoint.

Request: /v2/microvms/checkpoints/{checkpoint_id}
curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/microvms/checkpoints/01a0ed98-0a74-75dd-a625-e4856adbc298"

Responses

204

The action was successful and the response body is empty.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

400

The request was malformed, failed validation, or is not allowed in the resource's current state.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
code string required
Example: NOT_FOUND

A service-defined error code.

message string required
Example: MicroVM not found

A human-readable description of the error.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The MicroVM or checkpoint does not exist, or it belongs to another team.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
code string required
Example: NOT_FOUND

A service-defined error code.

message string required
Example: MicroVM not found

A human-readable description of the error.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
Example 
{
  "code": "INVALID_AUTO_PAUSE",
  "message": "auto_pause.enabled cannot be false; omit it to keep the 5 minute default, or set idle_timeout up to the account maximum"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "code": "NOT_FOUND",
  "message": "MicroVM not found"
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Retrieve a MicroVM

/v2/microvms/{microvm_id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: microvm:read

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 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
  • 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"

To show information about a MicroVM, send a GET request to /v2/microvms/{microvm_id}.

The endpoint is in the urls entry with default set to true. Its hostname is empty and its status is PENDING until provisioning finishes.

Path Parameters

microvm_id string (uuid) required
Example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a

The unique ID of the MicroVM.

Request: /v2/microvms/{microvm_id}
curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/microvms/01a0ef1a-d873-793d-ae6a-5dd6239be62a"

Responses

200

The response will be a JSON object with a key called microvm. The value will be an object containing the standard attributes associated with a MicroVM.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
microvm object optional

A MicroVM. All fields are set at creation. There is no update endpoint.

Show child properties
auto_pause object optional

Automatic pause settings. A MicroVM always pauses after it is idle for idle_timeout. Sending enabled set to false is rejected.

Show child properties
enabled boolean optional
Example: true

Whether auto-pause is on. Always true.

idle_timeout string optional
Example: 5m0s

How long the MicroVM is idle before it pauses, as a duration such as 30s, 5m, or 1h. Defaults to 5m. The maximum is 4h. Responses show the duration in the form 5m0s.

auto_resume boolean optional
Example: true

Whether an HTTP request, command, or console session resumes the MicroVM when it is paused.

created_at string (date-time) optional read-only
Example: 2026-09-29T21:38:29Z

When the MicroVM was created, in ISO 8601 format.

failure_reason string optional read-only
Example: workload container exited (code 0): exited with code 0

Why the MicroVM failed. Present only when state is failed.

http_protocol string, one of: http, http2 optional Nullable
Example: http

The protocol the MicroVM's HTTP port serves. null if the protocol was not set when the MicroVM was created.

id string (uuid) optional read-only
Example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a

The unique ID of the MicroVM.

name string optional
Example: example-microvm

The name of the MicroVM. Must be unique in the region and contain 1 to 63 lowercase letters, digits, and hyphens.

networking string, one of: public, vpc optional
Example: public

public sends outbound traffic through a shared NAT gateway. vpc places the MicroVM in the VPC network set by vpc_uuid.

ports array of integer optional
Example: [80]

The guest ports declared on the MicroVM, including the HTTP port. During the public preview, only the HTTP port is reachable through the MicroVM's endpoint.

region string optional
Example: mkc1

The slug of the region the MicroVM is in.

size object optional

The MicroVM's size. cpu and memory must be one of the pairs 1/2048, 2/4096, 8/16384, or 16/32768. The size sets the disk, which is returned in responses.

Show child properties
cpu integer required
Example: 1

The number of vCPUs.

disk integer optional read-only
Example: 50

The size of the disk, in GB. Set by the size.

memory integer required
Example: 2048

The amount of memory, in MiB.

source object optional

What the MicroVM runs. Set exactly one of oci_ref or checkpoint_id.

Show child properties
checkpoint_id string (uuid) optional
Example: 01a0ed98-0a74-75dd-a625-e4856adbc298

The ID of a checkpoint to create the MicroVM from. The new MicroVM inherits the checkpoint's region, size, container image, and environment variables.

oci_ref string optional
Example: docker.io/library/nginx:latest

A reference to a linux/amd64 container image in the form registry/repository:tag. The image can be public, such as an image on Docker Hub, or private in your team's DigitalOcean Container Registry.

state string (enum) optional read-only
Example: running

The MicroVM's current state.

tags array of string optional
Example: ["example"]

The tags applied to the MicroVM.

urls array of object optional read-only

The MicroVM's HTTPS endpoints. The entry with default set to true is the endpoint for the HTTP port.

Show child properties
default boolean optional
Example: true

Whether this is the endpoint for the MicroVM's HTTP port.

hostname string optional
Example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a.mkc1.microvm.ondigitalocean.com

The endpoint's hostname. Empty until provisioning finishes. Requests to the endpoint must include a DigitalOcean API token with the microvm:access scope in the Authorization header.

port integer optional
Example: 80

The guest port the endpoint serves.

status string, one of: PENDING, ACTIVE optional
Example: ACTIVE

PENDING until provisioning finishes, then ACTIVE.

vpc_uuid string (uuid) optional
Example: 5a4981aa-9653-4bd1-bef5-d6bff52042e4

The ID of a VPC network in the same region that belongs to your team. Present only when networking is vpc.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The MicroVM or checkpoint does not exist, or it belongs to another team.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
code string required
Example: NOT_FOUND

A service-defined error code.

message string required
Example: MicroVM not found

A human-readable description of the error.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "microvm": {
    "auto_pause": {
      "enabled": true,
      "idle_timeout": "5m0s"
    },
    "auto_resume": true,
    "created_at": "2026-09-29T21:38:29Z",
    "http_protocol": "http",
    "id": "01a0ef1a-d873-793d-ae6a-5dd6239be62a",
    "name": "example-microvm",
    "networking": "public",
    "ports": [
      80
    ],
    "region": "mkc1",
    "size": {
      "cpu": 1,
      "disk": 50,
      "memory": 2048
    },
    "source": {
      "oci_ref": "docker.io/library/nginx:latest"
    },
    "state": "running",
    "tags": [
      "example"
    ],
    "urls": [
      {
        "default": true,
        "hostname": "01a0ef1a-d873-793d-ae6a-5dd6239be62a.mkc1.microvm.ondigitalocean.com",
        "port": 80,
        "status": "ACTIVE"
      }
    ]
  }
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "code": "NOT_FOUND",
  "message": "MicroVM not found"
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

DELETE Delete a MicroVM

/v2/microvms/{microvm_id}
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: microvm:delete

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 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
  • 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"

To delete a MicroVM and the data on its disk, send a DELETE request to /v2/microvms/{microvm_id}. The MicroVM's checkpoints are not deleted.

A successful request returns a 204 No Content status code.

Path Parameters

microvm_id string (uuid) required
Example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a

The unique ID of the MicroVM.

Request: /v2/microvms/{microvm_id}
curl -X DELETE \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/microvms/01a0ef1a-d873-793d-ae6a-5dd6239be62a"

Responses

204

The action was successful and the response body is empty.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The MicroVM or checkpoint does not exist, or it belongs to another team.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
code string required
Example: NOT_FOUND

A service-defined error code.

message string required
Example: MicroVM not found

A human-readable description of the error.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "code": "NOT_FOUND",
  "message": "MicroVM not found"
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Pause a MicroVM

/v2/microvms/{microvm_id}/pause
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: microvm:update

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 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
  • 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"

To pause a MicroVM, send a POST request to /v2/microvms/{microvm_id}/pause.

Pausing suspends the MicroVM's processes and preserves its memory, files, and processes. A paused MicroVM incurs storage charges only. The request returns when the change completes. Pausing a MicroVM that is already paused succeeds. The request returns HTTP 400 when the MicroVM is creating, terminated, or failed.

Path Parameters

microvm_id string (uuid) required
Example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a

The unique ID of the MicroVM.

Request: /v2/microvms/{microvm_id}/pause
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/microvms/01a0ef1a-d873-793d-ae6a-5dd6239be62a/pause"

Responses

200

The response will be a JSON object with a key called microvm. The value will be an object containing the standard attributes associated with a MicroVM.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
microvm object optional

A MicroVM. All fields are set at creation. There is no update endpoint.

Show child properties
auto_pause object optional

Automatic pause settings. A MicroVM always pauses after it is idle for idle_timeout. Sending enabled set to false is rejected.

Show child properties
enabled boolean optional
Example: true

Whether auto-pause is on. Always true.

idle_timeout string optional
Example: 5m0s

How long the MicroVM is idle before it pauses, as a duration such as 30s, 5m, or 1h. Defaults to 5m. The maximum is 4h. Responses show the duration in the form 5m0s.

auto_resume boolean optional
Example: true

Whether an HTTP request, command, or console session resumes the MicroVM when it is paused.

created_at string (date-time) optional read-only
Example: 2026-09-29T21:38:29Z

When the MicroVM was created, in ISO 8601 format.

failure_reason string optional read-only
Example: workload container exited (code 0): exited with code 0

Why the MicroVM failed. Present only when state is failed.

http_protocol string, one of: http, http2 optional Nullable
Example: http

The protocol the MicroVM's HTTP port serves. null if the protocol was not set when the MicroVM was created.

id string (uuid) optional read-only
Example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a

The unique ID of the MicroVM.

name string optional
Example: example-microvm

The name of the MicroVM. Must be unique in the region and contain 1 to 63 lowercase letters, digits, and hyphens.

networking string, one of: public, vpc optional
Example: public

public sends outbound traffic through a shared NAT gateway. vpc places the MicroVM in the VPC network set by vpc_uuid.

ports array of integer optional
Example: [80]

The guest ports declared on the MicroVM, including the HTTP port. During the public preview, only the HTTP port is reachable through the MicroVM's endpoint.

region string optional
Example: mkc1

The slug of the region the MicroVM is in.

size object optional

The MicroVM's size. cpu and memory must be one of the pairs 1/2048, 2/4096, 8/16384, or 16/32768. The size sets the disk, which is returned in responses.

Show child properties
cpu integer required
Example: 1

The number of vCPUs.

disk integer optional read-only
Example: 50

The size of the disk, in GB. Set by the size.

memory integer required
Example: 2048

The amount of memory, in MiB.

source object optional

What the MicroVM runs. Set exactly one of oci_ref or checkpoint_id.

Show child properties
checkpoint_id string (uuid) optional
Example: 01a0ed98-0a74-75dd-a625-e4856adbc298

The ID of a checkpoint to create the MicroVM from. The new MicroVM inherits the checkpoint's region, size, container image, and environment variables.

oci_ref string optional
Example: docker.io/library/nginx:latest

A reference to a linux/amd64 container image in the form registry/repository:tag. The image can be public, such as an image on Docker Hub, or private in your team's DigitalOcean Container Registry.

state string (enum) optional read-only
Example: running

The MicroVM's current state.

tags array of string optional
Example: ["example"]

The tags applied to the MicroVM.

urls array of object optional read-only

The MicroVM's HTTPS endpoints. The entry with default set to true is the endpoint for the HTTP port.

Show child properties
default boolean optional
Example: true

Whether this is the endpoint for the MicroVM's HTTP port.

hostname string optional
Example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a.mkc1.microvm.ondigitalocean.com

The endpoint's hostname. Empty until provisioning finishes. Requests to the endpoint must include a DigitalOcean API token with the microvm:access scope in the Authorization header.

port integer optional
Example: 80

The guest port the endpoint serves.

status string, one of: PENDING, ACTIVE optional
Example: ACTIVE

PENDING until provisioning finishes, then ACTIVE.

vpc_uuid string (uuid) optional
Example: 5a4981aa-9653-4bd1-bef5-d6bff52042e4

The ID of a VPC network in the same region that belongs to your team. Present only when networking is vpc.

400

The request was malformed, failed validation, or is not allowed in the resource's current state.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
code string required
Example: NOT_FOUND

A service-defined error code.

message string required
Example: MicroVM not found

A human-readable description of the error.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The MicroVM or checkpoint does not exist, or it belongs to another team.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
code string required
Example: NOT_FOUND

A service-defined error code.

message string required
Example: MicroVM not found

A human-readable description of the error.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "microvm": {
    "auto_pause": {
      "enabled": true,
      "idle_timeout": "5m0s"
    },
    "auto_resume": true,
    "created_at": "2026-09-29T21:38:29Z",
    "http_protocol": "http",
    "id": "01a0ef1a-d873-793d-ae6a-5dd6239be62a",
    "name": "example-microvm",
    "networking": "public",
    "ports": [
      80
    ],
    "region": "mkc1",
    "size": {
      "cpu": 1,
      "disk": 50,
      "memory": 2048
    },
    "source": {
      "oci_ref": "docker.io/library/nginx:latest"
    },
    "state": "running",
    "tags": [
      "example"
    ],
    "urls": [
      {
        "default": true,
        "hostname": "01a0ef1a-d873-793d-ae6a-5dd6239be62a.mkc1.microvm.ondigitalocean.com",
        "port": 80,
        "status": "ACTIVE"
      }
    ]
  }
}
Example 
{
  "code": "INVALID_AUTO_PAUSE",
  "message": "auto_pause.enabled cannot be false; omit it to keep the 5 minute default, or set idle_timeout up to the account maximum"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "code": "NOT_FOUND",
  "message": "MicroVM not found"
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Resume a MicroVM

/v2/microvms/{microvm_id}/resume
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: microvm:update

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 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
  • 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"

To resume a paused MicroVM, send a POST request to /v2/microvms/{microvm_id}/resume.

The request returns when the change completes. Resuming a MicroVM that is already running succeeds. The request returns HTTP 400 when the MicroVM is creating, terminated, or failed.

Path Parameters

microvm_id string (uuid) required
Example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a

The unique ID of the MicroVM.

Request: /v2/microvms/{microvm_id}/resume
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "https://api.digitalocean.com/v2/microvms/01a0ef1a-d873-793d-ae6a-5dd6239be62a/resume"

Responses

200

The response will be a JSON object with a key called microvm. The value will be an object containing the standard attributes associated with a MicroVM.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
microvm object optional

A MicroVM. All fields are set at creation. There is no update endpoint.

Show child properties
auto_pause object optional

Automatic pause settings. A MicroVM always pauses after it is idle for idle_timeout. Sending enabled set to false is rejected.

Show child properties
enabled boolean optional
Example: true

Whether auto-pause is on. Always true.

idle_timeout string optional
Example: 5m0s

How long the MicroVM is idle before it pauses, as a duration such as 30s, 5m, or 1h. Defaults to 5m. The maximum is 4h. Responses show the duration in the form 5m0s.

auto_resume boolean optional
Example: true

Whether an HTTP request, command, or console session resumes the MicroVM when it is paused.

created_at string (date-time) optional read-only
Example: 2026-09-29T21:38:29Z

When the MicroVM was created, in ISO 8601 format.

failure_reason string optional read-only
Example: workload container exited (code 0): exited with code 0

Why the MicroVM failed. Present only when state is failed.

http_protocol string, one of: http, http2 optional Nullable
Example: http

The protocol the MicroVM's HTTP port serves. null if the protocol was not set when the MicroVM was created.

id string (uuid) optional read-only
Example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a

The unique ID of the MicroVM.

name string optional
Example: example-microvm

The name of the MicroVM. Must be unique in the region and contain 1 to 63 lowercase letters, digits, and hyphens.

networking string, one of: public, vpc optional
Example: public

public sends outbound traffic through a shared NAT gateway. vpc places the MicroVM in the VPC network set by vpc_uuid.

ports array of integer optional
Example: [80]

The guest ports declared on the MicroVM, including the HTTP port. During the public preview, only the HTTP port is reachable through the MicroVM's endpoint.

region string optional
Example: mkc1

The slug of the region the MicroVM is in.

size object optional

The MicroVM's size. cpu and memory must be one of the pairs 1/2048, 2/4096, 8/16384, or 16/32768. The size sets the disk, which is returned in responses.

Show child properties
cpu integer required
Example: 1

The number of vCPUs.

disk integer optional read-only
Example: 50

The size of the disk, in GB. Set by the size.

memory integer required
Example: 2048

The amount of memory, in MiB.

source object optional

What the MicroVM runs. Set exactly one of oci_ref or checkpoint_id.

Show child properties
checkpoint_id string (uuid) optional
Example: 01a0ed98-0a74-75dd-a625-e4856adbc298

The ID of a checkpoint to create the MicroVM from. The new MicroVM inherits the checkpoint's region, size, container image, and environment variables.

oci_ref string optional
Example: docker.io/library/nginx:latest

A reference to a linux/amd64 container image in the form registry/repository:tag. The image can be public, such as an image on Docker Hub, or private in your team's DigitalOcean Container Registry.

state string (enum) optional read-only
Example: running

The MicroVM's current state.

tags array of string optional
Example: ["example"]

The tags applied to the MicroVM.

urls array of object optional read-only

The MicroVM's HTTPS endpoints. The entry with default set to true is the endpoint for the HTTP port.

Show child properties
default boolean optional
Example: true

Whether this is the endpoint for the MicroVM's HTTP port.

hostname string optional
Example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a.mkc1.microvm.ondigitalocean.com

The endpoint's hostname. Empty until provisioning finishes. Requests to the endpoint must include a DigitalOcean API token with the microvm:access scope in the Authorization header.

port integer optional
Example: 80

The guest port the endpoint serves.

status string, one of: PENDING, ACTIVE optional
Example: ACTIVE

PENDING until provisioning finishes, then ACTIVE.

vpc_uuid string (uuid) optional
Example: 5a4981aa-9653-4bd1-bef5-d6bff52042e4

The ID of a VPC network in the same region that belongs to your team. Present only when networking is vpc.

400

The request was malformed, failed validation, or is not allowed in the resource's current state.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
code string required
Example: NOT_FOUND

A service-defined error code.

message string required
Example: MicroVM not found

A human-readable description of the error.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The MicroVM or checkpoint does not exist, or it belongs to another team.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
code string required
Example: NOT_FOUND

A service-defined error code.

message string required
Example: MicroVM not found

A human-readable description of the error.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "microvm": {
    "auto_pause": {
      "enabled": true,
      "idle_timeout": "5m0s"
    },
    "auto_resume": true,
    "created_at": "2026-09-29T21:38:29Z",
    "http_protocol": "http",
    "id": "01a0ef1a-d873-793d-ae6a-5dd6239be62a",
    "name": "example-microvm",
    "networking": "public",
    "ports": [
      80
    ],
    "region": "mkc1",
    "size": {
      "cpu": 1,
      "disk": 50,
      "memory": 2048
    },
    "source": {
      "oci_ref": "docker.io/library/nginx:latest"
    },
    "state": "running",
    "tags": [
      "example"
    ],
    "urls": [
      {
        "default": true,
        "hostname": "01a0ef1a-d873-793d-ae6a-5dd6239be62a.mkc1.microvm.ondigitalocean.com",
        "port": 80,
        "status": "ACTIVE"
      }
    ]
  }
}
Example 
{
  "code": "INVALID_AUTO_PAUSE",
  "message": "auto_pause.enabled cannot be false; omit it to keep the 5 minute default, or set idle_timeout up to the account maximum"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "code": "NOT_FOUND",
  "message": "MicroVM not found"
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Run a command in a MicroVM

/v2/microvms/{microvm_id}/exec
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: microvm:update

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 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
  • 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"

To run a command in a MicroVM's workload container, send a POST request to /v2/microvms/{microvm_id}/exec.

argv runs directly, not through a shell, with standard input closed. If the MicroVM is paused and auto-resume is on, the request resumes it and waits until it is running.

A command has 60 seconds to finish. Your team can run 32 commands at once and 60 commands per minute. Rejected requests count toward the per-minute limit.

Path Parameters

microvm_id string (uuid) required
Example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a

The unique ID of the MicroVM.

Request Body: application/json

argv array of string required
Example: ["nginx","-v"]

The command and its arguments.

cwd string optional
Example: /usr/share/nginx/html

The working directory to run the command in.

Request: /v2/microvms/{microvm_id}/exec
Content type application/json
Example 
{
  "argv": [
    "nginx",
    "-v"
  ]
}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"argv": ["nginx", "-v"]}' \
  "https://api.digitalocean.com/v2/microvms/01a0ef1a-d873-793d-ae6a-5dd6239be62a/exec"

Responses

200

The command ran. HTTP 200 is returned even when the command itself fails. Check exit_code for the command's result.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
exit_code integer optional
Example: 0

The command's exit code.

stderr string optional

The command's standard error. Bytes that are not valid UTF-8 are replaced.

stdout string optional

The command's standard output. Bytes that are not valid UTF-8 are replaced.

truncated boolean optional
Example: false

Present and true when the output exceeded 4 MiB and was cut off.

400

The request was malformed, failed validation, or is not allowed in the resource's current state.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
code string required
Example: NOT_FOUND

A service-defined error code.

message string required
Example: MicroVM not found

A human-readable description of the error.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

403

The token does not have the required scope, or your team has reached a limit.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
code string required
Example: NOT_FOUND

A service-defined error code.

message string required
Example: MicroVM not found

A human-readable description of the error.

404

The MicroVM or checkpoint does not exist, or it belongs to another team.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
code string required
Example: NOT_FOUND

A service-defined error code.

message string required
Example: MicroVM not found

A human-readable description of the error.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

502

The command did not reach the workload, for example because the container is not running.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
code string required
Example: NOT_FOUND

A service-defined error code.

message string required
Example: MicroVM not found

A human-readable description of the error.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "exit_code": 0,
  "stderr": "nginx version: nginx/1.29.1\n",
  "stdout": ""
}
Example 
{
  "code": "INVALID_AUTO_PAUSE",
  "message": "auto_pause.enabled cannot be false; omit it to keep the 5 minute default, or set idle_timeout up to the account maximum"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "code": "PERMISSION_DENIED",
  "message": "permission denied"
}
{
  "code": "NOT_FOUND",
  "message": "MicroVM not found"
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "code": "UNAVAILABLE",
  "message": "workload unavailable"
}
{
  "id": "example_error",
  "message": "some error message"
}

GET Open a console in a MicroVM

/v2/microvms/{microvm_id}/console
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: microvm:update

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 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
  • 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"

To open an interactive /bin/sh console in a MicroVM's workload container, open a WebSocket connection to wss://api.digitalocean.com/v2/microvms/{microvm_id}/console.

Send the API token in the Authorization header of the handshake. Browsers cannot set this header, so you cannot open the console from browser JavaScript. The image must include /bin/sh. A MicroVM can have four consoles open at a time. If the MicroVM is paused and auto-resume is on, opening a console resumes it.

Path Parameters

microvm_id string (uuid) required
Example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a

The unique ID of the MicroVM.

Query Parameters

rows integer 1 – 65535 optional
Example: 24

The initial number of terminal rows.

Default: 24
cols integer 1 – 65535 optional
Example: 80

The initial number of terminal columns.

Default: 80
Request: /v2/microvms/{microvm_id}/console
websocat -b \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  "wss://api.digitalocean.com/v2/microvms/01a0ef1a-d873-793d-ae6a-5dd6239be62a/console?rows=24&cols=80"
curl -X GET \
  -H "Authorization: Bearer $API_TOKEN" \
  "https://api.digitalocean.com/v2/microvms/{microvm_id}/console"

Responses

101

The connection is upgraded to a WebSocket. Binary frames from the client are terminal input, and text frames are resize messages such as {"resize":{"rows":40,"cols":120}}. Binary frames from the server are terminal output with stdout and stderr combined. Text frames from the server are control messages: {"status":{"state":"resuming"}} while a paused MicroVM resumes, {"error":{"code":"...","message":"..."}} when the console fails to connect or start (with code set to dial_failed, start_failed, or agent_error), and {"exit":{"code":0}} when the shell exits. The server sends a ping every 30 seconds. A console closes after 4 hours, or after 30 minutes with no input and no output. A message larger than 1 MiB closes the console with WebSocket code 1009.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

403

The token does not have the required scope, or your team has reached a limit.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
code string required
Example: NOT_FOUND

A service-defined error code.

message string required
Example: MicroVM not found

A human-readable description of the error.

404

The MicroVM or checkpoint does not exist, or it belongs to another team.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
code string required
Example: NOT_FOUND

A service-defined error code.

message string required
Example: MicroVM not found

A human-readable description of the error.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "code": "PERMISSION_DENIED",
  "message": "permission denied"
}
{
  "code": "NOT_FOUND",
  "message": "MicroVM not found"
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

POST Create a checkpoint of a MicroVM

/v2/microvms/{microvm_id}/checkpoints
Authorizations: bearer_auth (1 scope)
Http: Bearer
Required scopes: microvm:create

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 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
  • 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"

To create a checkpoint of a running or paused MicroVM, send a POST request to /v2/microvms/{microvm_id}/checkpoints.

The capture runs in the background and does not change the MicroVM's state. Poll GET /v2/microvms/checkpoints/{checkpoint_id} until status is CHECKPOINT_AVAILABLE.

Path Parameters

microvm_id string (uuid) required
Example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a

The unique ID of the MicroVM.

Request Body: application/json

name string optional
Example: example-checkpoint

A name for the checkpoint. If you omit it, a name such as checkpoint-20260929-143559 is generated.

Request: /v2/microvms/{microvm_id}/checkpoints
Content type application/json 
{
  "name": "example-checkpoint"
}
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -d '{"name": "example-checkpoint"}' \
  "https://api.digitalocean.com/v2/microvms/01a0ef1a-d873-793d-ae6a-5dd6239be62a/checkpoints"

Responses

201

The response will be a JSON object with a key called checkpoint. The value will be an object containing the standard attributes associated with a checkpoint.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
checkpoint object optional

A checkpoint of a MicroVM's memory and disk. New MicroVMs created from a checkpoint start from that state.

Show child properties
created_at string (date-time) optional read-only
Example: 2026-09-29T14:35:59Z

When the checkpoint was created, in ISO 8601 format.

disk_bytes integer (int64) optional read-only
Example: 1073741824

The stored size of the checkpoint's disk, in bytes.

id string (uuid) optional read-only
Example: 01a0ed98-0a74-75dd-a625-e4856adbc298

The unique ID of the checkpoint.

memory_bytes integer (int64) optional read-only
Example: 2147483648

The stored size of the checkpoint's memory, in bytes.

microvm_id string (uuid) optional read-only
Example: 01a0ed71-4efb-718f-9598-ca9cba942595

The ID of the MicroVM the checkpoint was taken from.

microvm_name string optional read-only
Example: example-microvm

The name of the MicroVM the checkpoint was taken from.

name string optional
Example: checkpoint-20260929-143559

The name of the checkpoint. If you do not set one, a name such as checkpoint-20260929-143559 is generated.

region string optional read-only
Example: mkc1

The slug of the checkpoint's region.

size object optional

The MicroVM's size. cpu and memory must be one of the pairs 1/2048, 2/4096, 8/16384, or 16/32768. The size sets the disk, which is returned in responses.

Show child properties
cpu integer required
Example: 1

The number of vCPUs.

disk integer optional read-only
Example: 50

The size of the disk, in GB. Set by the size.

memory integer required
Example: 2048

The amount of memory, in MiB.

status string, one of: CHECKPOINT_CREATING, CHECKPOINT_AVAILABLE, CHECKPOINT_FAILED, CHECKPOINT_DELETING, CHECKPOINT_DELETED optional read-only
Example: CHECKPOINT_AVAILABLE

The checkpoint's status. You can create MicroVMs from the checkpoint when it is CHECKPOINT_AVAILABLE.

400

The request was malformed, failed validation, or is not allowed in the resource's current state.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
code string required
Example: NOT_FOUND

A service-defined error code.

message string required
Example: MicroVM not found

A human-readable description of the error.

401

Authentication failed due to invalid credentials.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

404

The MicroVM or checkpoint does not exist, or it belongs to another team.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
code string required
Example: NOT_FOUND

A service-defined error code.

message string required
Example: MicroVM not found

A human-readable description of the error.

429

The API rate limit has been exceeded.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

500

There was a server error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

default

There was an unexpected error.
Response Headers
ratelimit-limit integer

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.

ratelimit-remaining integer

The number of requests in your hourly quota that remain before you hit your request limit. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

ratelimit-reset integer

The time when the oldest request will expire. The value is given in Unix epoch time. See https://docs.digitalocean.com/reference/api/reference/#rate-limit for information about how requests expire.

Response Schema: application/json
id string required
Example: not_found

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."

message string required
Example: The resource you were accessing could not be found.

A message providing additional information about the error, including details to help resolve it when possible.

request_id string optional
Example: 4d9d8375-3c56-4925-a3e7-eb137fed17e9

Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Response
{
  "checkpoint": {
    "created_at": "2026-09-29T14:35:59Z",
    "disk_bytes": 1073741824,
    "id": "01a0ed98-0a74-75dd-a625-e4856adbc298",
    "memory_bytes": 2147483648,
    "microvm_id": "01a0ef1a-d873-793d-ae6a-5dd6239be62a",
    "microvm_name": "example-microvm",
    "name": "example-checkpoint",
    "region": "mkc1",
    "size": {
      "cpu": 1,
      "disk": 50,
      "memory": 2048
    },
    "status": "CHECKPOINT_AVAILABLE"
  }
}
Example 
{
  "code": "INVALID_AUTO_PAUSE",
  "message": "auto_pause.enabled cannot be false; omit it to keep the 5 minute default, or set idle_timeout up to the account maximum"
}
{
  "id": "unauthorized",
  "message": "Unable to authenticate you."
}
{
  "code": "NOT_FOUND",
  "message": "MicroVM not found"
}
{
  "id": "too_many_requests",
  "message": "API rate limit exceeded."
}
{
  "id": "server_error",
  "message": "Unexpected server-side error"
}
{
  "id": "example_error",
  "message": "some error message"
}

We can't find any results for your search.

Try using different keywords or simplifying your search terms.