Sign in

v5

latestOpenAPI 3.0.2raw.githubusercontent.com2026-08-015725.9 KB
builds

Cancel Build

Cancel a build.

Handles both active builds (delegated to Build Coordinator) and pre-dispatch builds (cancelled FS-only via an atomic row lock).

The operation is idempotent with respect to terminal state. When the build has already reached a terminal state (cancelled, completed, failed, or timed_out) — whether Build Coordinator reports it or the local task row records it — the response is still 200 and the status field carries that terminal state. Coordinator statuses are normalized into the effective vocabulary before they are surfaced: BC's timed_out surfaces as timed_out, the same word a subsequent GET reconstructs from the footprint the callback path persists (status='failed' + error_class='timeout'), so the two surfaces always agree.

Cancelling a pre-dispatch build permanently retires its identity tuple: uq_factory_build_identity dedup treats the cancelled row like any other terminal build, so a later event expanding to the same identity inserts nothing. Recovery is manual by design — a cancel that ambient event traffic could overturn would not be a cancel.

Outcomes: 200 — Build cancelled, or already terminal. BuildResponse.status reflects the effective state. 404 — No build with the given ID. 502 — Build Coordinator unreachable or returned an unexpected error; or the coordinator does not know the build yet because its dispatch is in flight (the worker commits its claim before the HTTP submit), or no longer knows it (coordinator restart or purge). In every 502 case the correct client action is retry with backoff.

An audit log line is emitted on every path, including unhandled exceptions (outcome=internal_error).

delete/api/v1/factory/builds/{build_id}

Path parameters

build_idinteger required

Response

Build cancelled or already terminal; status field carries the outcome

build_idinteger required
status'pending' | 'running' | 'completed' | 'failed' | 'timed_out' | 'cancelled' required

Effective status of a build, derived server-side and never stored.

A dispatched build's task lifecycle is authoritative, with timed_out reconstructed from a failed task whose error class is 'timeout'; a build cancelled before dispatch is cancelled; an undispatched, uncancelled build is pending. These six values are exactly what the derivation can emit; emittable, filterable, and the whole vocabulary are the same set. The member order here is the documentation order.

source_repo_urlstring required
source_commit_shastring required
nixpkgs_revisionstring required
systemstring required
attr_pathstring required
build_typestring required
catalog_namestring required
exit_codeinteger nullable
created_atstring date-time required