API reference

Machines API

Create, list, read, change, start, stop, restart, and delete machines. Every lifecycle change is an asynchronous operation.

View as Markdown

List machines: GET /v1/machines
Create a machine: POST /v1/machines
Get a machine: GET /v1/machines/{machine_id}
Change machine settings: PATCH /v1/machines/{machine_id}
Start a machine: POST /v1/machines/{machine_id}/start
Stop a machine: POST /v1/machines/{machine_id}/stop
Restart a machine: POST /v1/machines/{machine_id}/restart
Delete a machine: POST /v1/machines/{machine_id}/delete
Change a machine's egress: PUT /v1/machines/{machine_id}/network

List machines

GET /v1/machines

API key: Authorization: Bearer vmy_… with preset read_only, use_existing, create_and_use, full_access.
Browser session: the vmyard_session cookie.
Who: Any member.

Parameters

Name	In	Type	Required	Description
`limit`	query	`integer`	No	Page size, 1-100 (default 50).
`cursor`	query	`string`	No	`next_cursor` from the previous page, with the same `sort` and `order`.
`q`	query	`string`	No	Case-insensitive search, at most 128 characters: contained in the display name or tenant alias, a prefix of the machine ID or port label, or a port host (`<label>-<port>...`). Blank means no search.
`state`	query	`string`	No	Observed state: `absent`, `provisioning`, `running`, `stopped`, `degraded`, or `unknown`.
`desired_state`	query	`string`	No	Desired state: `running`, `stopped`, or `deleted`.
`sort`	query	`string`	No	`created_at` (default), `name` (display name), or `state` (observed state).
`order`	query	`string`	No	`asc` or `desc`. Defaults to `desc` for `created_at` (newest first) and `asc` otherwise. Ties break on the machine ID in the same direction.
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Responses

Status	Description	Body
`200`	—	`MachinePage`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`422`	An unknown `sort`, `order`, `state`, or `desired_state`, an oversized `q`, or a malformed cursor or one made for another sort	`ProblemDetails`

Request

curl "$VMYARD_API_URL/v1/machines" \
  -H "Authorization: Bearer $VMYARD_API_KEY"

Response 200

{
  "items": [
    {
      "auto_stop_after_seconds": 0,
      "auto_stop_at": "2026-10-12T06:51:01Z",
      "backend": "mock",
      "created_at": "2026-10-12T05:51:01Z",
      "desired_state": "running",
      "environment": {
        "applied_version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "error_code": "string",
        "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "status": "pending",
        "version": 0,
        "version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
      },
      "forked_from_machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "idle_since": "2026-10-12T05:36:01Z",
      "idle_sleep_after_seconds": 900,
      "idle_sleep_at": "2026-10-12T05:51:01Z",
      "image": {
        "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "version": 0
      },
      "last_active_at": "2026-10-12T05:36:01Z",
      "latest_snapshot": {
        "completed_at": "2026-10-12T05:51:01Z",
        "created_at": "2026-10-12T05:51:01Z",
        "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "source": "api",
        "status": "pending",
        "tier": "warm"
      },
      "metrics": {
        "cpu_limit_millis": 0,
        "cpu_millis": 0,
        "cpu_percent": 0.5,
        "disk_percent": 0.5,
        "disk_size_bytes": 0,
        "disk_used_bytes": 0,
        "flags": [
          "disk_almost_full"
        ],
        "io_read_bps": 0,
        "io_write_bps": 0,
        "memory_bytes": 0,
        "memory_limit_bytes": 0,
        "memory_percent": 0.5,
        "net_rx_bps": 0,
        "net_tx_bps": 0,
        "sampled_at": "2026-10-12T05:51:01Z",
        "stale": false,
        "stale_reason": "host_unreachable",
        "state": "string"
      },
      "name": "dev",
      "network": {
        "egress": "none",
        "ipv6_address": "string"
      },
      "observed_state": {
        "boot_id": "string",
        "state": "running"
      },
      "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "plan": {
        "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "version": 0
      },
      "region": {
        "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "version": 0
      },
      "resources": {
        "cpu": 0,
        "disk_gib": 0,
        "memory_mib": 0
      },
      "restored_from_snapshot_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "setup_operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
      "ssh": {
        "host": "ssh.eu.example.com",
        "port": 0,
        "user": "vmyard"
      },
      "starting_soon": {
        "expires_at": "2026-10-12T05:51:01Z",
        "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
        "position": 0,
        "priority": "paid",
        "queued_at": "2026-10-12T05:51:01Z",
        "reason": "no_host_in_region"
      },
      "tenant_alias": "dev"
    }
  ],
  "next_cursor": "string"
}

