From d91541807b2da29d8251e93a1137cf9a655b9b4d Mon Sep 17 00:00:00 2001 From: Brian Boucheron Date: Thu, 8 Oct 2026 11:45:48 -0400 Subject: [PATCH 1/4] PDOCS-4764: add MicroVMs public preview API --- specification/DigitalOcean-public.v2.yaml | 65 +++++++++ .../curl/microvms_checkpoints_create.yml | 7 + .../curl/microvms_checkpoints_delete.yml | 6 + .../curl/microvms_checkpoints_get.yml | 6 + .../curl/microvms_checkpoints_list.yml | 6 + .../examples/curl/microvms_console.yml | 5 + .../examples/curl/microvms_create.yml | 7 + .../examples/curl/microvms_delete.yml | 6 + .../microvms/examples/curl/microvms_exec.yml | 7 + .../microvms/examples/curl/microvms_get.yml | 6 + .../microvms/examples/curl/microvms_list.yml | 6 + .../examples/curl/microvms_options.yml | 6 + .../microvms/examples/curl/microvms_pause.yml | 6 + .../examples/curl/microvms_resume.yml | 6 + .../microvms/microvms_checkpoints_create.yml | 65 +++++++++ .../microvms/microvms_checkpoints_delete.yml | 45 +++++++ .../microvms/microvms_checkpoints_get.yml | 39 ++++++ .../microvms/microvms_checkpoints_list.yml | 39 ++++++ .../resources/microvms/microvms_console.yml | 49 +++++++ .../resources/microvms/microvms_create.yml | 94 +++++++++++++ .../resources/microvms/microvms_delete.yml | 41 ++++++ .../resources/microvms/microvms_exec.yml | 76 +++++++++++ .../resources/microvms/microvms_get.yml | 41 ++++++ .../resources/microvms/microvms_list.yml | 41 ++++++ .../resources/microvms/microvms_options.yml | 33 +++++ .../resources/microvms/microvms_pause.yml | 46 +++++++ .../resources/microvms/microvms_resume.yml | 45 +++++++ .../resources/microvms/models/checkpoint.yml | 77 +++++++++++ .../resources/microvms/models/exec.yml | 59 +++++++++ .../resources/microvms/models/microvm.yml | 124 ++++++++++++++++++ .../microvms/models/microvm_auto_pause.yml | 19 +++ .../microvms/models/microvm_create.yml | 109 +++++++++++++++ .../microvms/models/microvm_error.yml | 18 +++ .../microvms/models/microvm_options.yml | 116 ++++++++++++++++ .../microvms/models/microvm_size.yml | 27 ++++ .../microvms/models/microvm_source.yml | 22 ++++ .../resources/microvms/models/microvm_url.yml | 31 +++++ .../resources/microvms/parameters.yml | 94 +++++++++++++ .../microvms/responses/all_checkpoints.yml | 47 +++++++ .../microvms/responses/all_microvms.yml | 63 +++++++++ .../microvms/responses/checkpoint.yml | 38 ++++++ .../microvms/responses/console_upgrade.yml | 20 +++ .../resources/microvms/responses/errors.yml | 79 +++++++++++ .../resources/microvms/responses/exec.yml | 23 ++++ .../resources/microvms/responses/microvm.yml | 51 +++++++ .../microvms/responses/microvm_created.yml | 52 ++++++++ .../microvms/responses/microvm_options.yml | 73 +++++++++++ 47 files changed, 1941 insertions(+) create mode 100644 specification/resources/microvms/examples/curl/microvms_checkpoints_create.yml create mode 100644 specification/resources/microvms/examples/curl/microvms_checkpoints_delete.yml create mode 100644 specification/resources/microvms/examples/curl/microvms_checkpoints_get.yml create mode 100644 specification/resources/microvms/examples/curl/microvms_checkpoints_list.yml create mode 100644 specification/resources/microvms/examples/curl/microvms_console.yml create mode 100644 specification/resources/microvms/examples/curl/microvms_create.yml create mode 100644 specification/resources/microvms/examples/curl/microvms_delete.yml create mode 100644 specification/resources/microvms/examples/curl/microvms_exec.yml create mode 100644 specification/resources/microvms/examples/curl/microvms_get.yml create mode 100644 specification/resources/microvms/examples/curl/microvms_list.yml create mode 100644 specification/resources/microvms/examples/curl/microvms_options.yml create mode 100644 specification/resources/microvms/examples/curl/microvms_pause.yml create mode 100644 specification/resources/microvms/examples/curl/microvms_resume.yml create mode 100644 specification/resources/microvms/microvms_checkpoints_create.yml create mode 100644 specification/resources/microvms/microvms_checkpoints_delete.yml create mode 100644 specification/resources/microvms/microvms_checkpoints_get.yml create mode 100644 specification/resources/microvms/microvms_checkpoints_list.yml create mode 100644 specification/resources/microvms/microvms_console.yml create mode 100644 specification/resources/microvms/microvms_create.yml create mode 100644 specification/resources/microvms/microvms_delete.yml create mode 100644 specification/resources/microvms/microvms_exec.yml create mode 100644 specification/resources/microvms/microvms_get.yml create mode 100644 specification/resources/microvms/microvms_list.yml create mode 100644 specification/resources/microvms/microvms_options.yml create mode 100644 specification/resources/microvms/microvms_pause.yml create mode 100644 specification/resources/microvms/microvms_resume.yml create mode 100644 specification/resources/microvms/models/checkpoint.yml create mode 100644 specification/resources/microvms/models/exec.yml create mode 100644 specification/resources/microvms/models/microvm.yml create mode 100644 specification/resources/microvms/models/microvm_auto_pause.yml create mode 100644 specification/resources/microvms/models/microvm_create.yml create mode 100644 specification/resources/microvms/models/microvm_error.yml create mode 100644 specification/resources/microvms/models/microvm_options.yml create mode 100644 specification/resources/microvms/models/microvm_size.yml create mode 100644 specification/resources/microvms/models/microvm_source.yml create mode 100644 specification/resources/microvms/models/microvm_url.yml create mode 100644 specification/resources/microvms/parameters.yml create mode 100644 specification/resources/microvms/responses/all_checkpoints.yml create mode 100644 specification/resources/microvms/responses/all_microvms.yml create mode 100644 specification/resources/microvms/responses/checkpoint.yml create mode 100644 specification/resources/microvms/responses/console_upgrade.yml create mode 100644 specification/resources/microvms/responses/errors.yml create mode 100644 specification/resources/microvms/responses/exec.yml create mode 100644 specification/resources/microvms/responses/microvm.yml create mode 100644 specification/resources/microvms/responses/microvm_created.yml create mode 100644 specification/resources/microvms/responses/microvm_options.yml diff --git a/specification/DigitalOcean-public.v2.yaml b/specification/DigitalOcean-public.v2.yaml index a26d71aa6..19b91cc56 100644 --- a/specification/DigitalOcean-public.v2.yaml +++ b/specification/DigitalOcean-public.v2.yaml @@ -435,6 +435,21 @@ tags: delete load balancers as well as add or remove Droplets, forwarding rules, and other configuration details. + - name: MicroVMs [Public Preview] + description: |- + [DigitalOcean MicroVMs](https://docs.digitalocean.com/products/microvms/) + are lightweight virtual machines that run a `linux/amd64` container image + in an isolated kernel. A MicroVM pauses automatically when it is idle and + resumes on the next HTTP request, command, or console session, with its + memory, files, and processes intact. By sending requests to the + `/v2/microvms` endpoints, you can create, list, pause, resume, and delete + MicroVMs, run commands and open a console in them, and create checkpoints + to start new MicroVMs from a saved state. + + Each MicroVM serves its HTTP port at + `https://{microvm_id}.{region}.microvm.ondigitalocean.com`. Requests to + that endpoint require a token with the `microvm:access` scope. + - name: Monitoring description: |- The DigitalOcean Monitoring API makes it possible to programmatically retrieve metrics as well as configure alert @@ -741,6 +756,7 @@ x-tagGroups: - Insights - Kubernetes - Load Balancers + - MicroVMs [Public Preview] - Monitoring - NFS - NFS Actions @@ -1965,6 +1981,55 @@ paths: delete: $ref: "resources/load_balancers/loadBalancers_remove_forwardingRules.yml" + /v2/microvms: + get: + $ref: "resources/microvms/microvms_list.yml" + + post: + $ref: "resources/microvms/microvms_create.yml" + + /v2/microvms/options: + get: + $ref: "resources/microvms/microvms_options.yml" + + /v2/microvms/checkpoints: + get: + $ref: "resources/microvms/microvms_checkpoints_list.yml" + + /v2/microvms/checkpoints/{checkpoint_id}: + get: + $ref: "resources/microvms/microvms_checkpoints_get.yml" + + delete: + $ref: "resources/microvms/microvms_checkpoints_delete.yml" + + /v2/microvms/{microvm_id}: + get: + $ref: "resources/microvms/microvms_get.yml" + + delete: + $ref: "resources/microvms/microvms_delete.yml" + + /v2/microvms/{microvm_id}/pause: + post: + $ref: "resources/microvms/microvms_pause.yml" + + /v2/microvms/{microvm_id}/resume: + post: + $ref: "resources/microvms/microvms_resume.yml" + + /v2/microvms/{microvm_id}/exec: + post: + $ref: "resources/microvms/microvms_exec.yml" + + /v2/microvms/{microvm_id}/console: + get: + $ref: "resources/microvms/microvms_console.yml" + + /v2/microvms/{microvm_id}/checkpoints: + post: + $ref: "resources/microvms/microvms_checkpoints_create.yml" + /v2/monitoring/alerts: get: $ref: "resources/monitoring/monitoring_list_alertPolicy.yml" diff --git a/specification/resources/microvms/examples/curl/microvms_checkpoints_create.yml b/specification/resources/microvms/examples/curl/microvms_checkpoints_create.yml new file mode 100644 index 000000000..2f94e29d4 --- /dev/null +++ b/specification/resources/microvms/examples/curl/microvms_checkpoints_create.yml @@ -0,0 +1,7 @@ +lang: cURL +source: |- + 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" diff --git a/specification/resources/microvms/examples/curl/microvms_checkpoints_delete.yml b/specification/resources/microvms/examples/curl/microvms_checkpoints_delete.yml new file mode 100644 index 000000000..16374c653 --- /dev/null +++ b/specification/resources/microvms/examples/curl/microvms_checkpoints_delete.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + 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" diff --git a/specification/resources/microvms/examples/curl/microvms_checkpoints_get.yml b/specification/resources/microvms/examples/curl/microvms_checkpoints_get.yml new file mode 100644 index 000000000..317560223 --- /dev/null +++ b/specification/resources/microvms/examples/curl/microvms_checkpoints_get.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + 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" diff --git a/specification/resources/microvms/examples/curl/microvms_checkpoints_list.yml b/specification/resources/microvms/examples/curl/microvms_checkpoints_list.yml new file mode 100644 index 000000000..7458f1615 --- /dev/null +++ b/specification/resources/microvms/examples/curl/microvms_checkpoints_list.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + 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" diff --git a/specification/resources/microvms/examples/curl/microvms_console.yml b/specification/resources/microvms/examples/curl/microvms_console.yml new file mode 100644 index 000000000..1a9a00855 --- /dev/null +++ b/specification/resources/microvms/examples/curl/microvms_console.yml @@ -0,0 +1,5 @@ +lang: WebSocket +source: |- + websocat -b \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "wss://api.digitalocean.com/v2/microvms/01a0ef1a-d873-793d-ae6a-5dd6239be62a/console?rows=24&cols=80" diff --git a/specification/resources/microvms/examples/curl/microvms_create.yml b/specification/resources/microvms/examples/curl/microvms_create.yml new file mode 100644 index 000000000..5a016a26a --- /dev/null +++ b/specification/resources/microvms/examples/curl/microvms_create.yml @@ -0,0 +1,7 @@ +lang: cURL +source: |- + 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" diff --git a/specification/resources/microvms/examples/curl/microvms_delete.yml b/specification/resources/microvms/examples/curl/microvms_delete.yml new file mode 100644 index 000000000..ecbaf65d0 --- /dev/null +++ b/specification/resources/microvms/examples/curl/microvms_delete.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + curl -X DELETE \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/microvms/01a0ef1a-d873-793d-ae6a-5dd6239be62a" diff --git a/specification/resources/microvms/examples/curl/microvms_exec.yml b/specification/resources/microvms/examples/curl/microvms_exec.yml new file mode 100644 index 000000000..3a2ac9f96 --- /dev/null +++ b/specification/resources/microvms/examples/curl/microvms_exec.yml @@ -0,0 +1,7 @@ +lang: cURL +source: |- + 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" diff --git a/specification/resources/microvms/examples/curl/microvms_get.yml b/specification/resources/microvms/examples/curl/microvms_get.yml new file mode 100644 index 000000000..3f50b7459 --- /dev/null +++ b/specification/resources/microvms/examples/curl/microvms_get.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/microvms/01a0ef1a-d873-793d-ae6a-5dd6239be62a" diff --git a/specification/resources/microvms/examples/curl/microvms_list.yml b/specification/resources/microvms/examples/curl/microvms_list.yml new file mode 100644 index 000000000..ac893ed8e --- /dev/null +++ b/specification/resources/microvms/examples/curl/microvms_list.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/microvms?region=mkc1&tag_name=example" diff --git a/specification/resources/microvms/examples/curl/microvms_options.yml b/specification/resources/microvms/examples/curl/microvms_options.yml new file mode 100644 index 000000000..d8195c858 --- /dev/null +++ b/specification/resources/microvms/examples/curl/microvms_options.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + curl -X GET \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \ + "https://api.digitalocean.com/v2/microvms/options" diff --git a/specification/resources/microvms/examples/curl/microvms_pause.yml b/specification/resources/microvms/examples/curl/microvms_pause.yml new file mode 100644 index 000000000..17746a6fc --- /dev/null +++ b/specification/resources/microvms/examples/curl/microvms_pause.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + 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" diff --git a/specification/resources/microvms/examples/curl/microvms_resume.yml b/specification/resources/microvms/examples/curl/microvms_resume.yml new file mode 100644 index 000000000..e430365c5 --- /dev/null +++ b/specification/resources/microvms/examples/curl/microvms_resume.yml @@ -0,0 +1,6 @@ +lang: cURL +source: |- + 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" diff --git a/specification/resources/microvms/microvms_checkpoints_create.yml b/specification/resources/microvms/microvms_checkpoints_create.yml new file mode 100644 index 000000000..fb8c38891 --- /dev/null +++ b/specification/resources/microvms/microvms_checkpoints_create.yml @@ -0,0 +1,65 @@ +operationId: microvmCheckpoints_create + +summary: Create a checkpoint of a MicroVM + +description: | + 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`. + +tags: + - MicroVMs [Public Preview] + +parameters: + - $ref: 'parameters.yml#/microvm_id' + +requestBody: + required: false + + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: >- + A name for the checkpoint. If you omit it, a name such as + `checkpoint-20260929-143559` is generated. + example: example-checkpoint + + examples: + Named Checkpoint: + value: + name: example-checkpoint + +responses: + '201': + $ref: 'responses/checkpoint.yml' + + '400': + $ref: 'responses/errors.yml#/bad_request' + + '401': + $ref: '../../shared/responses/unauthorized.yml' + + '404': + $ref: 'responses/errors.yml#/not_found' + + '429': + $ref: '../../shared/responses/too_many_requests.yml' + + '500': + $ref: '../../shared/responses/server_error.yml' + + default: + $ref: '../../shared/responses/unexpected_error.yml' + +x-codeSamples: + - $ref: 'examples/curl/microvms_checkpoints_create.yml' + +security: + - bearer_auth: + - 'microvm:create' diff --git a/specification/resources/microvms/microvms_checkpoints_delete.yml b/specification/resources/microvms/microvms_checkpoints_delete.yml new file mode 100644 index 000000000..553a8556c --- /dev/null +++ b/specification/resources/microvms/microvms_checkpoints_delete.yml @@ -0,0 +1,45 @@ +operationId: microvmCheckpoints_delete + +summary: Delete a checkpoint + +description: | + 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. + +tags: + - MicroVMs [Public Preview] + +parameters: + - $ref: 'parameters.yml#/checkpoint_id' + +responses: + '204': + $ref: '../../shared/responses/no_content.yml' + + '400': + $ref: 'responses/errors.yml#/bad_request' + + '401': + $ref: '../../shared/responses/unauthorized.yml' + + '404': + $ref: 'responses/errors.yml#/not_found' + + '429': + $ref: '../../shared/responses/too_many_requests.yml' + + '500': + $ref: '../../shared/responses/server_error.yml' + + default: + $ref: '../../shared/responses/unexpected_error.yml' + +x-codeSamples: + - $ref: 'examples/curl/microvms_checkpoints_delete.yml' + +security: + - bearer_auth: + - 'microvm:delete' diff --git a/specification/resources/microvms/microvms_checkpoints_get.yml b/specification/resources/microvms/microvms_checkpoints_get.yml new file mode 100644 index 000000000..e4e1ede02 --- /dev/null +++ b/specification/resources/microvms/microvms_checkpoints_get.yml @@ -0,0 +1,39 @@ +operationId: microvmCheckpoints_get + +summary: Retrieve a checkpoint + +description: | + To show information about a checkpoint, send a GET request to + `/v2/microvms/checkpoints/{checkpoint_id}`. + +tags: + - MicroVMs [Public Preview] + +parameters: + - $ref: 'parameters.yml#/checkpoint_id' + +responses: + '200': + $ref: 'responses/checkpoint.yml' + + '401': + $ref: '../../shared/responses/unauthorized.yml' + + '404': + $ref: 'responses/errors.yml#/not_found' + + '429': + $ref: '../../shared/responses/too_many_requests.yml' + + '500': + $ref: '../../shared/responses/server_error.yml' + + default: + $ref: '../../shared/responses/unexpected_error.yml' + +x-codeSamples: + - $ref: 'examples/curl/microvms_checkpoints_get.yml' + +security: + - bearer_auth: + - 'microvm:read' diff --git a/specification/resources/microvms/microvms_checkpoints_list.yml b/specification/resources/microvms/microvms_checkpoints_list.yml new file mode 100644 index 000000000..72a4d65a2 --- /dev/null +++ b/specification/resources/microvms/microvms_checkpoints_list.yml @@ -0,0 +1,39 @@ +operationId: microvmCheckpoints_list + +summary: List checkpoints + +description: | + 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. + +tags: + - MicroVMs [Public Preview] + +parameters: + - $ref: '../../shared/parameters.yml#/page' + - $ref: 'parameters.yml#/microvm_per_page' + - $ref: 'parameters.yml#/microvm_id_filter' + +responses: + '200': + $ref: 'responses/all_checkpoints.yml' + + '401': + $ref: '../../shared/responses/unauthorized.yml' + + '429': + $ref: '../../shared/responses/too_many_requests.yml' + + '500': + $ref: '../../shared/responses/server_error.yml' + + default: + $ref: '../../shared/responses/unexpected_error.yml' + +x-codeSamples: + - $ref: 'examples/curl/microvms_checkpoints_list.yml' + +security: + - bearer_auth: + - 'microvm:read' diff --git a/specification/resources/microvms/microvms_console.yml b/specification/resources/microvms/microvms_console.yml new file mode 100644 index 000000000..9fea521eb --- /dev/null +++ b/specification/resources/microvms/microvms_console.yml @@ -0,0 +1,49 @@ +operationId: microvms_get_console + +summary: Open a console in a MicroVM + +description: | + 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. + +tags: + - MicroVMs [Public Preview] + +parameters: + - $ref: 'parameters.yml#/microvm_id' + - $ref: 'parameters.yml#/console_rows' + - $ref: 'parameters.yml#/console_cols' + +responses: + '101': + $ref: 'responses/console_upgrade.yml' + + '401': + $ref: '../../shared/responses/unauthorized.yml' + + '403': + $ref: 'responses/errors.yml#/forbidden' + + '404': + $ref: 'responses/errors.yml#/not_found' + + '429': + $ref: '../../shared/responses/too_many_requests.yml' + + '500': + $ref: '../../shared/responses/server_error.yml' + + default: + $ref: '../../shared/responses/unexpected_error.yml' + +x-codeSamples: + - $ref: 'examples/curl/microvms_console.yml' + +security: + - bearer_auth: + - 'microvm:update' diff --git a/specification/resources/microvms/microvms_create.yml b/specification/resources/microvms/microvms_create.yml new file mode 100644 index 000000000..6e0508567 --- /dev/null +++ b/specification/resources/microvms/microvms_create.yml @@ -0,0 +1,94 @@ +operationId: microvms_create + +summary: Create a MicroVM + +description: | + 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. + +tags: + - MicroVMs [Public Preview] + +requestBody: + required: true + + content: + application/json: + schema: + $ref: 'models/microvm_create.yml' + + examples: + From a Container Image: + value: + 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 + + From a Checkpoint: + value: + name: example-from-checkpoint + source: + checkpoint_id: 01a0ed98-0a74-75dd-a625-e4856adbc298 + + In a VPC Network: + value: + name: example-vpc-microvm + region: mkc1 + size: + cpu: 2 + memory: 4096 + source: + oci_ref: docker.io/library/nginx:latest + http_port: 80 + networking: vpc + vpc_uuid: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 + environment: + APP_ENV: production + +responses: + '201': + $ref: 'responses/microvm_created.yml' + + '400': + $ref: 'responses/errors.yml#/bad_request' + + '401': + $ref: '../../shared/responses/unauthorized.yml' + + '403': + $ref: 'responses/errors.yml#/forbidden' + + '429': + $ref: '../../shared/responses/too_many_requests.yml' + + '500': + $ref: '../../shared/responses/server_error.yml' + + default: + $ref: '../../shared/responses/unexpected_error.yml' + +x-codeSamples: + - $ref: 'examples/curl/microvms_create.yml' + +security: + - bearer_auth: + - 'microvm:create' diff --git a/specification/resources/microvms/microvms_delete.yml b/specification/resources/microvms/microvms_delete.yml new file mode 100644 index 000000000..d706a874f --- /dev/null +++ b/specification/resources/microvms/microvms_delete.yml @@ -0,0 +1,41 @@ +operationId: microvms_delete + +summary: Delete a MicroVM + +description: | + 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. + +tags: + - MicroVMs [Public Preview] + +parameters: + - $ref: 'parameters.yml#/microvm_id' + +responses: + '204': + $ref: '../../shared/responses/no_content.yml' + + '401': + $ref: '../../shared/responses/unauthorized.yml' + + '404': + $ref: 'responses/errors.yml#/not_found' + + '429': + $ref: '../../shared/responses/too_many_requests.yml' + + '500': + $ref: '../../shared/responses/server_error.yml' + + default: + $ref: '../../shared/responses/unexpected_error.yml' + +x-codeSamples: + - $ref: 'examples/curl/microvms_delete.yml' + +security: + - bearer_auth: + - 'microvm:delete' diff --git a/specification/resources/microvms/microvms_exec.yml b/specification/resources/microvms/microvms_exec.yml new file mode 100644 index 000000000..d0c3d165d --- /dev/null +++ b/specification/resources/microvms/microvms_exec.yml @@ -0,0 +1,76 @@ +operationId: microvms_run_command + +summary: Run a command in a MicroVM + +description: | + 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. + +tags: + - MicroVMs [Public Preview] + +parameters: + - $ref: 'parameters.yml#/microvm_id' + +requestBody: + required: true + + content: + application/json: + schema: + $ref: 'models/exec.yml#/exec_request' + + examples: + Run a Command: + value: + argv: + - nginx + - -v + + Run a Shell Pipeline: + value: + argv: + - sh + - -c + - ls /usr/share/nginx/html | wc -l + +responses: + '200': + $ref: 'responses/exec.yml' + + '400': + $ref: 'responses/errors.yml#/bad_request' + + '401': + $ref: '../../shared/responses/unauthorized.yml' + + '403': + $ref: 'responses/errors.yml#/forbidden' + + '404': + $ref: 'responses/errors.yml#/not_found' + + '429': + $ref: '../../shared/responses/too_many_requests.yml' + + '500': + $ref: '../../shared/responses/server_error.yml' + + '502': + $ref: 'responses/errors.yml#/bad_gateway' + + default: + $ref: '../../shared/responses/unexpected_error.yml' + +x-codeSamples: + - $ref: 'examples/curl/microvms_exec.yml' + +security: + - bearer_auth: + - 'microvm:update' diff --git a/specification/resources/microvms/microvms_get.yml b/specification/resources/microvms/microvms_get.yml new file mode 100644 index 000000000..9fc0bb3a0 --- /dev/null +++ b/specification/resources/microvms/microvms_get.yml @@ -0,0 +1,41 @@ +operationId: microvms_get + +summary: Retrieve a MicroVM + +description: | + 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. + +tags: + - MicroVMs [Public Preview] + +parameters: + - $ref: 'parameters.yml#/microvm_id' + +responses: + '200': + $ref: 'responses/microvm.yml' + + '401': + $ref: '../../shared/responses/unauthorized.yml' + + '404': + $ref: 'responses/errors.yml#/not_found' + + '429': + $ref: '../../shared/responses/too_many_requests.yml' + + '500': + $ref: '../../shared/responses/server_error.yml' + + default: + $ref: '../../shared/responses/unexpected_error.yml' + +x-codeSamples: + - $ref: 'examples/curl/microvms_get.yml' + +security: + - bearer_auth: + - 'microvm:read' diff --git a/specification/resources/microvms/microvms_list.yml b/specification/resources/microvms/microvms_list.yml new file mode 100644 index 000000000..e7c47cc39 --- /dev/null +++ b/specification/resources/microvms/microvms_list.yml @@ -0,0 +1,41 @@ +operationId: microvms_list + +summary: List all MicroVMs + +description: | + 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. + +tags: + - MicroVMs [Public Preview] + +parameters: + - $ref: '../../shared/parameters.yml#/page' + - $ref: 'parameters.yml#/microvm_per_page' + - $ref: 'parameters.yml#/microvm_region' + - $ref: 'parameters.yml#/name' + - $ref: 'parameters.yml#/tag_name' + +responses: + '200': + $ref: 'responses/all_microvms.yml' + + '401': + $ref: '../../shared/responses/unauthorized.yml' + + '429': + $ref: '../../shared/responses/too_many_requests.yml' + + '500': + $ref: '../../shared/responses/server_error.yml' + + default: + $ref: '../../shared/responses/unexpected_error.yml' + +x-codeSamples: + - $ref: 'examples/curl/microvms_list.yml' + +security: + - bearer_auth: + - 'microvm:read' diff --git a/specification/resources/microvms/microvms_options.yml b/specification/resources/microvms/microvms_options.yml new file mode 100644 index 000000000..2d5f4025f --- /dev/null +++ b/specification/resources/microvms/microvms_options.yml @@ -0,0 +1,33 @@ +operationId: microvms_get_options + +summary: List MicroVM options + +description: | + To list the default region, sizes, prices, account limits, and features available to + your team, send a GET request to `/v2/microvms/options`. + +tags: + - MicroVMs [Public Preview] + +responses: + '200': + $ref: 'responses/microvm_options.yml' + + '401': + $ref: '../../shared/responses/unauthorized.yml' + + '429': + $ref: '../../shared/responses/too_many_requests.yml' + + '500': + $ref: '../../shared/responses/server_error.yml' + + default: + $ref: '../../shared/responses/unexpected_error.yml' + +x-codeSamples: + - $ref: 'examples/curl/microvms_options.yml' + +security: + - bearer_auth: + - 'microvm:read' diff --git a/specification/resources/microvms/microvms_pause.yml b/specification/resources/microvms/microvms_pause.yml new file mode 100644 index 000000000..beb632ab9 --- /dev/null +++ b/specification/resources/microvms/microvms_pause.yml @@ -0,0 +1,46 @@ +operationId: microvms_post_pause + +summary: Pause a MicroVM + +description: | + 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`. + +tags: + - MicroVMs [Public Preview] + +parameters: + - $ref: 'parameters.yml#/microvm_id' + +responses: + '200': + $ref: 'responses/microvm.yml' + + '400': + $ref: 'responses/errors.yml#/bad_request' + + '401': + $ref: '../../shared/responses/unauthorized.yml' + + '404': + $ref: 'responses/errors.yml#/not_found' + + '429': + $ref: '../../shared/responses/too_many_requests.yml' + + '500': + $ref: '../../shared/responses/server_error.yml' + + default: + $ref: '../../shared/responses/unexpected_error.yml' + +x-codeSamples: + - $ref: 'examples/curl/microvms_pause.yml' + +security: + - bearer_auth: + - 'microvm:update' diff --git a/specification/resources/microvms/microvms_resume.yml b/specification/resources/microvms/microvms_resume.yml new file mode 100644 index 000000000..d9744b1a4 --- /dev/null +++ b/specification/resources/microvms/microvms_resume.yml @@ -0,0 +1,45 @@ +operationId: microvms_post_resume + +summary: Resume a MicroVM + +description: | + 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`. + +tags: + - MicroVMs [Public Preview] + +parameters: + - $ref: 'parameters.yml#/microvm_id' + +responses: + '200': + $ref: 'responses/microvm.yml' + + '400': + $ref: 'responses/errors.yml#/bad_request' + + '401': + $ref: '../../shared/responses/unauthorized.yml' + + '404': + $ref: 'responses/errors.yml#/not_found' + + '429': + $ref: '../../shared/responses/too_many_requests.yml' + + '500': + $ref: '../../shared/responses/server_error.yml' + + default: + $ref: '../../shared/responses/unexpected_error.yml' + +x-codeSamples: + - $ref: 'examples/curl/microvms_resume.yml' + +security: + - bearer_auth: + - 'microvm:update' diff --git a/specification/resources/microvms/models/checkpoint.yml b/specification/resources/microvms/models/checkpoint.yml new file mode 100644 index 000000000..88803670e --- /dev/null +++ b/specification/resources/microvms/models/checkpoint.yml @@ -0,0 +1,77 @@ +type: object + +description: >- + A checkpoint of a MicroVM's memory and disk. New MicroVMs created from a + checkpoint start from that state. + +properties: + id: + type: string + format: uuid + readOnly: true + description: The unique ID of the checkpoint. + example: 01a0ed98-0a74-75dd-a625-e4856adbc298 + + name: + type: string + description: >- + The name of the checkpoint. If you do not set one, a name such as + `checkpoint-20260929-143559` is generated. + example: checkpoint-20260929-143559 + + microvm_id: + type: string + format: uuid + readOnly: true + description: The ID of the MicroVM the checkpoint was taken from. + example: 01a0ed71-4efb-718f-9598-ca9cba942595 + + microvm_name: + type: string + readOnly: true + description: The name of the MicroVM the checkpoint was taken from. + example: example-microvm + + region: + type: string + readOnly: true + description: The slug of the checkpoint's region. + example: mkc1 + + size: + $ref: 'microvm_size.yml' + + status: + type: string + readOnly: true + enum: + - CHECKPOINT_CREATING + - CHECKPOINT_AVAILABLE + - CHECKPOINT_FAILED + - CHECKPOINT_DELETING + - CHECKPOINT_DELETED + description: >- + The checkpoint's status. You can create MicroVMs from the checkpoint + when it is `CHECKPOINT_AVAILABLE`. + example: CHECKPOINT_AVAILABLE + + memory_bytes: + type: integer + format: int64 + readOnly: true + description: The stored size of the checkpoint's memory, in bytes. + example: 2147483648 + + disk_bytes: + type: integer + format: int64 + readOnly: true + description: The stored size of the checkpoint's disk, in bytes. + example: 1073741824 + + created_at: + type: string + format: date-time + readOnly: true + description: When the checkpoint was created, in ISO 8601 format. + example: "2026-09-29T14:35:59Z" diff --git a/specification/resources/microvms/models/exec.yml b/specification/resources/microvms/models/exec.yml new file mode 100644 index 000000000..ee56dc330 --- /dev/null +++ b/specification/resources/microvms/models/exec.yml @@ -0,0 +1,59 @@ +exec_request: + type: object + + description: >- + A command to run in the MicroVM's workload container. The command runs + directly, not through a shell. To use pipes, redirects, or environment + variables, run it with `sh -c`. The request body can be up to 1 MiB. + + properties: + argv: + type: array + minItems: 1 + items: + type: string + description: The command and its arguments. + example: + - nginx + - -v + + cwd: + type: string + description: The working directory to run the command in. + example: /usr/share/nginx/html + + required: + - argv + +exec_response: + type: object + + description: >- + The result of a command. The command has 60 seconds to finish. Combined + `stdout` and `stderr` are limited to 4 MiB. + + properties: + stdout: + type: string + description: >- + The command's standard output. Bytes that are not valid UTF-8 are + replaced. + example: "" + + stderr: + type: string + description: >- + The command's standard error. Bytes that are not valid UTF-8 are + replaced. + example: "nginx version: nginx/1.29.1\n" + + exit_code: + type: integer + description: The command's exit code. + example: 0 + + truncated: + type: boolean + description: >- + Present and `true` when the output exceeded 4 MiB and was cut off. + example: false diff --git a/specification/resources/microvms/models/microvm.yml b/specification/resources/microvms/models/microvm.yml new file mode 100644 index 000000000..bfd72f474 --- /dev/null +++ b/specification/resources/microvms/models/microvm.yml @@ -0,0 +1,124 @@ +type: object + +description: >- + A MicroVM. All fields are set at creation. There is no update endpoint. + +properties: + id: + type: string + format: uuid + readOnly: true + description: The unique ID of the MicroVM. + example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a + + name: + type: string + pattern: '^[a-z0-9-]{1,63}$' + description: >- + The name of the MicroVM. Must be unique in the region and contain 1 to 63 + lowercase letters, digits, and hyphens. + example: example-microvm + + region: + type: string + description: The slug of the region the MicroVM is in. + example: mkc1 + + size: + $ref: 'microvm_size.yml' + + source: + $ref: 'microvm_source.yml' + + state: + type: string + readOnly: true + enum: + - creating + - running + - pausing + - paused + - resuming + - terminating + - terminated + - failed + - unknown + description: The MicroVM's current state. + example: running + + failure_reason: + type: string + readOnly: true + description: Why the MicroVM failed. Present only when `state` is `failed`. + example: "workload container exited (code 0): exited with code 0" + + networking: + type: string + enum: + - public + - vpc + default: public + description: >- + `public` sends outbound traffic through a shared NAT gateway. `vpc` + places the MicroVM in the VPC network set by `vpc_uuid`. + example: public + + vpc_uuid: + type: string + format: uuid + description: >- + The ID of a VPC network in the same region that belongs to your team. + Present only when `networking` is `vpc`. + example: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 + + auto_pause: + $ref: 'microvm_auto_pause.yml' + + auto_resume: + type: boolean + default: true + description: >- + Whether an HTTP request, command, or console session resumes the + MicroVM when it is paused. + example: true + + http_protocol: + type: string + enum: + - http + - http2 + description: The protocol the MicroVM's HTTP port serves. + example: http + + ports: + type: array + maxItems: 5 + items: + type: integer + description: The guest ports open on the MicroVM, including the HTTP port. + example: + - 80 + + tags: + type: array + items: + type: string + description: The tags applied to the MicroVM. + example: + - example + + urls: + type: array + readOnly: true + items: + $ref: 'microvm_url.yml' + description: >- + The MicroVM's HTTPS endpoints. The entry with `default` set to `true` is + the endpoint for the HTTP port. + + created_at: + type: string + format: date-time + readOnly: true + description: When the MicroVM was created, in ISO 8601 format. + example: "2026-09-29T21:38:29Z" diff --git a/specification/resources/microvms/models/microvm_auto_pause.yml b/specification/resources/microvms/models/microvm_auto_pause.yml new file mode 100644 index 000000000..e880f1faf --- /dev/null +++ b/specification/resources/microvms/models/microvm_auto_pause.yml @@ -0,0 +1,19 @@ +type: object + +description: >- + Automatic pause settings. A MicroVM always pauses after it is idle for + `idle_timeout`. Sending `enabled` set to `false` is rejected. + +properties: + enabled: + type: boolean + description: Whether auto-pause is on. Always `true`. + example: true + + idle_timeout: + type: string + description: >- + How long the MicroVM is idle before it pauses, as a duration such as + `30s`, `5m`, or `1h`. Defaults to `5m`. The maximum is `4h`. Responses + show the duration in the form `5m0s`. + example: 5m0s diff --git a/specification/resources/microvms/models/microvm_create.yml b/specification/resources/microvms/models/microvm_create.yml new file mode 100644 index 000000000..985a1060b --- /dev/null +++ b/specification/resources/microvms/models/microvm_create.yml @@ -0,0 +1,109 @@ +type: object + +description: >- + The request body for creating a MicroVM. With `source.oci_ref`, `region` + and `size` are required. With `source.checkpoint_id`, the MicroVM inherits + the checkpoint's region, size, container image, and environment variables, + and a different `region` or `size`, or any `environment`, is rejected. + +properties: + name: + type: string + pattern: '^[a-z0-9-]{1,63}$' + description: >- + The name of the MicroVM. Must be unique in the region and contain 1 to 63 + lowercase letters, digits, and hyphens. + example: example-microvm + + source: + $ref: 'microvm_source.yml' + + region: + type: string + description: >- + The slug of the region to create the MicroVM in. Required with + `source.oci_ref`. + example: mkc1 + + size: + $ref: 'microvm_size.yml' + + networking: + type: string + enum: + - public + - vpc + default: public + description: >- + `public` sends outbound traffic through a shared NAT gateway. `vpc` + places the MicroVM in the VPC network set by `vpc_uuid`. + example: public + + vpc_uuid: + type: string + format: uuid + description: >- + The ID of a VPC network in the same region that belongs to your team. + Required when `networking` is `vpc`. + example: 5a4981aa-9653-4bd1-bef5-d6bff52042e4 + + auto_pause: + $ref: 'microvm_auto_pause.yml' + + auto_resume: + type: boolean + default: true + description: >- + Whether an HTTP request, command, or console session resumes the + MicroVM when it is paused. Set to `false` to require a manual resume. + example: true + + http_port: + type: integer + default: 80 + description: >- + The guest port the workload serves HTTP on. Not returned in responses. + When creating from a checkpoint without `ports`, must be one of the + checkpoint's ports. + example: 80 + + http_protocol: + type: string + enum: + - http + - http2 + description: The protocol the HTTP port serves. + example: http + + ports: + type: array + maxItems: 5 + items: + type: integer + description: >- + The guest ports to open, up to five. Must include `http_port`. Defaults + to only the HTTP port. + example: + - 80 + + environment: + type: object + additionalProperties: + type: string + description: >- + Environment variables passed into the MicroVM at boot, as key and value + pairs. Not returned in responses. + example: + APP_ENV: production + + tags: + type: array + items: + type: string + description: Tags to apply to the MicroVM. + example: + - example + +required: + - name + - source diff --git a/specification/resources/microvms/models/microvm_error.yml b/specification/resources/microvms/models/microvm_error.yml new file mode 100644 index 000000000..8a2a3294e --- /dev/null +++ b/specification/resources/microvms/models/microvm_error.yml @@ -0,0 +1,18 @@ +type: object + +description: A MicroVMs API error response. + +properties: + code: + type: string + description: A service-defined error code. + example: NOT_FOUND + + message: + type: string + description: A human-readable description of the error. + example: MicroVM not found + +required: + - code + - message diff --git a/specification/resources/microvms/models/microvm_options.yml b/specification/resources/microvms/models/microvm_options.yml new file mode 100644 index 000000000..7db0c0741 --- /dev/null +++ b/specification/resources/microvms/models/microvm_options.yml @@ -0,0 +1,116 @@ +type: object + +description: >- + The default region, sizes, prices, account limits, and features available + to your team. + +properties: + default_region: + type: string + description: The slug of the region MicroVMs are created in by default. + example: mkc1 + + sizes: + type: array + description: The sizes available to your team. + items: + type: object + properties: + cpu: + type: integer + description: The number of vCPUs. + example: 1 + memory: + type: integer + description: The amount of memory, in MiB. + example: 2048 + disk: + type: integer + description: The size of the disk, in GB. + example: 50 + available: + type: boolean + description: Whether the size is available on your team's plan. + example: true + regions: + type: array + items: + type: string + description: The slugs of the regions the size is available in. + example: + - mkc1 + pricing: + type: object + description: The compute price of the size. + properties: + price_per_hour: + type: number + description: The price per hour of running time, in USD. + example: 0.039 + price_per_month: + type: number + description: >- + The price for running continuously for a month (730 hours), in + USD. + example: 28.47 + + resource_pricing: + type: object + description: Per-resource rates, in USD. + properties: + price_per_vcpu_hour: + type: number + description: The price per vCPU per hour of running time. + example: 0.022 + price_per_gib_memory_hour: + type: number + description: The price per GiB of memory per hour of running time. + example: 0.0085 + price_per_gib_storage_month: + type: number + description: The price per GiB-month of disk and checkpoint storage. + example: 0.05 + price_per_gib_bandwidth: + type: number + description: The price per GiB of outbound data transfer. + example: 0.01 + + account_limits: + type: object + description: Your team's MicroVM limits. + properties: + max_total_count: + type: integer + description: >- + The maximum number of MicroVMs, counting both running and paused + MicroVMs. + example: 1000 + max_memory_bytes: + type: integer + format: int64 + description: The maximum memory per MicroVM, in bytes. + example: 34359738368 + max_disk_bytes: + type: integer + format: int64 + description: The maximum disk per MicroVM, in bytes. + example: 429496729600 + max_idle_timeout_seconds: + type: integer + description: The maximum auto-pause idle timeout, in seconds. + example: 14400 + + features: + type: array + description: Features and whether they are enabled for your team. + items: + type: object + properties: + name: + type: string + description: The name of the feature. + example: exec_pty + enabled: + type: boolean + description: Whether the feature is enabled. + example: true diff --git a/specification/resources/microvms/models/microvm_size.yml b/specification/resources/microvms/models/microvm_size.yml new file mode 100644 index 000000000..2f0371bf5 --- /dev/null +++ b/specification/resources/microvms/models/microvm_size.yml @@ -0,0 +1,27 @@ +type: object + +description: >- + 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. + +properties: + cpu: + type: integer + description: The number of vCPUs. + example: 1 + + memory: + type: integer + description: The amount of memory, in MiB. + example: 2048 + + disk: + type: integer + readOnly: true + description: The size of the disk, in GB. Set by the size. + example: 50 + +required: + - cpu + - memory diff --git a/specification/resources/microvms/models/microvm_source.yml b/specification/resources/microvms/models/microvm_source.yml new file mode 100644 index 000000000..55e5750e7 --- /dev/null +++ b/specification/resources/microvms/models/microvm_source.yml @@ -0,0 +1,22 @@ +type: object + +description: >- + What the MicroVM runs. Set exactly one of `oci_ref` or `checkpoint_id`. + +properties: + oci_ref: + type: string + description: >- + A reference to a `linux/amd64` container image in the form + `registry/repository:tag`. The image can be public, such as an image on + Docker Hub, or private in your team's DigitalOcean Container Registry. + example: docker.io/library/nginx:latest + + checkpoint_id: + type: string + format: uuid + description: >- + The ID of a checkpoint to create the MicroVM from. The new MicroVM + inherits the checkpoint's region, size, container image, and environment + variables. + example: 01a0ed98-0a74-75dd-a625-e4856adbc298 diff --git a/specification/resources/microvms/models/microvm_url.yml b/specification/resources/microvms/models/microvm_url.yml new file mode 100644 index 000000000..c104651b5 --- /dev/null +++ b/specification/resources/microvms/models/microvm_url.yml @@ -0,0 +1,31 @@ +type: object + +description: An HTTPS endpoint for one of the MicroVM's ports. + +properties: + hostname: + type: string + description: >- + The endpoint's hostname. Empty until provisioning finishes. Requests to + the endpoint must include a DigitalOcean API token with the + `microvm:access` scope in the `Authorization` header. + example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a.mkc1.microvm.ondigitalocean.com + + port: + type: integer + description: The guest port the endpoint serves. + example: 80 + + default: + type: boolean + description: Whether this is the endpoint for the MicroVM's HTTP port. + example: true + + status: + type: string + enum: + - PENDING + - ACTIVE + description: >- + `PENDING` until provisioning finishes, then `ACTIVE`. + example: ACTIVE diff --git a/specification/resources/microvms/parameters.yml b/specification/resources/microvms/parameters.yml new file mode 100644 index 000000000..e5d2d9337 --- /dev/null +++ b/specification/resources/microvms/parameters.yml @@ -0,0 +1,94 @@ +microvm_id: + in: path + name: microvm_id + description: The unique ID of the MicroVM. + required: true + schema: + type: string + format: uuid + example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a + +checkpoint_id: + in: path + name: checkpoint_id + description: The unique ID of the checkpoint. + required: true + schema: + type: string + format: uuid + example: 01a0ed98-0a74-75dd-a625-e4856adbc298 + +microvm_region: + in: query + name: region + required: false + description: Only return MicroVMs in this region. + schema: + type: string + example: mkc1 + +name: + in: query + name: name + required: false + description: Only return the MicroVM with this exact name. + schema: + type: string + example: example-microvm + +tag_name: + in: query + name: tag_name + required: false + description: >- + Only return MicroVMs with this tag. A tag that matches no MicroVMs returns + an empty list. + schema: + type: string + example: example + +microvm_id_filter: + in: query + name: microvm_id + required: false + description: Only return checkpoints taken from this MicroVM. + schema: + type: string + format: uuid + example: 01a0ef1a-d873-793d-ae6a-5dd6239be62a + +console_rows: + in: query + name: rows + required: false + description: The initial number of terminal rows. + schema: + type: integer + minimum: 1 + maximum: 65535 + default: 24 + example: 24 + +console_cols: + in: query + name: cols + required: false + description: The initial number of terminal columns. + schema: + type: integer + minimum: 1 + maximum: 65535 + default: 80 + example: 80 + +microvm_per_page: + in: query + name: per_page + required: false + description: Number of items returned per page. + schema: + type: integer + minimum: 1 + default: 25 + maximum: 200 + example: 25 diff --git a/specification/resources/microvms/responses/all_checkpoints.yml b/specification/resources/microvms/responses/all_checkpoints.yml new file mode 100644 index 000000000..002089e7f --- /dev/null +++ b/specification/resources/microvms/responses/all_checkpoints.yml @@ -0,0 +1,47 @@ +description: >- + The response will be a JSON object with a key called `checkpoints`. The + value will be an array of checkpoint objects, newest first. + +headers: + ratelimit-limit: + $ref: '../../../shared/headers.yml#/ratelimit-limit' + ratelimit-remaining: + $ref: '../../../shared/headers.yml#/ratelimit-remaining' + ratelimit-reset: + $ref: '../../../shared/headers.yml#/ratelimit-reset' + +content: + application/json: + schema: + allOf: + - type: object + properties: + checkpoints: + type: array + items: + $ref: '../models/checkpoint.yml' + - $ref: '../../../shared/pages.yml#/pagination' + - $ref: '../../../shared/meta.yml' + + examples: + All Checkpoints: + value: + checkpoints: + - id: 01a0ed98-0a74-75dd-a625-e4856adbc298 + name: example-checkpoint + microvm_id: 01a0ef1a-d873-793d-ae6a-5dd6239be62a + microvm_name: example-microvm + region: mkc1 + size: + cpu: 1 + memory: 2048 + disk: 50 + status: CHECKPOINT_AVAILABLE + memory_bytes: 2147483648 + disk_bytes: 1073741824 + created_at: "2026-09-29T14:35:59Z" + links: {} + meta: + page: 1 + per_page: 25 + total: 1 diff --git a/specification/resources/microvms/responses/all_microvms.yml b/specification/resources/microvms/responses/all_microvms.yml new file mode 100644 index 000000000..bb2075b26 --- /dev/null +++ b/specification/resources/microvms/responses/all_microvms.yml @@ -0,0 +1,63 @@ +description: >- + The response will be a JSON object with a key called `microvms`. The value + will be an array of MicroVM objects. + +headers: + ratelimit-limit: + $ref: '../../../shared/headers.yml#/ratelimit-limit' + ratelimit-remaining: + $ref: '../../../shared/headers.yml#/ratelimit-remaining' + ratelimit-reset: + $ref: '../../../shared/headers.yml#/ratelimit-reset' + +content: + application/json: + schema: + allOf: + - type: object + properties: + microvms: + type: array + items: + $ref: '../models/microvm.yml' + - $ref: '../../../shared/pages.yml#/pagination' + - $ref: '../../../shared/meta.yml' + + examples: + All MicroVMs: + value: + microvms: + - id: 01a0ef1a-d873-793d-ae6a-5dd6239be62a + name: example-microvm + region: mkc1 + size: + cpu: 1 + memory: 2048 + disk: 50 + source: + oci_ref: docker.io/library/nginx:latest + state: paused + networking: public + auto_pause: + enabled: true + idle_timeout: 5m0s + auto_resume: true + http_protocol: http + ports: + - 80 + tags: + - example + urls: + - hostname: 01a0ef1a-d873-793d-ae6a-5dd6239be62a.mkc1.microvm.ondigitalocean.com + port: 80 + default: true + status: ACTIVE + created_at: "2026-09-29T21:38:29Z" + links: + pages: + last: /v2/microvms?page=4&per_page=1 + next: /v2/microvms?page=2&per_page=1 + meta: + page: 1 + per_page: 1 + total: 4 diff --git a/specification/resources/microvms/responses/checkpoint.yml b/specification/resources/microvms/responses/checkpoint.yml new file mode 100644 index 000000000..87a2670c7 --- /dev/null +++ b/specification/resources/microvms/responses/checkpoint.yml @@ -0,0 +1,38 @@ +description: >- + 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. + +headers: + ratelimit-limit: + $ref: '../../../shared/headers.yml#/ratelimit-limit' + ratelimit-remaining: + $ref: '../../../shared/headers.yml#/ratelimit-remaining' + ratelimit-reset: + $ref: '../../../shared/headers.yml#/ratelimit-reset' + +content: + application/json: + schema: + type: object + properties: + checkpoint: + $ref: '../models/checkpoint.yml' + + examples: + Available Checkpoint: + value: + checkpoint: + id: 01a0ed98-0a74-75dd-a625-e4856adbc298 + name: example-checkpoint + microvm_id: 01a0ef1a-d873-793d-ae6a-5dd6239be62a + microvm_name: example-microvm + region: mkc1 + size: + cpu: 1 + memory: 2048 + disk: 50 + status: CHECKPOINT_AVAILABLE + memory_bytes: 2147483648 + disk_bytes: 1073741824 + created_at: "2026-09-29T14:35:59Z" diff --git a/specification/resources/microvms/responses/console_upgrade.yml b/specification/resources/microvms/responses/console_upgrade.yml new file mode 100644 index 000000000..fb9793d77 --- /dev/null +++ b/specification/resources/microvms/responses/console_upgrade.yml @@ -0,0 +1,20 @@ +description: >- + 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. + +headers: + ratelimit-limit: + $ref: '../../../shared/headers.yml#/ratelimit-limit' + ratelimit-remaining: + $ref: '../../../shared/headers.yml#/ratelimit-remaining' + ratelimit-reset: + $ref: '../../../shared/headers.yml#/ratelimit-reset' diff --git a/specification/resources/microvms/responses/errors.yml b/specification/resources/microvms/responses/errors.yml new file mode 100644 index 000000000..557af73b4 --- /dev/null +++ b/specification/resources/microvms/responses/errors.yml @@ -0,0 +1,79 @@ +bad_request: + description: The request was malformed or failed validation. + + headers: + ratelimit-limit: + $ref: '../../../shared/headers.yml#/ratelimit-limit' + ratelimit-remaining: + $ref: '../../../shared/headers.yml#/ratelimit-remaining' + ratelimit-reset: + $ref: '../../../shared/headers.yml#/ratelimit-reset' + + content: + application/json: + schema: + $ref: '../models/microvm_error.yml' + example: + code: INVALID_ARGUMENT + message: "size must be one of the supported sizes" + +forbidden: + description: >- + The token does not have the required scope, the feature is not enabled for + your team, or your team has reached a limit. + + headers: + ratelimit-limit: + $ref: '../../../shared/headers.yml#/ratelimit-limit' + ratelimit-remaining: + $ref: '../../../shared/headers.yml#/ratelimit-remaining' + ratelimit-reset: + $ref: '../../../shared/headers.yml#/ratelimit-reset' + + content: + application/json: + schema: + $ref: '../models/microvm_error.yml' + example: + code: PERMISSION_DENIED + message: "permission denied" + +not_found: + description: The MicroVM or checkpoint does not exist, or it belongs to another team. + + headers: + ratelimit-limit: + $ref: '../../../shared/headers.yml#/ratelimit-limit' + ratelimit-remaining: + $ref: '../../../shared/headers.yml#/ratelimit-remaining' + ratelimit-reset: + $ref: '../../../shared/headers.yml#/ratelimit-reset' + + content: + application/json: + schema: + $ref: '../models/microvm_error.yml' + example: + code: NOT_FOUND + message: MicroVM not found + +bad_gateway: + description: >- + The command did not reach the workload, for example because the container + is not running. + + headers: + ratelimit-limit: + $ref: '../../../shared/headers.yml#/ratelimit-limit' + ratelimit-remaining: + $ref: '../../../shared/headers.yml#/ratelimit-remaining' + ratelimit-reset: + $ref: '../../../shared/headers.yml#/ratelimit-reset' + + content: + application/json: + schema: + $ref: '../models/microvm_error.yml' + example: + code: UNAVAILABLE + message: "workload unavailable" diff --git a/specification/resources/microvms/responses/exec.yml b/specification/resources/microvms/responses/exec.yml new file mode 100644 index 000000000..e632ef40b --- /dev/null +++ b/specification/resources/microvms/responses/exec.yml @@ -0,0 +1,23 @@ +description: >- + The command ran. HTTP 200 is returned even when the command itself fails. + Check `exit_code` for the command's result. + +headers: + ratelimit-limit: + $ref: '../../../shared/headers.yml#/ratelimit-limit' + ratelimit-remaining: + $ref: '../../../shared/headers.yml#/ratelimit-remaining' + ratelimit-reset: + $ref: '../../../shared/headers.yml#/ratelimit-reset' + +content: + application/json: + schema: + $ref: '../models/exec.yml#/exec_response' + + examples: + Command Output: + value: + stdout: "" + stderr: "nginx version: nginx/1.29.1\n" + exit_code: 0 diff --git a/specification/resources/microvms/responses/microvm.yml b/specification/resources/microvms/responses/microvm.yml new file mode 100644 index 000000000..1528c705a --- /dev/null +++ b/specification/resources/microvms/responses/microvm.yml @@ -0,0 +1,51 @@ +description: >- + 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. + +headers: + ratelimit-limit: + $ref: '../../../shared/headers.yml#/ratelimit-limit' + ratelimit-remaining: + $ref: '../../../shared/headers.yml#/ratelimit-remaining' + ratelimit-reset: + $ref: '../../../shared/headers.yml#/ratelimit-reset' + +content: + application/json: + schema: + type: object + properties: + microvm: + $ref: '../models/microvm.yml' + + examples: + Running MicroVM: + value: + microvm: + id: 01a0ef1a-d873-793d-ae6a-5dd6239be62a + name: example-microvm + region: mkc1 + size: + cpu: 1 + memory: 2048 + disk: 50 + source: + oci_ref: docker.io/library/nginx:latest + state: running + networking: public + auto_pause: + enabled: true + idle_timeout: 5m0s + auto_resume: true + http_protocol: http + ports: + - 80 + tags: + - example + urls: + - hostname: 01a0ef1a-d873-793d-ae6a-5dd6239be62a.mkc1.microvm.ondigitalocean.com + port: 80 + default: true + status: ACTIVE + created_at: "2026-09-29T21:38:29Z" diff --git a/specification/resources/microvms/responses/microvm_created.yml b/specification/resources/microvms/responses/microvm_created.yml new file mode 100644 index 000000000..2e740a04f --- /dev/null +++ b/specification/resources/microvms/responses/microvm_created.yml @@ -0,0 +1,52 @@ +description: >- + 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`. + +headers: + ratelimit-limit: + $ref: '../../../shared/headers.yml#/ratelimit-limit' + ratelimit-remaining: + $ref: '../../../shared/headers.yml#/ratelimit-remaining' + ratelimit-reset: + $ref: '../../../shared/headers.yml#/ratelimit-reset' + +content: + application/json: + schema: + type: object + properties: + microvm: + $ref: '../models/microvm.yml' + + examples: + Creating MicroVM: + value: + microvm: + id: 01a0ef1a-d873-793d-ae6a-5dd6239be62a + name: example-microvm + region: mkc1 + size: + cpu: 1 + memory: 2048 + disk: 50 + source: + oci_ref: docker.io/library/nginx:latest + state: creating + networking: public + auto_pause: + enabled: true + idle_timeout: 5m0s + auto_resume: true + http_protocol: http + ports: + - 80 + tags: + - example + urls: + - hostname: "" + port: 80 + default: true + status: PENDING + created_at: "2026-09-29T21:38:29Z" diff --git a/specification/resources/microvms/responses/microvm_options.yml b/specification/resources/microvms/responses/microvm_options.yml new file mode 100644 index 000000000..7399ba7fb --- /dev/null +++ b/specification/resources/microvms/responses/microvm_options.yml @@ -0,0 +1,73 @@ +description: >- + The response will be a JSON object with the default region, sizes, prices, + account limits, and features available to your team. + +headers: + ratelimit-limit: + $ref: '../../../shared/headers.yml#/ratelimit-limit' + ratelimit-remaining: + $ref: '../../../shared/headers.yml#/ratelimit-remaining' + ratelimit-reset: + $ref: '../../../shared/headers.yml#/ratelimit-reset' + +content: + application/json: + schema: + $ref: '../models/microvm_options.yml' + + examples: + Options: + value: + default_region: mkc1 + sizes: + - cpu: 1 + memory: 2048 + disk: 50 + available: true + regions: + - mkc1 + pricing: + price_per_hour: 0.039 + price_per_month: 28.47 + - cpu: 2 + memory: 4096 + disk: 80 + available: true + regions: + - mkc1 + pricing: + price_per_hour: 0.078 + price_per_month: 56.94 + - cpu: 8 + memory: 16384 + disk: 320 + available: true + regions: + - mkc1 + pricing: + price_per_hour: 0.312 + price_per_month: 227.76 + - cpu: 16 + memory: 32768 + disk: 400 + available: true + regions: + - mkc1 + pricing: + price_per_hour: 0.624 + price_per_month: 455.52 + resource_pricing: + price_per_vcpu_hour: 0.022 + price_per_gib_memory_hour: 0.0085 + price_per_gib_storage_month: 0.05 + price_per_gib_bandwidth: 0.01 + account_limits: + max_total_count: 1000 + max_memory_bytes: 34359738368 + max_disk_bytes: 429496729600 + max_idle_timeout_seconds: 14400 + features: + - name: microvm + enabled: true + - name: exec_pty + enabled: true From b2b7e145c241c385d10f7335f41514bc1c299a18 Mon Sep 17 00:00:00 2001 From: Brian Boucheron Date: Thu, 8 Oct 2026 14:47:01 -0400 Subject: [PATCH 2/4] PDOCS-4764: use observed MicroVMs error codes and nullable http_protocol --- .../resources/microvms/models/microvm.yml | 5 +++- .../resources/microvms/responses/errors.yml | 24 ++++++++++++++----- 2 files changed, 22 insertions(+), 7 deletions(-) diff --git a/specification/resources/microvms/models/microvm.yml b/specification/resources/microvms/models/microvm.yml index bfd72f474..42ccc8abb 100644 --- a/specification/resources/microvms/models/microvm.yml +++ b/specification/resources/microvms/models/microvm.yml @@ -87,7 +87,10 @@ properties: enum: - http - http2 - description: The protocol the MicroVM's HTTP port serves. + nullable: true + description: >- + The protocol the MicroVM's HTTP port serves. `null` if the protocol was + not set when the MicroVM was created. example: http ports: diff --git a/specification/resources/microvms/responses/errors.yml b/specification/resources/microvms/responses/errors.yml index 557af73b4..52509e082 100644 --- a/specification/resources/microvms/responses/errors.yml +++ b/specification/resources/microvms/responses/errors.yml @@ -1,5 +1,7 @@ bad_request: - description: The request was malformed or failed validation. + description: >- + The request was malformed, failed validation, or is not allowed in the + resource's current state. headers: ratelimit-limit: @@ -13,14 +15,24 @@ bad_request: application/json: schema: $ref: '../models/microvm_error.yml' - example: - code: INVALID_ARGUMENT - message: "size must be one of the supported sizes" + examples: + Invalid Size: + value: + code: INVALID_SIZE + message: "no supported size matches the requested resources: 3 vCPU with 2048 MiB of memory (supported: 1vCPU/2048MiB, 2vCPU/4096MiB, 8vCPU/16384MiB, 16vCPU/32768MiB)" + Auto-Pause Disabled: + value: + 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" + Checkpoint Still Capturing: + value: + code: FAILED_PRECONDITION + message: "checkpoint 01a11cd5-25dd-790f-a77c-3677f24bca85 is still being captured; retry delete once the capture completes" forbidden: description: >- - The token does not have the required scope, the feature is not enabled for - your team, or your team has reached a limit. + The token does not have the required scope, or your team has reached a + limit. headers: ratelimit-limit: From 28a55f7772329da2095615017850d1b1342c9d12 Mon Sep 17 00:00:00 2001 From: Brian Boucheron Date: Thu, 8 Oct 2026 15:03:54 -0400 Subject: [PATCH 3/4] PDOCS-4764: note only the HTTP port is reachable --- specification/resources/microvms/models/microvm.yml | 5 ++++- specification/resources/microvms/models/microvm_create.yml | 5 +++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/specification/resources/microvms/models/microvm.yml b/specification/resources/microvms/models/microvm.yml index 42ccc8abb..8c2d62b4f 100644 --- a/specification/resources/microvms/models/microvm.yml +++ b/specification/resources/microvms/models/microvm.yml @@ -98,7 +98,10 @@ properties: maxItems: 5 items: type: integer - description: The guest ports open on the MicroVM, including the HTTP port. + description: >- + 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. example: - 80 diff --git a/specification/resources/microvms/models/microvm_create.yml b/specification/resources/microvms/models/microvm_create.yml index 985a1060b..c987c98cc 100644 --- a/specification/resources/microvms/models/microvm_create.yml +++ b/specification/resources/microvms/models/microvm_create.yml @@ -81,8 +81,9 @@ properties: items: type: integer description: >- - The guest ports to open, up to five. Must include `http_port`. Defaults - to only the HTTP port. + 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. example: - 80 From 86c97015a6765147e90dda72151704b76d9d4168 Mon Sep 17 00:00:00 2001 From: Brian Boucheron Date: Thu, 8 Oct 2026 15:45:20 -0400 Subject: [PATCH 4/4] PDOCS-4764: default http_port to 8080 --- .../resources/microvms/models/microvm_create.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/resources/microvms/models/microvm_create.yml b/specification/resources/microvms/models/microvm_create.yml index c987c98cc..6b7d7fd8a 100644 --- a/specification/resources/microvms/models/microvm_create.yml +++ b/specification/resources/microvms/models/microvm_create.yml @@ -60,11 +60,11 @@ properties: http_port: type: integer - default: 80 + default: 8080 description: >- - The guest port the workload serves HTTP on. Not returned in responses. - When creating from a checkpoint without `ports`, must be one of the - checkpoint's ports. + 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. example: 80 http_protocol: