Create a container image build record.

This multipart request accepts exactly one image source. Provide context_archive to stream a tar.gz build context to the configured cloud build provider, or provide image_url to register an existing tagged image as an immediately successful build without invoking the provider. build_args and platform apply only to archive builds.

Exactly one of agent_name or agent_id must identify the target agent. agent_name creates a new build-only agent and must be unused. agent_id targets an existing agent. Archive builds normally return in a queued or running state; prebuilt images can immediately be passed to Cloud Deploy using the returned build ID. Archives must be non-empty and no larger than 500 MB.

Retrieve a single build by its ID, including its current lifecycle status.

Because builds run asynchronously after submission, the status returned here reflects the latest known state and may still be queued or running; call this endpoint again to observe progression to a terminal state such as success, failed, cancelled, or timed out. Responds with a not-found error if no such build exists for the caller's account.

List container image build records for the caller's account as a paginated collection.

Each entry is one individual build with its current lifecycle status; pass agent_name, source_commit, or working_tree_hash to return only matching builds. Archived builds are excluded, and results are limited to builds the caller is permitted to read. Use this to enumerate individual builds; to instead list agents that have been built but not yet deployed, use GET /v5/builds/undeployed.

Request cancellation of a build and return 202 Accepted.

Cancellation runs asynchronously: the endpoint verifies the build exists and then hands it off to a background workflow that marks the build as cancelling, asks the cloud build provider to stop it, and polls until the build reaches a terminal state before recording the final status. Only builds that are still queued or running are actually cancelled; if the build has already finished, or cancellation is already in progress, the request is still accepted but has no effect. The returned record reflects the build's state at the time of the call, so it will not yet show the pending cancellation. The request is rejected if no such build exists for the caller's account.

List agents that exist only as cloud builds and have no healthy deployment yet.

Unlike listing builds, this aggregates by agent: it returns one entry per distinct agent name whose builds have never reached a healthy deploy, each carrying that agent's most recent build and its total build count. The result is a plain list (not paginated) and is limited to builds the caller is permitted to read. Use this to surface agents that were built but still need to be deployed; use GET /v5/builds when you need the individual build records instead.