Create a machine

POST /v1/machines

Billing admission can refuse it: 402 billing_required or spend_cap_reached, 403 trial_machine_class_not_allowed, 409 plan_not_priced, or 429 limit_reached. See Usage, billing, and limits. Idle sleep is off unless the body sets idle_sleep_after_seconds (300 to 86,400); see Idle sleep. network: {egress} (none or internet) chooses the machine's egress; omitted, the host's default applies, and it can't be combined with template (422); see Internet access and IPv6.

API key: Authorization: Bearer vmy_… with preset create_and_use, full_access.
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Owner, Admin, or Operator.
Idempotency: send a unique Idempotency-Key; replaying the same key and body returns the same operation.

Parameters

Name	In	Type	Required	Description
`X-Organization-ID`	header	`string (uuid)`	No	Organization context. Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Request body (application/json, CreateMachineRequest)

Field	Type	Required	Description
`auto_stop_after_seconds`	`integer \| null`	No	Seconds the machine may run after it becomes running before the control plane stops it, 60 to 2592000. Omitted means 3600; `null` means never. 60–2592000.
`backend`	`null \| BackendDto`	No
`environment`	`string \| null`	No	Environment to apply, by name (alternative to `environment_id`).
`environment_id`	`string (uuid) \| null`	No	Environment to apply once the machine is first ready, by ID. Omitting `environment_id`, `environment`, and `no_env` selects the organization's default environment, if it has one.
`idle_sleep_after_seconds`	`integer \| null`	No	Seconds the running machine may stay idle (no operation, terminal, or resource activity) before the control plane puts it to sleep, 300 to 86400. Omitted or `null` leaves idle sleep off. 300–86400.
`image`	`null \| VersionedSelectionDto`	No
`name`	`string \| null`	No	Display name, following the `tenant_alias` rules. Defaults to the tenant alias. Unlike the alias it can be changed later.
`network`	`null \| NetworkRequest`	No	The machine's egress policy. Omitted, the host's default applies (internet egress unless the operator configured otherwise). Not with `template`: a restored machine keeps its host's policy. Change it later with `PUT /v1/machines/{machine_id}/network`.
`never_auto_stop`	`boolean`	No	`true` disables auto-stop. It cannot be combined with `auto_stop_after_seconds`.
`no_env`	`boolean`	No	`true` creates the machine without any environment, not even the default (for example, for a machine shared with third parties).
`plan`	`null \| VersionedSelectionDto`	No	Required without `template`; with one, the template's exact plan, image, region, resources, and backend are used and these may be omitted (if sent, they must match).
`region`	`null \| VersionedSelectionDto`	No
`resources`	`null \| ResourcesDto`	No
`setup_script`	`string \| null`	No	Shell script run once as `/bin/sh -c <script>` after the machine is first ready, at most 65527 bytes without NUL. It is its own exec operation (see `setup_operation_id`) with the runtime's maximum timeout; its failure does not stop the machine.
`template`	`string \| null`	No	Create the machine from a ready template (name or ID): a warm restore with its own identity, woken at once. The chosen environment (or the default, or `no_env`) is applied after the restore.
`tenant_alias`	`string \| null`	No	Required without `template`. With one, it is the template's (the runtime scopes stored snapshots to their tenant) and may be omitted.

Responses

