v4

latestOpenAPI 3.1.0Apache-2.0raw.githubusercontent.com2026-05-09283767.7 KB

builds

Get build status

Returns the current state of a build. While the build is in progress, status is pending or running and progress contains a human-readable string describing the current phase (e.g. Pulling image, Building (3 steps), Settling VM).

On success, status is completed and snapshotId references a ready snapshot — fetch it via GET /v1/snapshots/{id}. On failure, status is failed and error carries the worker's diagnostic.

get/v1/builds/{id}

Response

Build status

idstring required

Build ID (UUID). Use this to poll status.

namestring

statusstring required

Current state. Known values: pending (accepted, not yet started), running (worker is executing), completed (snapshot is ready), failed (build did not produce a snapshot). Additional values may be introduced in future server versions; clients should treat unknown values as "in progress" rather than as hard errors.

snapshotIdstring

Set when status is completed. Fetch the corresponding Snapshot record via GET /v1/snapshots/{id}.

imageRefstring required

progressstring

Human-readable phase string while the build runs (e.g. creating build VM, buildah pull, buildah bud, applying image, settling VM, creating snapshot). Not present after a terminal status.

errorstring

Set when status is failed. Diagnostic from the worker (truncated to ~4 KiB).

createdAtstring date-time required