API reference

Operations API

Read an operation's status and result, or follow its persisted events as server-sent events.

Get an operation: GET /v1/operations/{operation_id}
Stream operation events: GET /v1/operations/{operation_id}/events

Get an operation

GET /v1/operations/{operation_id}

A stop reports who asked for it in stop_reason: api, auto_stop, billing, idle_sleep, suspension (the organization was suspended), abuse (the sustained-CPU guard stopped a trial machine), or organization_deleted. See Operations and idempotency.

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
`operation_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`	—	`OperationDto`
`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/operations/$OPERATION_ID" \
  -H "Authorization: Bearer $VMYARD_API_KEY"

Response 200

{
  "attempt_count": 0,
  "completed_but_unchanged": false,
  "error_code": "string",
  "exec_result": {
    "cancelled": false,
    "exit_code": 0,
    "stderr_base64": "string",
    "stdout_base64": "string",
    "timed_out": false,
    "truncated": false
  },
  "file_ranges": [
    {
      "data_base64": "string",
      "missing": false,
      "offset": 0,
      "path": "notes/todo.txt",
      "size": 0
    }
  ],
  "id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "kind": "stop",
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "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"
  },
  "status": "pending",
  "stop_reason": "idle_sleep"
}

Stream operation events

GET /v1/operations/{operation_id}/events

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
`operation_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.
`Last-Event-ID`	header	`integer \| null`	No	Resume strictly after this persisted monotonic event ID

Responses

Status	Description	Body
`200`	Persisted history followed by live events	`text/event-stream`
`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`
`422`	Invalid request (`invalid_request`); `field_errors` names the fields.	`ProblemDetails`

Request

curl "$VMYARD_API_URL/v1/operations/$OPERATION_ID/events" \
  -N \
  -H "Authorization: Bearer $VMYARD_API_KEY"