Status	Description	Body
`202`	Accepted. Follow `operation_url` until the operation is terminal.	`OperationAccepted`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`).	`ProblemDetails`
`409`	Conflicts with the current state, such as a reused idempotency key with another body (`idempotency_conflict`).	`ProblemDetails`
`413`	The request body is too large (`body_too_large`).	`ProblemDetails`
`422`	Invalid request (`invalid_request`); `field_errors` names the fields.	`ProblemDetails`

Request

curl -X POST "$VMYARD_API_URL/v1/machines" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "tenant_alias": "dev",
  "name": "dev",
  "plan": {
    "id": "0b6f6c55-2f1d-4f0e-9a51-6f0f4cba7a10",
    "version": 1
  },
  "image": {
    "id": "4d2b9c1e-7a3f-4e58-b1c6-2f9d8e7a6b50",
    "version": 3
  },
  "region": {
    "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "version": 1
  },
  "resources": {
    "cpu": 2,
    "memory_mib": 4096,
    "disk_gib": 12
  },
  "backend": "kvm",
  "auto_stop_after_seconds": 7200,
  "setup_script": "apt-get update && apt-get install -y jq"
}'

Response 202

{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "create",
  "status": "pending"
}

Get a machine

GET /v1/machines/{machine_id}

API key: Authorization: Bearer vmy_… with preset read_only, use_existing, create_and_use, full_access.
Browser session: the vmyard_session cookie.
Who: Any member.

Parameters

Name	In	Type	Required	Description
`machine_id`	path	`string (uuid)`	Yes
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Responses

Status	Description	Body
`200`	—	`MachineDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`

Request

curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY"

Response 200

{
  "auto_stop_after_seconds": 0,
  "auto_stop_at": "2026-10-12T06:51:01Z",
  "backend": "mock",
  "created_at": "2026-10-12T05:51:01Z",
  "desired_state": "running",
  "environment": {
    "applied_version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "error_code": "string",
    "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "status": "pending",
    "version": 0,
    "version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
  },
  "forked_from_machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "idle_since": "2026-10-12T05:36:01Z",
  "idle_sleep_after_seconds": 900,
  "idle_sleep_at": "2026-10-12T05:51:01Z",
  "image": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "version": 0
  },
  "last_active_at": "2026-10-12T05:36:01Z",
  "latest_snapshot": {
    "completed_at": "2026-10-12T05:51:01Z",
    "created_at": "2026-10-12T05:51:01Z",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "source": "api",
    "status": "pending",
    "tier": "warm"
  },
  "metrics": {
    "cpu_limit_millis": 0,
    "cpu_millis": 0,
    "cpu_percent": 0.5,
    "disk_percent": 0.5,
    "disk_size_bytes": 0,
    "disk_used_bytes": 0,
    "flags": [
      "disk_almost_full"
    ],
    "io_read_bps": 0,
    "io_write_bps": 0,
    "memory_bytes": 0,
    "memory_limit_bytes": 0,
    "memory_percent": 0.5,
    "net_rx_bps": 0,
    "net_tx_bps": 0,
    "sampled_at": "2026-10-12T05:51:01Z",
    "stale": false,
    "stale_reason": "host_unreachable",
    "state": "string"
  },
  "name": "dev",
  "network": {
    "egress": "none",
    "ipv6_address": "string"
  },
  "observed_state": {
    "boot_id": "string",
    "state": "running"
  },
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "plan": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "version": 0
  },
  "region": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "version": 0
  },
  "resources": {
    "cpu": 0,
    "disk_gib": 0,
    "memory_mib": 0
  },
  "restored_from_snapshot_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "setup_operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "ssh": {
    "host": "ssh.eu.example.com",
    "port": 0,
    "user": "vmyard"
  },
  "starting_soon": {
    "expires_at": "2026-10-12T05:51:01Z",
    "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "position": 0,
    "priority": "paid",
    "queued_at": "2026-10-12T05:51:01Z",
    "reason": "no_host_in_region"
  },
  "tenant_alias": "dev"
}

Change machine settings

PATCH /v1/machines/{machine_id}

Send only what changes. idle_sleep_after_seconds takes 300 to 86,400 seconds, or null to turn idle sleep off, and restarts the idle window; out of range answers 422 with a field error. See Auto-stop and Idle sleep.

API key: Authorization: Bearer vmy_… with preset use_existing, create_and_use, full_access.
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Owner, Admin, or Operator.

Parameters

Name	In	Type	Required	Description
`machine_id`	path	`string (uuid)`	Yes
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Request body (application/json, UpdateMachineRequest)

Field	Type	Required	Description
`auto_stop_after_seconds`	`integer \| null`	No	New auto-stop duration, 60 to 2592000 seconds, or `null` for never. The deadline of a running machine restarts from now. 60–2592000.
`idle_sleep_after_seconds`	`integer \| null`	No	New idle-sleep window, 300 to 86400 seconds, or `null` to turn idle sleep off. The idle window restarts. 300–86400.
`name`	`string \| null`	No	New display name, following the `tenant_alias` rules. The tenant alias itself is immutable.
`never_auto_stop`	`boolean`	No	`true` disables auto-stop. It cannot be combined with `auto_stop_after_seconds`.

Responses

Status	Description	Body
`200`	—	`MachineDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`).	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`
`409`	`machine_deleted`: the machine was deleted	`ProblemDetails`
`413`	The request body is too large (`body_too_large`).	`ProblemDetails`
`422`	Invalid request (`invalid_request`); `field_errors` names the fields.	`ProblemDetails`

