SMsmolmachines
machines

List machines.

Changed on

Returns every machine in the caller's tenant. Requires the machine:read scope.

get/v1/machines

Request

Query parameters

labelstring[]

Only machines carrying this label, as key=value. Repeat to require several labels (all must match).

Response

List machines

archstring nullable

The machine's actual CPU arch (arm64/amd64): the arch of the node it runs on, falling back to source.arch (a .smolmachine's pinned arch) when the machine is unplaced or its node is gone. None only when neither is known. Lets the console show an arch badge for every machine, including ones whose source pinned no arch. Populated by the server's machine_info.

autoStopSecondsinteger nullable
branchGenerationinteger nullable

Zero for a root branch source, one for its children, and so on.

branchState'mutable' | 'freezing' | 'frozen'

User-visible state of a live-RAM checkpoint.

branchableboolean

Whether this machine can produce live copy-on-write branches.

checkpointState'mutable' | 'freezing' | 'frozen'

User-visible state of a live-RAM checkpoint.

createdAtstring required
createdBystring nullable

The account id of whoever created the machine; null when nobody is.

envobject required
ephemeralboolean required
errorstring nullable

When [Self::state] is "error", a human-readable reason the machine failed — the latest control-plane error event (e.g. "start failed: …", "auto-start failed: …", or "machine stuck in creating state"). null for machines that are not in an error state. Gives clients something actionable instead of a bare error with no explanation.

forkGenerationinteger nullable

Legacy alias for branch_generation.

forkableboolean

Legacy alias for branchable.

idstring required
labelsobject

Labels set at create time (or inherited from a branch source).

lastActivityAtstring nullable
namestring nullable
parentMachineIdstring nullable

Immediate live-RAM checkpoint this machine was branched from. null for ordinary machines and root checkpoints.

readyboolean

Whether the machine is READY to do work. state == "started" only means the VM process launched on the node — the guest OS and your in-VM workload still need a moment to boot. ready becomes true once the guest agent is reachable (an exec/connect will succeed) and, if the machine publishes a port, that port is accepting connections. Wait for ready (poll GET /v1/machines/:id) before expecting an in-guest worker to have started or before connecting to it — do NOT act on started alone.

readyAtstring nullable

When a probe first observed this machine serving (RFC3339), or null.

This is a readiness gate, not a boot timestamp: it is stamped when the published port accepts a connection (or, for a machine with no published ports, when its guest agent answers), and it is cleared on every stop so a restart must re-prove itself. A short-lived machine may finish its whole life as null here without anything being wrong. Use createdAt if you want when the machine came into existence.

rootBranchIdstring nullable

Root source for this live branch lineage. A root points to itself; ordinary machines have no lineage.

rootCheckpointIdstring nullable

Legacy alias for root_branch_id.

statestring required
ttlSecondsinteger nullable
updatedAtstring required
urlstring nullable

Public ingress URL for the machine's first published port, when the machine is started and the control plane has a public base URL configured. null for stopped machines, machines with no published port, or when the deployment exposes no public base URL.

workdirstring nullable

Changes

  • bc31fc04a568Revision changes
    • breaking

      added subschema #1 subschema #2 to the / response property oneOf list for the response status

    • breaking

      added subschema #1 subschema #2 subschema #3 to the / response property oneOf list for the response status

    • info

      the endpoint scheme security ApiKeyAuth was added to the API

    • info

      added the new optional query request parameter label

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      removed subschema #1 subschema #2 from the / response property oneOf list for the response status

    • info

      removed subschema #1 subschema #2 subschema #3 from the / response property oneOf list for the response status