PDOCS-4764: Add MicroVMs Public Preview API

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
@@ -754,6 +769,7 @@ x-tagGroups:
       - Insights
       - Kubernetes
       - Load Balancers
+      - MicroVMs [Public Preview]
       - Monitoring
       - NFS
       - NFS Actions
@@ -2040,6 +2056,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"

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"

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"

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"

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"

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"

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"

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"

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"

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"

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"

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"

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"

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"

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'

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'

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'

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'