Request

curl -X PATCH "$VMYARD_API_URL/v1/machines/$MACHINE_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "api",
  "auto_stop_after_seconds": 3600,
  "idle_sleep_after_seconds": 900
}'

Response 200

{
  "auto_stop_after_seconds": 0,
  "auto_stop_at": "2026-10-12T06:51:01Z",
  "backend": "mock",
  "created_at": "2026-10-12T05:51:01Z",
  "desired_state": "running",
  "environment": {
    "applied_version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "environment_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "error_code": "string",
    "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "status": "pending",
    "version": 0,
    "version_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f"
  },
  "forked_from_machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "idle_since": "2026-10-12T05:36:01Z",
  "idle_sleep_after_seconds": 900,
  "idle_sleep_at": "2026-10-12T05:51:01Z",
  "image": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "version": 0
  },
  "last_active_at": "2026-10-12T05:36:01Z",
  "latest_snapshot": {
    "completed_at": "2026-10-12T05:51:01Z",
    "created_at": "2026-10-12T05:51:01Z",
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "source": "api",
    "status": "pending",
    "tier": "warm"
  },
  "metrics": {
    "cpu_limit_millis": 0,
    "cpu_millis": 0,
    "cpu_percent": 0.5,
    "disk_percent": 0.5,
    "disk_size_bytes": 0,
    "disk_used_bytes": 0,
    "flags": [
      "disk_almost_full"
    ],
    "io_read_bps": 0,
    "io_write_bps": 0,
    "memory_bytes": 0,
    "memory_limit_bytes": 0,
    "memory_percent": 0.5,
    "net_rx_bps": 0,
    "net_tx_bps": 0,
    "sampled_at": "2026-10-12T05:51:01Z",
    "stale": false,
    "stale_reason": "host_unreachable",
    "state": "string"
  },
  "name": "dev",
  "network": {
    "egress": "none",
    "ipv6_address": "string"
  },
  "observed_state": {
    "boot_id": "string",
    "state": "running"
  },
  "organization_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "plan": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "version": 0
  },
  "region": {
    "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "version": 0
  },
  "resources": {
    "cpu": 0,
    "disk_gib": 0,
    "memory_mib": 0
  },
  "restored_from_snapshot_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "setup_operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "ssh": {
    "host": "ssh.eu.example.com",
    "port": 0,
    "user": "vmyard"
  },
  "starting_soon": {
    "expires_at": "2026-10-12T05:51:01Z",
    "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
    "position": 0,
    "priority": "paid",
    "queued_at": "2026-10-12T05:51:01Z",
    "reason": "no_host_in_region"
  },
  "tenant_alias": "dev"
}

Start a machine

POST /v1/machines/{machine_id}/start

Billing admission can refuse it: 402 billing_required or spend_cap_reached, 403 trial_machine_class_not_allowed, 409 plan_not_priced, or 429 limit_reached. See Usage, billing, and limits.

API key: Authorization: Bearer vmy_… with preset use_existing, create_and_use, full_access.
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Owner, Admin, or Operator.
Idempotency: send a unique Idempotency-Key; replaying the same key and body returns the same operation.

Parameters

Name	In	Type	Required	Description
`machine_id`	path	`string (uuid)`	Yes
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Request body (application/json, EmptyAction)

No fields.

Responses

Status	Description	Body
`202`	Accepted. Follow `operation_url` until the operation is terminal.	`OperationAccepted`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`).	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`
`409`	`machine_deleted`: the machine's deletion was requested; `machine_not_created`: its create is pending or did not succeed, so only a delete is accepted	`ProblemDetails`
`413`	The request body is too large (`body_too_large`).	`ProblemDetails`
`422`	Invalid request (`invalid_request`); `field_errors` names the fields.	`ProblemDetails`

Request

curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/start" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 202

{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "start",
  "status": "pending"
}

Stop a machine

POST /v1/machines/{machine_id}/stop

API key: Authorization: Bearer vmy_… with preset use_existing, create_and_use, full_access.
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Owner, Admin, or Operator.
Idempotency: send a unique Idempotency-Key; replaying the same key and body returns the same operation.

Parameters

Name	In	Type	Required	Description
`machine_id`	path	`string (uuid)`	Yes
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Request body (application/json, EmptyAction)

No fields.

Responses

