---
title: MicroVMs API and doctl Reference (public)
description: Fields of the MicroVM and checkpoint objects, the MicroVMs API endpoints, and the doctl commands for MicroVMs.
product: Microvms
url: https://docs.digitalocean.com/products/microvms/reference/endpoints-and-commands/
last_updated: "2026-10-09"
---

> **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](https://docs.digitalocean.com/llms.txt). Markdown versions of pages use the same URL with `index.html.md` in place of the HTML page (for example, append `index.html.md` to the directory path instead of opening the HTML document).

# MicroVMs API and doctl Reference (public)

DigitalOcean MicroVMs are lightweight virtual machines that run a container image in an isolated kernel, pause automatically when idle, and resume on the next request with memory, files, and processes intact.

DigitalOcean MicroVMs are managed through the `/v2/microvms` API endpoints and the `doctl compute microvm` commands. This page lists the fields of the MicroVM and checkpoint objects, each endpoint, and each `doctl` command with its flags.

## API Conventions

The base path is `https://api.digitalocean.com/v2/microvms`. Responses wrap objects in `microvm`, `microvms`, `checkpoint`, or `checkpoints`.

List endpoints take `page` and `per_page` query parameters. The default page size is 25, and the maximum is 200. List responses include the standard `links` and `meta` pagination objects. Any request can return HTTP 429 when you exceed rate limits.

Errors return a JSON object with a `code`, such as `NOT_FOUND`, and a human-readable `message`.

## MicroVM Object

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

| Field | Type | Description |
|---|---|---|
| `id` | string | Unique ID. Read-only. |
| `name` | string | Required on create. Unique in the region. 1 to 63 lowercase letters, digits, and hyphens. |
| `region` | string | Required when `source.oci_ref` is set. When creating from a checkpoint, omit it to use the checkpoint’s region. |
| `size` | object | `cpu` is the number of vCPUs, and `memory` is in MiB. Required with `oci_ref`. Must be one of the pairs `1`/`2048`, `2`/`4096`, `8`/`16384`, or `16`/`32768`. Responses also include `disk`, in GB. When creating from a checkpoint, a different size is rejected. |
| `source` | object | Required on create. Contains either `oci_ref` (string), a container image reference, or `checkpoint_id` (string). |
| `state` | string | Read-only. One of the states in [MicroVM Lifecycle](https://docs.digitalocean.com/products/microvms/concepts/lifecycle/index.html.md#microvm-states). |
| `failure_reason` | string | Read-only. Why the MicroVM failed. Present only when `state` is `failed`. |
| `networking` | string | `public` (default) or `vpc`. |
| `vpc_uuid` | string | Required when `networking` is `vpc`. |
| `auto_pause` | object | `idle_timeout` is a duration such as `30s`, `5m`, or `1h`, with a default of `5m` and a maximum of `4h`. Responses show the duration in the form `5m0s`, and `enabled` is always `true`. Sending `enabled` set to `false` is rejected. |
| `auto_resume` | boolean | Whether incoming traffic resumes a paused MicroVM. Defaults to `true`. |
| `http_port` | integer | Create only. The port the workload serves HTTP on. Defaults to `8080`. Not returned in responses. The `urls` entry with `default` set to `true` shows the HTTP port. |
| `http_protocol` | string | `http` or `http2`. |
| `ports` | array of integers | Up to five ports, including `http_port`. Defaults to the HTTP port. Only the HTTP port is reachable through the endpoint during the public preview. |
| `environment` | object | Create only. Key and value pairs passed into the MicroVM at boot. Not returned in responses. |
| `tags` | array of strings | Tags to apply. |
| `urls` | array of objects | Read-only. The MicroVM’s endpoints. Each entry has `hostname`, `port`, `default`, and `status`. `hostname` is empty and `status` is `PENDING` until provisioning finishes, then `status` is `ACTIVE`. |
| `created_at` | string | Read-only. When the MicroVM was created, in ISO 8601 format. |

## Checkpoint Object

| Field | Type | Description |
|---|---|---|
| `id` | string | Unique ID. |
| `name` | string | The name you gave the checkpoint, or a generated name such as `checkpoint-20260929-143559`. |
| `microvm_id` | string | The ID of the MicroVM the checkpoint was taken from. |
| `microvm_name` | string | The name of the MicroVM the checkpoint was taken from. |
| `region` | string | The checkpoint’s region. |
| `size` | object | The size the checkpoint was taken at, with `cpu`, `memory` in MiB, and `disk` in GB. A MicroVM created from the checkpoint uses this size. |
| `status` | string | One of the statuses in [MicroVM Checkpoints](https://docs.digitalocean.com/products/microvms/concepts/checkpoints/index.html.md#checkpoint-statuses). |
| `memory_bytes` | integer | Stored size of the checkpoint’s memory. |
| `disk_bytes` | integer | Stored size of the checkpoint’s disk. |
| `created_at` | string | When the checkpoint was created, in ISO 8601 format. |

## Options Object

`GET /v2/microvms/options` returns the following fields:

| Field | Type | Description |
|---|---|---|
| `default_region` | string | The region MicroVMs are created in by default, such as `mkc1`. |
| `sizes` | array of objects | The sizes available to your team. Each entry has `cpu`, `memory` in MiB, `disk` in GB, `regions`, `available`, and `pricing` with `price_per_hour` and `price_per_month`. |
| `resource_pricing` | object | Per-resource rates: `price_per_vcpu_hour`, `price_per_gib_memory_hour`, `price_per_gib_storage_month`, and `price_per_gib_bandwidth`. |
| `account_limits` | object | Your team’s limits: `max_total_count` (MicroVMs, running and paused), `max_memory_bytes`, `max_disk_bytes`, and `max_idle_timeout_seconds`. |
| `features` | array of objects | Features enabled for your team. Each entry has `name` and `enabled`. |

## API Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/v2/microvms` | List MicroVMs. The `region`, `name` (exact match), and `tag_name` filters combine with AND. |
| `POST` | `/v2/microvms` | Create a MicroVM. Returns HTTP 201. |
| `GET` | `/v2/microvms/<your-microvm-id>` | Get a MicroVM. |
| `DELETE` | `/v2/microvms/<your-microvm-id>` | Delete a MicroVM. Returns HTTP 204. |
| `POST` | `/v2/microvms/<your-microvm-id>/pause` | Pause a MicroVM. |
| `POST` | `/v2/microvms/<your-microvm-id>/resume` | Resume a MicroVM. |
| `POST` | `/v2/microvms/<your-microvm-id>/exec` | Run a command. Body contains `argv` and an optional `cwd`. |
| `GET` | `/v2/microvms/<your-microvm-id>/console` | Open a WebSocket console. Query parameters `rows` and `cols`. |
| `POST` | `/v2/microvms/<your-microvm-id>/checkpoints` | Start a checkpoint. Optional body `name`. |
| `GET` | `/v2/microvms/checkpoints` | List checkpoints, newest first. Filter with `microvm_id`. |
| `GET` | `/v2/microvms/checkpoints/<your-checkpoint-id>` | Get a checkpoint. |
| `DELETE` | `/v2/microvms/checkpoints/<your-checkpoint-id>` | Delete a checkpoint. Returns HTTP 400 while the checkpoint is still being captured. |
| `GET` | `/v2/microvms/options` | Get the default region, sizes, and account limits available to your team. |

## doctl Commands

The following commands are under `doctl compute microvm` in `doctl` v1.173.0 and later. Command aliases are in parentheses.

| Command | Description |
|---|---|
| `list` (`ls`) | List MicroVMs. |
| `get <id>` (`g`) | Show a MicroVM, including its state and endpoint. |
| `create <name>` (`c`) | Create a MicroVM. |
| `pause <id>` | Pause a running MicroVM. |
| `resume <id>` | Resume a paused MicroVM. |
| `delete <id>...` (`d`, `rm`) | Delete one or more MicroVMs. Prompts for confirmation unless you pass `--force` (`-f`). |
| `options` | List the sizes, default region, and account limits available to your team. |
| `exec <id> -- <command>` | Run a command in the MicroVM and print its output. If the command exits non-zero, `doctl` also exits non-zero. `--cwd` sets the working directory. |
| `console <id>` | Open an interactive terminal in the MicroVM. |
| `checkpoint list` (`ls`) | List checkpoints, newest first. `--microvm-id` filters to one MicroVM’s checkpoints. |
| `checkpoint get <id>` (`g`) | Show a checkpoint, including its status. |
| `checkpoint create <microvm-id>` (`c`) | Start a checkpoint of a MicroVM. `--name` sets an optional name. |
| `checkpoint delete <id>...` (`d`, `rm`) | Delete one or more checkpoints. Prompts for confirmation unless you pass `--force` (`-f`). |

The `checkpoint` command also has the aliases `checkpoints` and `cp`.

### Flags for `doctl compute microvm list`

The `list` filters combine with AND:

- `--region`: Only MicroVMs in this region, such as `mkc1`.
- `--name`: Only the MicroVM with this exact name.
- `--tag-name`: Only MicroVMs with this tag. A tag that matches nothing returns an empty list.

### Flags for `doctl compute microvm create`

Set exactly one source:

- `--oci-ref`: The container image to run, such as `docker.io/library/nginx:latest`.
- `--checkpoint-id`: The ID of a checkpoint to create the MicroVM from.

The following flags are required with `--oci-ref`, and inherited from the checkpoint with `--checkpoint-id`:

- `--region`: The region to create the MicroVM in, such as `mkc1`.
- `--cpu`: The number of vCPUs.
- `--memory`: The memory in MiB. Must match `--cpu` as listed in [Sizes](https://docs.digitalocean.com/products/microvms/details/limits/index.html.md#sizes).

The following flags are optional:

- `--networking`: `public` (default) or `vpc`.
- `--vpc-uuid`: The ID of the VPC network to place the MicroVM in. Only valid with `--networking vpc`.
- `--auto-pause-idle-timeout`: How long the MicroVM is idle before it pauses, such as `30s`, `5m`, or `1h`. Defaults to `5m`, with a maximum of `4h`.
- `--auto-resume`: Whether incoming traffic resumes a paused MicroVM. Defaults to `true`. Pass `--auto-resume=false` to require a manual resume.
- `--http-port`: The port your workload serves HTTP on. Defaults to `8080`.
- `--http-protocol`: `http` or `http2`.
- `--ports`: A guest port to declare, up to five. Repeatable. Must include the HTTP port. Defaults to only the HTTP port. Only the HTTP port is reachable during the public preview.
- `--env`: An environment variable in `KEY=VALUE` form. Repeatable.
- `--tag`: A tag to apply. Repeatable.