DigitalOcean MicroVMs API Reference
Last verified 9 Oct 2026
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, update, pause, resume,
and delete MicroVMs, run commands and open a console in them, upload and
download files, add and remove ingress URLs, create access tokens scoped
to one MicroVM, 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.
https://api.digitalocean.com
Endpoints
GET List all MicroVMs
/v2/microvms
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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
>= 1 optional
1Which 'page' of paginated results to return.
Default:1per_page
1 – 200 optional
25Number of items returned per page.
Default:25region
optional
mkc1Only return MicroVMs in this region.
name
optional
example-microvmOnly return MicroVMs whose name contains this substring (case-insensitive).
tag_name
optional
exampleOnly 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.
microvms. The value will be an array of MicroVM objects.ratelimit-limit
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
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
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.
application/json
microvms
optional
Show child properties
auto_pause
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
optional
trueWhether auto-pause is on. Always true.
idle_timeout
optional
5m0sHow 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
optional
trueWhether an HTTP request, command, or console session resumes the MicroVM when it is paused.
created_at
optional read-only
2026-09-29T21:38:29ZWhen the MicroVM was created, in ISO 8601 format.
egress_policy
optional
An outbound allow list. A destination that matches any rule is allowed; default_action decides every other destination. Only valid with public networking, and fixed at create: there is no way to change it later. With a policy set, direct connections out of the MicroVM are dropped; only HTTP and HTTPS through the platform proxy to the allowed destinations works, so clients must honor the injected HTTP_PROXY / HTTPS_PROXY environment. The registries needed to pull the workload image are allowed automatically. On a MicroVM this is the policy set at create, as supplied, except that credential secrets are never returned. On a checkpoint it is the policy a restored MicroVM inherits; a restore cannot change it. Omitted when egress is unrestricted.
Show child properties
credentials
optional
Credentials the platform adds to outbound requests, so the workload never holds them. Settable only at create, and only in regions that support credential injection. Each host must be allowed by a rule (or default_action must be allow). HTTPS requests to these hosts are intercepted so the credential can be attached; clients that pin certificates will fail on them. The credential is sent in the authorization header. Credentials cannot be set when restoring a checkpoint: the restored MicroVM inherits the origin's. Responses include host, path_prefix, and scheme for each credential. The secret is never returned.
Show child properties
host
required
api.example.comAn exact host. Wildcards and IP addresses are not allowed.
path_prefix
optional
/v1Only requests whose path starts with this prefix get the credential. Must start with /. Defaults to every path.
scheme
optional
bearerHow the value is sent. bearer sends Bearer <secret>; raw sends the secret as is.
secret
required write-only
s3cr3t-t0k3nThe credential value. It is stored in a secrets vault, never returned by the API, and cannot be read back.
default_action
optional
denyWhat to do with a destination no rule matches. deny refuses it (an HTTP request gets a 403 and a TLS connection is closed).
rules
optional
The destinations to allow. Rules match the host only: port, path, and method are not considered, and a hostname that resolves to an IP is not matched by an ip rule. Each rule sets exactly one of domain or ip.
Show child properties
domain
optional
api.example.comAn exact host such as api.example.com, or a wildcard such as *.example.com.
ip
optional
203.0.113.5An exact IP address. CIDR ranges are not supported.
failure_reason
optional read-only
workload container exited (code 0): exited with code 0Why the MicroVM failed. Present only when state is failed.
http_protocol
optional Nullable
httpThe protocol the MicroVM's HTTP port serves. null if the protocol was not set when the MicroVM was created.
id
optional read-only
01a0ef1a-d873-793d-ae6a-5dd6239be62aThe unique ID of the MicroVM.
name
optional
example-microvmThe name of the MicroVM. Must be unique in the region and contain 1 to 63 lowercase letters, digits, and hyphens.
networking
optional
publicpublic sends outbound traffic through a shared NAT gateway. vpc places the MicroVM in a VPC network. The VPC ID is not returned.
ports
optional
[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
optional
mkc1The slug of the region the MicroVM is in.
size
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
required
1The number of vCPUs.
disk
optional read-only
50The size of the disk, in GB. Set by the size.
memory
required
2048The amount of memory, in MiB.
source
optional
What the MicroVM runs. Set exactly one of oci_ref or checkpoint_id.
Show child properties
checkpoint_id
optional
01a0ed98-0a74-75dd-a625-e4856adbc298The 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
optional
docker.io/library/nginx:latestA 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
optional read-only
runningThe MicroVM's current state.
urls
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
optional
trueWhether this is the endpoint for the MicroVM's HTTP port.
hostname
optional
01a0ef1a-d873-793d-ae6a-5dd6239be62a.mkc1.microvm.ondigitalocean.comThe 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.
id
optional read-only
3f6c1a2b-9d4e-5f70-8a1b-2c3d4e5f6a7bThe unique ID of the URL. Use it to remove the URL with DELETE /v2/microvms/{microvm_id}/urls/{url_id}.
port
optional
80The guest port the endpoint serves.
status
optional
ACTIVEPENDING until provisioning finishes, then ACTIVE.
project_id
optional
4de7ac8b-495b-4884-9a69-1050c6793cd6The project the MicroVM belongs to. Omitted when the project could not be resolved.
tags
optional
["example"]The tags applied to the MicroVM.
links
optional
Show child properties
pages
optional
Forward Links
last
optional
https://api.digitalocean.com/v2/images?page=2URI of the last page of the results.
next
optional
https://api.digitalocean.com/v2/images?page=2URI of the next page of the results.
Backward Links
first
optional
https://api.digitalocean.com/v2/images?page=1URI of the first page of the results.
prev
optional
https://api.digitalocean.com/v2/images?page=1URI of the previous page of the results.
meta
required
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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
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
optional
trueWhether auto-pause is on. Always true.
idle_timeout
optional
5m0sHow 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
optional
trueWhether an HTTP request, command, or console session resumes the MicroVM when it is paused. Set to false to require a manual resume.
egress_policy
optional
An outbound allow list. A destination that matches any rule is allowed; default_action decides every other destination. Only valid with public networking, and fixed at create: there is no way to change it later. With a policy set, direct connections out of the MicroVM are dropped; only HTTP and HTTPS through the platform proxy to the allowed destinations works, so clients must honor the injected HTTP_PROXY / HTTPS_PROXY environment. The registries needed to pull the workload image are allowed automatically. On a MicroVM this is the policy set at create, as supplied, except that credential secrets are never returned. On a checkpoint it is the policy a restored MicroVM inherits; a restore cannot change it. Omitted when egress is unrestricted.
Show child properties
credentials
optional
Credentials the platform adds to outbound requests, so the workload never holds them. Settable only at create, and only in regions that support credential injection. Each host must be allowed by a rule (or default_action must be allow). HTTPS requests to these hosts are intercepted so the credential can be attached; clients that pin certificates will fail on them. The credential is sent in the authorization header. Credentials cannot be set when restoring a checkpoint: the restored MicroVM inherits the origin's. Responses include host, path_prefix, and scheme for each credential. The secret is never returned.
Show child properties
host
required
api.example.comAn exact host. Wildcards and IP addresses are not allowed.
path_prefix
optional
/v1Only requests whose path starts with this prefix get the credential. Must start with /. Defaults to every path.
scheme
optional
bearerHow the value is sent. bearer sends Bearer <secret>; raw sends the secret as is.
secret
required write-only
s3cr3t-t0k3nThe credential value. It is stored in a secrets vault, never returned by the API, and cannot be read back.
default_action
optional
denyWhat to do with a destination no rule matches. deny refuses it (an HTTP request gets a 403 and a TLS connection is closed).
rules
optional
The destinations to allow. Rules match the host only: port, path, and method are not considered, and a hostname that resolves to an IP is not matched by an ip rule. Each rule sets exactly one of domain or ip.
Show child properties
domain
optional
api.example.comAn exact host such as api.example.com, or a wildcard such as *.example.com.
ip
optional
203.0.113.5An exact IP address. CIDR ranges are not supported.
environment
optional
{"APP_ENV":"production"}Environment variables passed into the MicroVM at boot, as key and value pairs. Not returned in responses.
http_port
optional
80The 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
optional
httpThe protocol the HTTP port serves.
ingress
optional
trueWhether to create the MicroVM with a default public URL. Defaults to true. Set to false to create the MicroVM without one; URLs can be added later with POST /v2/microvms/{microvm_id}/urls.
name
required
example-microvmThe name of the MicroVM. Must be unique in the region and contain 1 to 63 lowercase letters, digits, and hyphens.
networking
optional
publicpublic sends outbound traffic through a shared NAT gateway. vpc places the MicroVM in the VPC network set by vpc_uuid.
ports
optional
[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.
project_id
optional
4de7ac8b-495b-4884-9a69-1050c6793cd6The project to place the MicroVM in. Omit to use the team's default project. A project that does not belong to the team is rejected.
region
optional
mkc1The slug of the region to create the MicroVM in. Required with source.oci_ref.
size
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
required
1The number of vCPUs.
disk
optional read-only
50The size of the disk, in GB. Set by the size.
memory
required
2048The amount of memory, in MiB.
source
required
What the MicroVM runs. Set exactly one of oci_ref or checkpoint_id.
Show child properties
checkpoint_id
optional
01a0ed98-0a74-75dd-a625-e4856adbc298The 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
optional
docker.io/library/nginx:latestA 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
optional
["example"]Tags to apply to the MicroVM.
vpc_uuid
optional
5a4981aa-9653-4bd1-bef5-d6bff52042e4The ID of a VPC network in the same region that belongs to your team. When networking is vpc and this is omitted, the team's default VPC is used.
Request: /v2/microvms
{
"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.
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.ratelimit-limit
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
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
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.
application/json
microvm
optional
400
The request was malformed, failed validation, or is not allowed in the resource's current state.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
429
The API rate limit has been exceeded.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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"
}
]
}
}{
"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)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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.
ratelimit-limit
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
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
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.
application/json
account_limits
optional
Your team's MicroVM limits.
Show child properties
max_disk_bytes
optional
429496729600The maximum disk per MicroVM, in bytes.
max_idle_timeout_seconds
optional
14400The maximum auto-pause idle timeout, in seconds.
max_memory_bytes
optional
34359738368The maximum memory per MicroVM, in bytes.
max_total_count
optional
1000The maximum number of MicroVMs, counting both running and paused MicroVMs.
default_region
optional
mkc1The slug of the region MicroVMs are created in by default.
features
optional
Features and whether they are enabled for your team. exec_pty gates exec and console; file_transfer gates files; egress_policy gates egress_policy on create; egress_credentials gates egress_policy.credentials (requires egress_policy, and only in regions that support credential injection).
Show child properties
enabled
optional
trueWhether the feature is enabled.
name
optional
exec_ptyThe name of the feature.
resource_pricing
optional
Per-resource rates, in USD.
Show child properties
price_per_gib_bandwidth
optional
0.01The price per GiB of outbound data transfer.
price_per_gib_memory_hour
optional
0.0085The price per GiB of memory per hour of running time.
price_per_gib_storage_month
optional
0.05The price per GiB-month of disk and checkpoint storage.
price_per_vcpu_hour
optional
0.022The price per vCPU per hour of running time.
sizes
optional
The sizes available to your team.
Show child properties
available
optional
trueWhether the size is available on your team's plan.
cpu
optional
1The number of vCPUs.
disk
optional
50The size of the disk, in GB.
memory
optional
2048The amount of memory, in MiB.
pricing
optional
The compute price of the size.
Show child properties
price_per_hour
optional
0.039The price per hour of running time, in USD.
price_per_month
optional
28.47The price for running continuously for a month (730 hours), in USD.
regions
optional
["mkc1"]The slugs of the regions the size is available in.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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
>= 1 optional
1Which 'page' of paginated results to return.
Default:1per_page
1 – 200 optional
25Number of items returned per page.
Default:25microvm_id
optional
01a0ef1a-d873-793d-ae6a-5dd6239be62aOnly 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.
checkpoints. The value will be an array of checkpoint objects, newest first.ratelimit-limit
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
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
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.
application/json
checkpoints
optional
Show child properties
created_at
optional read-only
2026-09-29T14:35:59ZWhen the checkpoint was created, in ISO 8601 format.
disk_bytes
optional read-only
1073741824The stored size of the checkpoint's disk, in bytes.
egress_policy
optional
An outbound allow list. A destination that matches any rule is allowed; default_action decides every other destination. Only valid with public networking, and fixed at create: there is no way to change it later. With a policy set, direct connections out of the MicroVM are dropped; only HTTP and HTTPS through the platform proxy to the allowed destinations works, so clients must honor the injected HTTP_PROXY / HTTPS_PROXY environment. The registries needed to pull the workload image are allowed automatically. On a MicroVM this is the policy set at create, as supplied, except that credential secrets are never returned. On a checkpoint it is the policy a restored MicroVM inherits; a restore cannot change it. Omitted when egress is unrestricted.
Show child properties
credentials
optional
Credentials the platform adds to outbound requests, so the workload never holds them. Settable only at create, and only in regions that support credential injection. Each host must be allowed by a rule (or default_action must be allow). HTTPS requests to these hosts are intercepted so the credential can be attached; clients that pin certificates will fail on them. The credential is sent in the authorization header. Credentials cannot be set when restoring a checkpoint: the restored MicroVM inherits the origin's. Responses include host, path_prefix, and scheme for each credential. The secret is never returned.
Show child properties
host
required
api.example.comAn exact host. Wildcards and IP addresses are not allowed.
path_prefix
optional
/v1Only requests whose path starts with this prefix get the credential. Must start with /. Defaults to every path.
scheme
optional
bearerHow the value is sent. bearer sends Bearer <secret>; raw sends the secret as is.
secret
required write-only
s3cr3t-t0k3nThe credential value. It is stored in a secrets vault, never returned by the API, and cannot be read back.
default_action
optional
denyWhat to do with a destination no rule matches. deny refuses it (an HTTP request gets a 403 and a TLS connection is closed).
rules
optional
The destinations to allow. Rules match the host only: port, path, and method are not considered, and a hostname that resolves to an IP is not matched by an ip rule. Each rule sets exactly one of domain or ip.
Show child properties
domain
optional
api.example.comAn exact host such as api.example.com, or a wildcard such as *.example.com.
ip
optional
203.0.113.5An exact IP address. CIDR ranges are not supported.
failure_reason
optional read-only
another checkpoint of this MicroVM is in progress; retry shortlyWhy the checkpoint failed. Present only when status is CHECKPOINT_FAILED.
id
optional read-only
01a0ed98-0a74-75dd-a625-e4856adbc298The unique ID of the checkpoint.
memory_bytes
optional read-only
2147483648The stored size of the checkpoint's memory, in bytes.
microvm_id
optional read-only
01a0ed71-4efb-718f-9598-ca9cba942595The ID of the MicroVM the checkpoint was taken from.
microvm_name
optional read-only
example-microvmThe name of the MicroVM the checkpoint was taken from.
name
optional
checkpoint-20260929-143559The name of the checkpoint. If you do not set one, a name such as checkpoint-20260929-143559 is generated.
region
optional read-only
mkc1The slug of the checkpoint's region.
size
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
required
1The number of vCPUs.
disk
optional read-only
50The size of the disk, in GB. Set by the size.
memory
required
2048The amount of memory, in MiB.
status
optional read-only
CHECKPOINT_AVAILABLEThe checkpoint's status. You can create MicroVMs from the checkpoint when it is CHECKPOINT_AVAILABLE.
links
optional
Show child properties
pages
optional
Forward Links
last
optional
https://api.digitalocean.com/v2/images?page=2URI of the last page of the results.
next
optional
https://api.digitalocean.com/v2/images?page=2URI of the next page of the results.
Backward Links
first
optional
https://api.digitalocean.com/v2/images?page=1URI of the first page of the results.
prev
optional
https://api.digitalocean.com/v2/images?page=1URI of the previous page of the results.
meta
required
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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
required
01a0ed98-0a74-75dd-a625-e4856adbc298The 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.
checkpoint. The value will be an object containing the standard attributes associated with a checkpoint.ratelimit-limit
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
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
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.
application/json
checkpoint
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
optional read-only
2026-09-29T14:35:59ZWhen the checkpoint was created, in ISO 8601 format.
disk_bytes
optional read-only
1073741824The stored size of the checkpoint's disk, in bytes.
egress_policy
optional
An outbound allow list. A destination that matches any rule is allowed; default_action decides every other destination. Only valid with public networking, and fixed at create: there is no way to change it later. With a policy set, direct connections out of the MicroVM are dropped; only HTTP and HTTPS through the platform proxy to the allowed destinations works, so clients must honor the injected HTTP_PROXY / HTTPS_PROXY environment. The registries needed to pull the workload image are allowed automatically. On a MicroVM this is the policy set at create, as supplied, except that credential secrets are never returned. On a checkpoint it is the policy a restored MicroVM inherits; a restore cannot change it. Omitted when egress is unrestricted.
Show child properties
credentials
optional
Credentials the platform adds to outbound requests, so the workload never holds them. Settable only at create, and only in regions that support credential injection. Each host must be allowed by a rule (or default_action must be allow). HTTPS requests to these hosts are intercepted so the credential can be attached; clients that pin certificates will fail on them. The credential is sent in the authorization header. Credentials cannot be set when restoring a checkpoint: the restored MicroVM inherits the origin's. Responses include host, path_prefix, and scheme for each credential. The secret is never returned.
Show child properties
host
required
api.example.comAn exact host. Wildcards and IP addresses are not allowed.
path_prefix
optional
/v1Only requests whose path starts with this prefix get the credential. Must start with /. Defaults to every path.
scheme
optional
bearerHow the value is sent. bearer sends Bearer <secret>; raw sends the secret as is.
secret
required write-only
s3cr3t-t0k3nThe credential value. It is stored in a secrets vault, never returned by the API, and cannot be read back.
default_action
optional
denyWhat to do with a destination no rule matches. deny refuses it (an HTTP request gets a 403 and a TLS connection is closed).
rules
optional
The destinations to allow. Rules match the host only: port, path, and method are not considered, and a hostname that resolves to an IP is not matched by an ip rule. Each rule sets exactly one of domain or ip.
Show child properties
domain
optional
api.example.comAn exact host such as api.example.com, or a wildcard such as *.example.com.
ip
optional
203.0.113.5An exact IP address. CIDR ranges are not supported.
failure_reason
optional read-only
another checkpoint of this MicroVM is in progress; retry shortlyWhy the checkpoint failed. Present only when status is CHECKPOINT_FAILED.
id
optional read-only
01a0ed98-0a74-75dd-a625-e4856adbc298The unique ID of the checkpoint.
memory_bytes
optional read-only
2147483648The stored size of the checkpoint's memory, in bytes.
microvm_id
optional read-only
01a0ed71-4efb-718f-9598-ca9cba942595The ID of the MicroVM the checkpoint was taken from.
microvm_name
optional read-only
example-microvmThe name of the MicroVM the checkpoint was taken from.
name
optional
checkpoint-20260929-143559The name of the checkpoint. If you do not set one, a name such as checkpoint-20260929-143559 is generated.
region
optional read-only
mkc1The slug of the checkpoint's region.
size
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
required
1The number of vCPUs.
disk
optional read-only
50The size of the disk, in GB. Set by the size.
memory
required
2048The amount of memory, in MiB.
status
optional read-only
CHECKPOINT_AVAILABLEThe checkpoint's status. You can create MicroVMs from the checkpoint when it is CHECKPOINT_AVAILABLE.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
429
The API rate limit has been exceeded.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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
required
01a0ed98-0a74-75dd-a625-e4856adbc298The 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.
ratelimit-limit
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
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
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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
429
The API rate limit has been exceeded.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"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)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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
required
01a0ef1a-d873-793d-ae6a-5dd6239be62aThe 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.
microvm. The value will be an object containing the standard attributes associated with a MicroVM.ratelimit-limit
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
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
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.
application/json
microvm
optional
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
429
The API rate limit has been exceeded.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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"
}PATCH Update a MicroVM
/v2/microvms/{microvm_id}
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 change a MicroVM's name or tags, send a PATCH request to
/v2/microvms/{microvm_id}.
The MicroVM must be running or paused. Omitted fields keep their current
value. Every other field is fixed at create; sending one (for example
size or region) is rejected with a 400 status code, and changing it
means creating a new MicroVM.
tags replaces the whole tag set: tags not in the list are removed, and an
empty list removes every tag.
Path Parameters
microvm_id
required
01a0ef1a-d873-793d-ae6a-5dd6239be62aThe unique ID of the MicroVM.
Request Body: application/json
name
optional
example-microvm-2The new name. Must be unique in the region and contain 1 to 63 lowercase letters, digits, and hyphens.
tags
optional
["example","prod"]The complete tag set. Replaces the current tags; tags not in the list are removed, and an empty list removes every tag.
Request: /v2/microvms/{microvm_id}
{
"name": "example-microvm-2",
"tags": [
"example",
"prod"
]
}curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
-d '{"name":"example-microvm-2","tags":["example","prod"]}' \
"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.
microvm. The value will be an object containing the standard attributes associated with a MicroVM.ratelimit-limit
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
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
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.
application/json
microvm
optional
400
The request was malformed, failed validation, or is not allowed in the resource's current state.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
409
The request conflicts with the resource's current state.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
429
The API rate limit has been exceeded.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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"
}
]
}
}{
"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"
}{
"code": "CONFLICT",
"message": "another MicroVM in the region already has the requested name"
}{
"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)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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
required
01a0ef1a-d873-793d-ae6a-5dd6239be62aThe 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.
ratelimit-limit
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
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
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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
429
The API rate limit has been exceeded.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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 Add a URL to a MicroVM
/v2/microvms/{microvm_id}/urls
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 add a public URL to a MicroVM, send a POST request to
/v2/microvms/{microvm_id}/urls.
The URL routes to port, which must be one of the ports declared at create;
the MicroVM's port set cannot change. The call returns once the URL is
recorded; its status is PENDING until the route is published.
The MicroVM must be running or paused. A MicroVM can have at most 10 URLs, the default one included.
Path Parameters
microvm_id
required
01a0ef1a-d873-793d-ae6a-5dd6239be62aThe unique ID of the MicroVM.
Request Body: application/json
port
optional
8080The guest port the URL routes to. Must be one of the MicroVM's ports. Defaults to the MicroVM's HTTP port when omitted.
Request: /v2/microvms/{microvm_id}/urls
{
"port": 8080
}curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
-d '{"port":8080}' \
"https://api.digitalocean.com/v2/microvms/01a0ef1a-d873-793d-ae6a-5dd6239be62a/urls"Responses
201
The response will be a JSON object with a key called url. The value will be the added URL object.
url. The value will be the added URL object.ratelimit-limit
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
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
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.
application/json
url
optional
An HTTPS endpoint for one of the MicroVM's ports: the system default URL minted at create, or one added with POST /v2/microvms/{microvm_id}/urls.
Show child properties
default
optional
trueWhether this is the endpoint for the MicroVM's HTTP port.
hostname
optional
01a0ef1a-d873-793d-ae6a-5dd6239be62a.mkc1.microvm.ondigitalocean.comThe 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.
id
optional read-only
3f6c1a2b-9d4e-5f70-8a1b-2c3d4e5f6a7bThe unique ID of the URL. Use it to remove the URL with DELETE /v2/microvms/{microvm_id}/urls/{url_id}.
port
optional
80The guest port the endpoint serves.
status
optional
ACTIVEPENDING until provisioning finishes, then ACTIVE.
400
The request was malformed, failed validation, or is not allowed in the resource's current state.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
429
The API rate limit has been exceeded.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"url": {
"default": false,
"hostname": "3f6c1a2b9d4e5f70.mkc1.microvm.ondigitalocean.com",
"id": "3f6c1a2b-9d4e-5f70-8a1b-2c3d4e5f6a7b",
"port": 8080,
"status": "PENDING"
}
}{
"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"
}DELETE Remove a URL from a MicroVM
/v2/microvms/{microvm_id}/urls/{url_id}
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 remove a public URL from a MicroVM, send a DELETE request to
/v2/microvms/{microvm_id}/urls/{url_id}. The URL stops serving traffic.
The system default URL cannot be removed.
A successful request returns a 204 No Content status code.
Path Parameters
microvm_id
required
01a0ef1a-d873-793d-ae6a-5dd6239be62aThe unique ID of the MicroVM.
url_id
required
3f6c1a2b-9d4e-5f70-8a1b-2c3d4e5f6a7bThe unique ID of the URL, from the MicroVM's urls list.
Request: /v2/microvms/{microvm_id}/urls/{url_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/urls/3f6c1a2b-9d4e-5f70-8a1b-2c3d4e5f6a7b"Responses
204
The action was successful and the response body is empty.
ratelimit-limit
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
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
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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
429
The API rate limit has been exceeded.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"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 List the access tokens of a MicroVM
/v2/microvms/{microvm_id}/access_tokens
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 live access tokens of a MicroVM, send a GET request to
/v2/microvms/{microvm_id}/access_tokens. Tokens are returned oldest first.
Token values are never returned. The id of an entry revokes the token
with DELETE /v2/microvms/{microvm_id}/access_tokens/{token_id}.
Path Parameters
microvm_id
required
01a0ef1a-d873-793d-ae6a-5dd6239be62aThe unique ID of the MicroVM.
Request: /v2/microvms/{microvm_id}/access_tokens
curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
"https://api.digitalocean.com/v2/microvms/01a0ef1a-d873-793d-ae6a-5dd6239be62a/access_tokens"Responses
200
The response will be a JSON object with a key called access_tokens. The value will be an array of access token objects, oldest first. Token values are never returned.
access_tokens. The value will be an array of access token objects, oldest first. Token values are never returned.ratelimit-limit
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
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
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.
application/json
access_tokens
optional
Show child properties
created_at
required read-only
2026-10-21T14:02:11ZWhen the token was created, in ISO 8601 format.
expires_at
optional read-only
2026-11-20T14:02:11ZWhen the token expires. Absent when the token does not expire.
id
required read-only
4f6a1c2e-9d3b-4e7a-8f10-2b5c7d9e1a33The unique ID of the access token. Use it to revoke the token with DELETE /v2/microvms/{microvm_id}/access_tokens/{token_id}.
micro_vm_id
required read-only
01a0ef1a-d873-793d-ae6a-5dd6239be62aThe MicroVM the token grants access to.
name
required
alice-workspaceThe name given at create.
400
The request was malformed, failed validation, or is not allowed in the resource's current state.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
429
The API rate limit has been exceeded.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"access_tokens": [
{
"created_at": "2026-10-21T14:02:11Z",
"expires_at": "2026-11-20T14:02:11Z",
"id": "4f6a1c2e-9d3b-4e7a-8f10-2b5c7d9e1a33",
"micro_vm_id": "01a0ef1a-d873-793d-ae6a-5dd6239be62a",
"name": "alice-workspace"
}
]
}{
"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 Create an access token for a MicroVM
/v2/microvms/{microvm_id}/access_tokens
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 an API token that grants access to the public endpoint of one
MicroVM only, send a POST request to
/v2/microvms/{microvm_id}/access_tokens.
The token value is returned once, in this response. Save it; list never returns it. To recover a lost token, revoke it and create a new one.
The token works on every URL of the MicroVM: the default URL and any extra
URL added with POST /v2/microvms/{microvm_id}/urls. This token does not
restrict team tokens: team members with microvm:access keep their access
to the MicroVM. A MicroVM can have at most 10 live access tokens. Deleting
the MicroVM revokes its tokens.
Path Parameters
microvm_id
required
01a0ef1a-d873-793d-ae6a-5dd6239be62aThe unique ID of the MicroVM.
Request Body: application/json
expires_in_seconds
optional
2592000The lifetime of the token in seconds. Omit for a token that does not expire.
name
required
alice-workspaceA name for the token. Unique among the live access tokens of the MicroVM.
Request: /v2/microvms/{microvm_id}/access_tokens
{
"expires_in_seconds": 2592000,
"name": "alice-workspace"
}curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
-d '{"name":"alice-workspace","expires_in_seconds":2592000}' \
"https://api.digitalocean.com/v2/microvms/01a0ef1a-d873-793d-ae6a-5dd6239be62a/access_tokens"Responses
201
The response will be a JSON object with a key called access_token. The token value is shown once, in this response only.
access_token. The token value is shown once, in this response only.ratelimit-limit
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
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
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.
application/json
access_token
optional
400
The request was malformed, failed validation, or is not allowed in the resource's current state.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
409
The request conflicts with the resource's current state.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
429
The API rate limit has been exceeded.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"access_token": {
"created_at": "2026-10-21T14:02:11Z",
"expires_at": "2026-11-20T14:02:11Z",
"id": "4f6a1c2e-9d3b-4e7a-8f10-2b5c7d9e1a33",
"micro_vm_id": "01a0ef1a-d873-793d-ae6a-5dd6239be62a",
"name": "alice-workspace",
"token": "dop_v1_2f8e1c3a9b4d6e7f8a0b1c2d3e4f5a6b7c91"
}
}{
"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"
}{
"code": "CONFLICT",
"message": "another MicroVM in the region already has the requested name"
}{
"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 Revoke an access token of a MicroVM
/v2/microvms/{microvm_id}/access_tokens/{token_id}
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 revoke an access token, send a DELETE request to
/v2/microvms/{microvm_id}/access_tokens/{token_id}. The token stops
working at the edge right away and drops out of the list. Revoke is
permanent; a revoked token cannot be restored.
A successful request returns a 204 No Content status code.
Path Parameters
microvm_id
required
01a0ef1a-d873-793d-ae6a-5dd6239be62aThe unique ID of the MicroVM.
token_id
required
4f6a1c2e-9d3b-4e7a-8f10-2b5c7d9e1a33The unique ID of the access token, from the list.
Request: /v2/microvms/{microvm_id}/access_tokens/{token_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/access_tokens/4f6a1c2e-9d3b-4e7a-8f10-2b5c7d9e1a33"Responses
204
The action was successful and the response body is empty.
ratelimit-limit
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
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
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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
429
The API rate limit has been exceeded.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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
required
01a0ef1a-d873-793d-ae6a-5dd6239be62aThe 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 is the MicroVM after the pause or resume, without its tags; read tags with GET /v2/microvms/{microvm_id}.
microvm. The value is the MicroVM after the pause or resume, without its tags; read tags with GET /v2/microvms/{microvm_id}.ratelimit-limit
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
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
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.
application/json
microvm
optional
A MicroVM without its tags. Pause and resume return this shape; read tags with GET /v2/microvms/{microvm_id}.
Show child properties
auto_pause
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
optional
trueWhether auto-pause is on. Always true.
idle_timeout
optional
5m0sHow 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
optional
trueWhether an HTTP request, command, or console session resumes the MicroVM when it is paused.
created_at
optional read-only
2026-09-29T21:38:29ZWhen the MicroVM was created, in ISO 8601 format.
egress_policy
optional
An outbound allow list. A destination that matches any rule is allowed; default_action decides every other destination. Only valid with public networking, and fixed at create: there is no way to change it later. With a policy set, direct connections out of the MicroVM are dropped; only HTTP and HTTPS through the platform proxy to the allowed destinations works, so clients must honor the injected HTTP_PROXY / HTTPS_PROXY environment. The registries needed to pull the workload image are allowed automatically. On a MicroVM this is the policy set at create, as supplied, except that credential secrets are never returned. On a checkpoint it is the policy a restored MicroVM inherits; a restore cannot change it. Omitted when egress is unrestricted.
Show child properties
credentials
optional
Credentials the platform adds to outbound requests, so the workload never holds them. Settable only at create, and only in regions that support credential injection. Each host must be allowed by a rule (or default_action must be allow). HTTPS requests to these hosts are intercepted so the credential can be attached; clients that pin certificates will fail on them. The credential is sent in the authorization header. Credentials cannot be set when restoring a checkpoint: the restored MicroVM inherits the origin's. Responses include host, path_prefix, and scheme for each credential. The secret is never returned.
Show child properties
host
required
api.example.comAn exact host. Wildcards and IP addresses are not allowed.
path_prefix
optional
/v1Only requests whose path starts with this prefix get the credential. Must start with /. Defaults to every path.
scheme
optional
bearerHow the value is sent. bearer sends Bearer <secret>; raw sends the secret as is.
secret
required write-only
s3cr3t-t0k3nThe credential value. It is stored in a secrets vault, never returned by the API, and cannot be read back.
default_action
optional
denyWhat to do with a destination no rule matches. deny refuses it (an HTTP request gets a 403 and a TLS connection is closed).
rules
optional
The destinations to allow. Rules match the host only: port, path, and method are not considered, and a hostname that resolves to an IP is not matched by an ip rule. Each rule sets exactly one of domain or ip.
Show child properties
domain
optional
api.example.comAn exact host such as api.example.com, or a wildcard such as *.example.com.
ip
optional
203.0.113.5An exact IP address. CIDR ranges are not supported.
failure_reason
optional read-only
workload container exited (code 0): exited with code 0Why the MicroVM failed. Present only when state is failed.
http_protocol
optional Nullable
httpThe protocol the MicroVM's HTTP port serves. null if the protocol was not set when the MicroVM was created.
id
optional read-only
01a0ef1a-d873-793d-ae6a-5dd6239be62aThe unique ID of the MicroVM.
name
optional
example-microvmThe name of the MicroVM. Must be unique in the region and contain 1 to 63 lowercase letters, digits, and hyphens.
networking
optional
publicpublic sends outbound traffic through a shared NAT gateway. vpc places the MicroVM in a VPC network. The VPC ID is not returned.
ports
optional
[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
optional
mkc1The slug of the region the MicroVM is in.
size
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
required
1The number of vCPUs.
disk
optional read-only
50The size of the disk, in GB. Set by the size.
memory
required
2048The amount of memory, in MiB.
source
optional
What the MicroVM runs. Set exactly one of oci_ref or checkpoint_id.
Show child properties
checkpoint_id
optional
01a0ed98-0a74-75dd-a625-e4856adbc298The 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
optional
docker.io/library/nginx:latestA 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
optional read-only
runningThe MicroVM's current state.
urls
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
optional
trueWhether this is the endpoint for the MicroVM's HTTP port.
hostname
optional
01a0ef1a-d873-793d-ae6a-5dd6239be62a.mkc1.microvm.ondigitalocean.comThe 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.
id
optional read-only
3f6c1a2b-9d4e-5f70-8a1b-2c3d4e5f6a7bThe unique ID of the URL. Use it to remove the URL with DELETE /v2/microvms/{microvm_id}/urls/{url_id}.
port
optional
80The guest port the endpoint serves.
status
optional
ACTIVEPENDING until provisioning finishes, then ACTIVE.
400
The request was malformed, failed validation, or is not allowed in the resource's current state.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
429
The API rate limit has been exceeded.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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": "paused",
"urls": [
{
"default": true,
"hostname": "01a0ef1a-d873-793d-ae6a-5dd6239be62a.mkc1.microvm.ondigitalocean.com",
"id": "3f6c1a2b-9d4e-5f70-8a1b-2c3d4e5f6a7b",
"port": 80,
"status": "ACTIVE"
}
]
}
}{
"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)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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
required
01a0ef1a-d873-793d-ae6a-5dd6239be62aThe 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 is the MicroVM after the pause or resume, without its tags; read tags with GET /v2/microvms/{microvm_id}.
microvm. The value is the MicroVM after the pause or resume, without its tags; read tags with GET /v2/microvms/{microvm_id}.ratelimit-limit
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
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
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.
application/json
microvm
optional
A MicroVM without its tags. Pause and resume return this shape; read tags with GET /v2/microvms/{microvm_id}.
Show child properties
auto_pause
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
optional
trueWhether auto-pause is on. Always true.
idle_timeout
optional
5m0sHow 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
optional
trueWhether an HTTP request, command, or console session resumes the MicroVM when it is paused.
created_at
optional read-only
2026-09-29T21:38:29ZWhen the MicroVM was created, in ISO 8601 format.
egress_policy
optional
An outbound allow list. A destination that matches any rule is allowed; default_action decides every other destination. Only valid with public networking, and fixed at create: there is no way to change it later. With a policy set, direct connections out of the MicroVM are dropped; only HTTP and HTTPS through the platform proxy to the allowed destinations works, so clients must honor the injected HTTP_PROXY / HTTPS_PROXY environment. The registries needed to pull the workload image are allowed automatically. On a MicroVM this is the policy set at create, as supplied, except that credential secrets are never returned. On a checkpoint it is the policy a restored MicroVM inherits; a restore cannot change it. Omitted when egress is unrestricted.
Show child properties
credentials
optional
Credentials the platform adds to outbound requests, so the workload never holds them. Settable only at create, and only in regions that support credential injection. Each host must be allowed by a rule (or default_action must be allow). HTTPS requests to these hosts are intercepted so the credential can be attached; clients that pin certificates will fail on them. The credential is sent in the authorization header. Credentials cannot be set when restoring a checkpoint: the restored MicroVM inherits the origin's. Responses include host, path_prefix, and scheme for each credential. The secret is never returned.
Show child properties
host
required
api.example.comAn exact host. Wildcards and IP addresses are not allowed.
path_prefix
optional
/v1Only requests whose path starts with this prefix get the credential. Must start with /. Defaults to every path.
scheme
optional
bearerHow the value is sent. bearer sends Bearer <secret>; raw sends the secret as is.
secret
required write-only
s3cr3t-t0k3nThe credential value. It is stored in a secrets vault, never returned by the API, and cannot be read back.
default_action
optional
denyWhat to do with a destination no rule matches. deny refuses it (an HTTP request gets a 403 and a TLS connection is closed).
rules
optional
The destinations to allow. Rules match the host only: port, path, and method are not considered, and a hostname that resolves to an IP is not matched by an ip rule. Each rule sets exactly one of domain or ip.
Show child properties
domain
optional
api.example.comAn exact host such as api.example.com, or a wildcard such as *.example.com.
ip
optional
203.0.113.5An exact IP address. CIDR ranges are not supported.
failure_reason
optional read-only
workload container exited (code 0): exited with code 0Why the MicroVM failed. Present only when state is failed.
http_protocol
optional Nullable
httpThe protocol the MicroVM's HTTP port serves. null if the protocol was not set when the MicroVM was created.
id
optional read-only
01a0ef1a-d873-793d-ae6a-5dd6239be62aThe unique ID of the MicroVM.
name
optional
example-microvmThe name of the MicroVM. Must be unique in the region and contain 1 to 63 lowercase letters, digits, and hyphens.
networking
optional
publicpublic sends outbound traffic through a shared NAT gateway. vpc places the MicroVM in a VPC network. The VPC ID is not returned.
ports
optional
[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
optional
mkc1The slug of the region the MicroVM is in.
size
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
required
1The number of vCPUs.
disk
optional read-only
50The size of the disk, in GB. Set by the size.
memory
required
2048The amount of memory, in MiB.
source
optional
What the MicroVM runs. Set exactly one of oci_ref or checkpoint_id.
Show child properties
checkpoint_id
optional
01a0ed98-0a74-75dd-a625-e4856adbc298The 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
optional
docker.io/library/nginx:latestA 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
optional read-only
runningThe MicroVM's current state.
urls
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
optional
trueWhether this is the endpoint for the MicroVM's HTTP port.
hostname
optional
01a0ef1a-d873-793d-ae6a-5dd6239be62a.mkc1.microvm.ondigitalocean.comThe 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.
id
optional read-only
3f6c1a2b-9d4e-5f70-8a1b-2c3d4e5f6a7bThe unique ID of the URL. Use it to remove the URL with DELETE /v2/microvms/{microvm_id}/urls/{url_id}.
port
optional
80The guest port the endpoint serves.
status
optional
ACTIVEPENDING until provisioning finishes, then ACTIVE.
400
The request was malformed, failed validation, or is not allowed in the resource's current state.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
429
The API rate limit has been exceeded.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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": "paused",
"urls": [
{
"default": true,
"hostname": "01a0ef1a-d873-793d-ae6a-5dd6239be62a.mkc1.microvm.ondigitalocean.com",
"id": "3f6c1a2b-9d4e-5f70-8a1b-2c3d4e5f6a7b",
"port": 80,
"status": "ACTIVE"
}
]
}
}{
"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)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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
required
01a0ef1a-d873-793d-ae6a-5dd6239be62aThe unique ID of the MicroVM.
Request Body: application/json
argv
required
["nginx","-v"]The command and its arguments.
cwd
optional
/usr/share/nginx/htmlThe working directory to run the command in.
output_encoding
optional
utf-8How stdout and stderr are returned. utf-8 (the default) is a JSON string; bytes that are not valid UTF-8 become U+FFFD. base64 returns the exact bytes. Use base64 when the command may emit binary output.
Request: /v2/microvms/{microvm_id}/exec
{
"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.
exit_code for the command's result.ratelimit-limit
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
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
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.
application/json
exit_code
optional
0The command's exit code.
output_encoding
optional
utf-8The encoding of stdout and stderr, echoing the request's output_encoding (or the utf-8 default).
stderr
optional
The command's standard error. A UTF-8 string when output_encoding is utf-8; standard Base64 when it is base64.
stdout
optional
The command's standard output. A UTF-8 string when output_encoding is utf-8; standard Base64 when it is base64.
truncated
optional
falsePresent 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
404
The MicroVM or checkpoint does not exist, or it belongs to another team.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
429
The API rate limit has been exceeded.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
default
There was an unexpected error.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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": ""
}{
"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)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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
required
01a0ef1a-d873-793d-ae6a-5dd6239be62aThe unique ID of the MicroVM.
Query Parameters
rows
1 – 65535 optional
24The initial number of terminal rows.
Default:24cols
1 – 65535 optional
80The initial number of terminal columns.
Default:80Request: /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.
{"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.ratelimit-limit
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
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
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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
404
The MicroVM or checkpoint does not exist, or it belongs to another team.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
429
The API rate limit has been exceeded.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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"
}GET Download a file from a MicroVM
/v2/microvms/{microvm_id}/files
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 read a file from a MicroVM's workload container, send a GET request to
/v2/microvms/{microvm_id}/files?path=<absolute path>.
The response body is the raw file content with a Content-Type of
application/octet-stream. The Content-Length and X-Checksum-Sha256 headers describe the
file as it was when the transfer began. Only regular files of up to 64 MiB can be downloaded.
A MicroVM serves up to 4 downloads at a time.
Your team needs the file_transfer feature. Check GET /v2/microvms/options. If the MicroVM
is paused and auto-resume is on, the request resumes it.
Path Parameters
microvm_id
required
01a0ef1a-d873-793d-ae6a-5dd6239be62aThe unique ID of the MicroVM.
Query Parameters
path
required
/app/config.jsonThe absolute path of the file inside the workload container.
Request: /v2/microvms/{microvm_id}/files
curl -X GET \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
-o output.log \
"https://api.digitalocean.com/v2/microvms/01a0ef1a-d873-793d-ae6a-5dd6239be62a/files?path=/app/output.log"Responses
200
The raw file content. Content-Length and X-Checksum-Sha256 describe the file as it was when the transfer began.
Content-Length and X-Checksum-Sha256 describe the file as it was when the transfer began.X-Checksum-Sha256
The lowercase hex SHA-256 of the file content.
ratelimit-limit
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
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
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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
404
The MicroVM or checkpoint does not exist, or it belongs to another team.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
409
The file operation is not possible in the MicroVM's current state. WORKLOAD_NOT_RUNNING: the workload container is not running. NOT_A_REGULAR_FILE: the path is a directory, device, socket, or symlink. AGENT_UNSUPPORTED: the MicroVM runs an image that predates file transfer; recreate it.
WORKLOAD_NOT_RUNNING: the workload container is not running. NOT_A_REGULAR_FILE: the path is a directory, device, socket, or symlink. AGENT_UNSUPPORTED: the MicroVM runs an image that predates file transfer; recreate it.ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
413
The file exceeds 64 MiB, or the guest disk is full.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
429
The API rate limit has been exceeded.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
504
The transfer did not finish within 10 minutes. On upload the target file is unchanged. On download, if the body had already started, the stream ends short of Content-Length instead.
Content-Length instead.ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
default
There was an unexpected error.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"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"
}{
"code": "AGENT_UNSUPPORTED",
"message": "this MicroVM does not support file transfer; recreate it to pick up the new agent"
}{
"code": "PAYLOAD_TOO_LARGE",
"message": "file exceeds the 67108864 byte limit"
}{
"id": "too_many_requests",
"message": "API rate limit exceeded."
}{
"id": "server_error",
"message": "Unexpected server-side error"
}{
"code": "UNAVAILABLE",
"message": "workload unavailable"
}{
"code": "FILE_TIMEOUT",
"message": "file transfer timed out"
}{
"id": "example_error",
"message": "some error message"
}PUT Upload a file to a MicroVM
/v2/microvms/{microvm_id}/files
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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 write a file into a MicroVM's workload container, send a PUT request to
/v2/microvms/{microvm_id}/files?path=<absolute path> with the raw file content as the
request body and a Content-Type of application/octet-stream.
The file replaces any existing regular file at path atomically. The parent directory
must already exist. The request must carry a Content-Length header; chunked bodies are
rejected. A body of up to 64 MiB is accepted, and a Content-Length of 0 writes an empty
file. Pass sha256 to have the API verify the content before it replaces the target.
Your team needs the file_transfer feature. Check GET /v2/microvms/options. If the MicroVM
is paused and auto-resume is on, the request resumes it.
Path Parameters
microvm_id
required
01a0ef1a-d873-793d-ae6a-5dd6239be62aThe unique ID of the MicroVM.
Query Parameters
path
required
/app/config.jsonThe absolute path of the file inside the workload container.
mode
optional
0600The octal permission bits for the file, from 0001 to 0777. Defaults to 0644. Setuid, setgid, sticky bits, and 0000 are rejected.
uid
optional
1000The owner user ID. Set it together with gid. Defaults to the workload container's user.
gid
optional
1000The owner group ID. Set it together with uid. Defaults to the workload container's group.
sha256
optional
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855The lowercase hex SHA-256 of the request body. When set, the API verifies the content before it replaces the target. A mismatch returns 422 and leaves the existing file unchanged.
Request Body: application/octet-stream
The raw file content.
Request: /v2/microvms/{microvm_id}/files
"string"curl -X PUT \
-H "Content-Type: application/octet-stream" \
-H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
--data-binary @config.json \
"https://api.digitalocean.com/v2/microvms/01a0ef1a-d873-793d-ae6a-5dd6239be62a/files?path=/app/config.json&mode=0600"Responses
200
The file was written. The X-Checksum-Sha256 header repeats the digest from the body.
X-Checksum-Sha256 header repeats the digest from the body.X-Checksum-Sha256
The lowercase hex SHA-256 of the file content.
ratelimit-limit
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
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
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.
application/json
gid
optional
0The owner group ID.
mode
optional
0644The octal permission bits as written.
path
required
/app/config.jsonThe absolute path inside the workload container.
sha256
required
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855The lowercase hex SHA-256 of the content.
size_bytes
required
1024The file size in bytes.
uid
optional
0The owner user ID.
400
The request was malformed, failed validation, or is not allowed in the resource's current state.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
404
The MicroVM or checkpoint does not exist, or it belongs to another team.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
409
The file operation is not possible in the MicroVM's current state. WORKLOAD_NOT_RUNNING: the workload container is not running. NOT_A_REGULAR_FILE: the path is a directory, device, socket, or symlink. AGENT_UNSUPPORTED: the MicroVM runs an image that predates file transfer; recreate it.
WORKLOAD_NOT_RUNNING: the workload container is not running. NOT_A_REGULAR_FILE: the path is a directory, device, socket, or symlink. AGENT_UNSUPPORTED: the MicroVM runs an image that predates file transfer; recreate it.ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
411
The request has no Content-Length header.
Content-Length header.ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
413
The file exceeds 64 MiB, or the guest disk is full.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
422
The request body does not match the sha256 query parameter. The target file is unchanged.
sha256 query parameter. The target file is unchanged.ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
429
The API rate limit has been exceeded.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
504
The transfer did not finish within 10 minutes. On upload the target file is unchanged. On download, if the body had already started, the stream ends short of Content-Length instead.
Content-Length instead.ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
default
There was an unexpected error.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Response
{
"gid": 0,
"mode": "0600",
"path": "/app/config.json",
"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"size_bytes": 1024,
"uid": 0
}{
"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"
}{
"code": "AGENT_UNSUPPORTED",
"message": "this MicroVM does not support file transfer; recreate it to pick up the new agent"
}{
"code": "LENGTH_REQUIRED",
"message": "Content-Length is required"
}{
"code": "PAYLOAD_TOO_LARGE",
"message": "file exceeds the 67108864 byte limit"
}{
"code": "CHECKSUM_MISMATCH",
"message": "sha256 mismatch: expected e3b0c442…, got 9f86d081…"
}{
"id": "too_many_requests",
"message": "API rate limit exceeded."
}{
"id": "server_error",
"message": "Unexpected server-side error"
}{
"code": "UNAVAILABLE",
"message": "workload unavailable"
}{
"code": "FILE_TIMEOUT",
"message": "file transfer timed out"
}{
"id": "example_error",
"message": "some error message"
}POST Create a checkpoint of a MicroVM
/v2/microvms/{microvm_id}/checkpoints
Authorizations:
bearer_auth
(1 scope)
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 paneldoo_v1_for tokens generated by applications using the OAuth flowdor_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
required
01a0ef1a-d873-793d-ae6a-5dd6239be62aThe unique ID of the MicroVM.
Request Body: application/json
name
optional
example-checkpointA name for the checkpoint. If you omit it, a name such as checkpoint-20260929-143559 is generated.
Request: /v2/microvms/{microvm_id}/checkpoints
{
"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.
checkpoint. The value will be an object containing the standard attributes associated with a checkpoint.ratelimit-limit
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
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
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.
application/json
checkpoint
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
optional read-only
2026-09-29T14:35:59ZWhen the checkpoint was created, in ISO 8601 format.
disk_bytes
optional read-only
1073741824The stored size of the checkpoint's disk, in bytes.
egress_policy
optional
An outbound allow list. A destination that matches any rule is allowed; default_action decides every other destination. Only valid with public networking, and fixed at create: there is no way to change it later. With a policy set, direct connections out of the MicroVM are dropped; only HTTP and HTTPS through the platform proxy to the allowed destinations works, so clients must honor the injected HTTP_PROXY / HTTPS_PROXY environment. The registries needed to pull the workload image are allowed automatically. On a MicroVM this is the policy set at create, as supplied, except that credential secrets are never returned. On a checkpoint it is the policy a restored MicroVM inherits; a restore cannot change it. Omitted when egress is unrestricted.
Show child properties
credentials
optional
Credentials the platform adds to outbound requests, so the workload never holds them. Settable only at create, and only in regions that support credential injection. Each host must be allowed by a rule (or default_action must be allow). HTTPS requests to these hosts are intercepted so the credential can be attached; clients that pin certificates will fail on them. The credential is sent in the authorization header. Credentials cannot be set when restoring a checkpoint: the restored MicroVM inherits the origin's. Responses include host, path_prefix, and scheme for each credential. The secret is never returned.
Show child properties
host
required
api.example.comAn exact host. Wildcards and IP addresses are not allowed.
path_prefix
optional
/v1Only requests whose path starts with this prefix get the credential. Must start with /. Defaults to every path.
scheme
optional
bearerHow the value is sent. bearer sends Bearer <secret>; raw sends the secret as is.
secret
required write-only
s3cr3t-t0k3nThe credential value. It is stored in a secrets vault, never returned by the API, and cannot be read back.
default_action
optional
denyWhat to do with a destination no rule matches. deny refuses it (an HTTP request gets a 403 and a TLS connection is closed).
rules
optional
The destinations to allow. Rules match the host only: port, path, and method are not considered, and a hostname that resolves to an IP is not matched by an ip rule. Each rule sets exactly one of domain or ip.
Show child properties
domain
optional
api.example.comAn exact host such as api.example.com, or a wildcard such as *.example.com.
ip
optional
203.0.113.5An exact IP address. CIDR ranges are not supported.
failure_reason
optional read-only
another checkpoint of this MicroVM is in progress; retry shortlyWhy the checkpoint failed. Present only when status is CHECKPOINT_FAILED.
id
optional read-only
01a0ed98-0a74-75dd-a625-e4856adbc298The unique ID of the checkpoint.
memory_bytes
optional read-only
2147483648The stored size of the checkpoint's memory, in bytes.
microvm_id
optional read-only
01a0ed71-4efb-718f-9598-ca9cba942595The ID of the MicroVM the checkpoint was taken from.
microvm_name
optional read-only
example-microvmThe name of the MicroVM the checkpoint was taken from.
name
optional
checkpoint-20260929-143559The name of the checkpoint. If you do not set one, a name such as checkpoint-20260929-143559 is generated.
region
optional read-only
mkc1The slug of the checkpoint's region.
size
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
required
1The number of vCPUs.
disk
optional read-only
50The size of the disk, in GB. Set by the size.
memory
required
2048The amount of memory, in MiB.
status
optional read-only
CHECKPOINT_AVAILABLEThe 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
401
Authentication failed due to invalid credentials.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
code
required
NOT_FOUNDA service-defined error code.
message
required
MicroVM not foundA human-readable description of the error.
429
The API rate limit has been exceeded.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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.
ratelimit-limit
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
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
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.
application/json
id
required
not_foundA 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
required
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
optional
4d9d8375-3c56-4925-a3e7-eb137fed17e9Optionally, 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"
}
}{
"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"
}