Status	Description	Body
`202`	Accepted. Follow `operation_url` until the operation is terminal.	`OperationAccepted`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`).	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`
`409`	`machine_deleted`: the machine's deletion was requested; `machine_not_created`: its create is pending or did not succeed, so only a delete is accepted	`ProblemDetails`
`413`	The request body is too large (`body_too_large`).	`ProblemDetails`
`422`	Invalid request (`invalid_request`); `field_errors` names the fields.	`ProblemDetails`

Request

curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/stop" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 202

{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "stop",
  "status": "pending"
}

Restart a machine

POST /v1/machines/{machine_id}/restart

Billing admission can refuse it: 402 billing_required or spend_cap_reached, 403 trial_machine_class_not_allowed, 409 plan_not_priced, or 429 limit_reached. See Usage, billing, and limits. One restart operation reboots the running machine without stopping it: /work is kept, its run stays open, and it succeeds only with a new boot_id. A host that can't restart its machines ends it failed with restart_unsupported, and the machine keeps running. See Restart.

API key: Authorization: Bearer vmy_… with preset use_existing, create_and_use, full_access.
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Owner, Admin, or Operator.
Idempotency: send a unique Idempotency-Key; replaying the same key and body returns the same operation.

Parameters

Name	In	Type	Required	Description
`machine_id`	path	`string (uuid)`	Yes
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Request body (application/json, EmptyAction)

No fields.

Responses

Status	Description	Body
`202`	Accepted. Follow `operation_url` until the operation is terminal.	`OperationAccepted`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`).	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`
`409`	`machine_deleted`: the machine's deletion was requested; `machine_not_created`: its create is pending or did not succeed, so only a delete is accepted	`ProblemDetails`
`413`	The request body is too large (`body_too_large`).	`ProblemDetails`
`422`	Invalid request (`invalid_request`); `field_errors` names the fields.	`ProblemDetails`

Request

curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/restart" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 202

{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "restart",
  "status": "pending"
}

Delete a machine

POST /v1/machines/{machine_id}/delete

API key: Authorization: Bearer vmy_… with preset create_and_use, full_access.
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Owner, Admin, or Operator.
Idempotency: send a unique Idempotency-Key; replaying the same key and body returns the same operation.

Parameters

Name	In	Type	Required	Description
`machine_id`	path	`string (uuid)`	Yes
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Request body (application/json, EmptyAction)

No fields.

Responses

Status	Description	Body
`202`	Accepted. Follow `operation_url` until the operation is terminal.	`OperationAccepted`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`).	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`
`409`	`machine_deleted`: the machine's deletion was requested; `machine_not_created`: its create is pending or did not succeed, so only a delete is accepted	`ProblemDetails`
`413`	The request body is too large (`body_too_large`).	`ProblemDetails`
`422`	Invalid request (`invalid_request`); `field_errors` names the fields.	`ProblemDetails`

Request

curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/delete" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 202

{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "delete",
  "status": "pending"
}

Change a machine's egress

PUT /v1/machines/{machine_id}/network

The machine must be running or stopped (422 otherwise); the change never starts, stops, or restarts it. The network_set operation succeeds only when the host reports the requested policy applied, and MachineDto.network then shows it. A host without guest networking, or one whose operator turned internet egress off, ends it failed with nothing changed. See Internet access and IPv6.

API key: Authorization: Bearer vmy_… with preset create_and_use, full_access.
Browser session: the vmyard_session cookie and the x-csrf-token header.
Who: Owner, Admin, or Operator.
Idempotency: send a unique Idempotency-Key; replaying the same key and body returns the same operation.

Parameters

Name	In	Type	Required	Description
`machine_id`	path	`string (uuid)`	Yes
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.

Request body (application/json, NetworkRequest)

Field	Type	Required	Description
`egress`	`EgressDto`	Yes

Responses

Status	Description	Body
`202`	The `network_set` operation changes the policy on the machine's host; the machine must be running or stopped. `MachineDto.network` shows the result once it succeeds.	`OperationAccepted`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`403`	Refused for this caller: role, key preset, CSRF token, or organization (`forbidden`, `insufficient_scope`, `csrf_invalid`, `organization_mismatch`, `session_required`).	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`
`409`	Conflicts with the current state, such as a reused idempotency key with another body (`idempotency_conflict`).	`ProblemDetails`
`422`	Invalid request (`invalid_request`); `field_errors` names the fields.	`ProblemDetails`

Request

curl -X PUT "$VMYARD_API_URL/v1/machines/$MACHINE_ID/network" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "egress": "none"
}'

Response 202

{
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "operation_url": "/v1/operations/6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "requested_action": "network_set",
  "status": "pending"
}