DigitalOcean API (unofficial showcase)
POST/v2/microvms

Create a MicroVM

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.

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

13 body fields
namestringrequired
The name of the MicroVM. Must be unique in the region and contain 1 to 63 lowercase letters, digits, and hyphens.
sourceobjectrequired
What the MicroVM runs. Set exactly one of `oci_ref` or `checkpoint_id`.
regionstringoptional
The slug of the region to create the MicroVM in. Required with `source.oci_ref`.
sizeobjectoptional
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.
networkingstringoptional
`public` sends outbound traffic through a shared NAT gateway. `vpc` places the MicroVM in the VPC network set by `vpc_uuid`.
Allowed:publicvpcDefault:public
vpc_uuidstringoptional
The ID of a VPC network in the same region that belongs to your team. Required when `networking` is `vpc`.
auto_pauseobjectoptional
Automatic pause settings. A MicroVM always pauses after it is idle for `idle_timeout`. Sending `enabled` set to `false` is rejected.
auto_resumebooleanoptional
Whether an HTTP request, command, or console session resumes the MicroVM when it is paused. Set to `false` to require a manual resume.
Default:true
http_portintegeroptional
The guest port the workload serves HTTP on. Defaults to `8080`. Not returned in responses. When creating from a checkpoint without `ports`, must be one of the checkpoint's ports.
Default:8080
http_protocolstringoptional
The protocol the HTTP port serves.
Allowed:httphttp2
portsarray<integer>optional
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.
environmentobjectoptional
Environment variables passed into the MicroVM at boot, as key and value pairs. Not returned in responses.
tagsarray<string>optional
Tags to apply to the MicroVM.

7 status codes
201The 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`.
microvmobjectoptional
A MicroVM. All fields are set at creation. There is no update endpoint.
400The request was malformed, failed validation, or is not allowed in the resource's current state.

3 documented failures

  • INVALID_SIZE

    no supported size matches the requested resources: 3 vCPU with 2048 MiB of memory (supported: 1vCPU/2048MiB, 2vCPU/4096MiB, 8vCPU/16384MiB, 16vCPU/32768MiB)

  • INVALID_AUTO_PAUSE

    auto_pause.enabled cannot be false; omit it to keep the 5 minute default, or set idle_timeout up to the account maximum

  • FAILED_PRECONDITION

    checkpoint 01a11cd5-25dd-790f-a77c-3677f24bca85 is still being captured; retry delete once the capture completes

codestringrequired
A service-defined error code.
messagestringrequired
A human-readable description of the error.
401Authentication failed due to invalid credentials.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
403The token does not have the required scope, or your team has reached a limit.

One documented failure

  • PERMISSION_DENIED

    permission denied

codestringrequired
A service-defined error code.
messagestringrequired
A human-readable description of the error.
429The API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500There was a server error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 400 is returned: The request was malformed, failed validation, or is not allowed in the resource's current state. A 401 is returned: Authentication failed due to invalid credentials. A 403 is returned: The token does not have the required scope, or your team has reached a limit. A 429 is returned: The API rate limit has been exceeded. A 500 is returned: There was a server error. Any other status is an error: There was an unexpected error.