---
title: "Cancel a build"
method: POST
path: "/v1/builds/{buildId}/cancel"
tags: ["Builds"]
---

# Cancel a build

`POST /v1/builds/{buildId}/cancel`

## Request

- Base URL: `https://api.spacefast.com`
- URL: `https://api.spacefast.com/v1/builds/{buildId}/cancel`
- Auth: HTTP bearer

Cancels a queued, uploading, or running build and returns the latest build state. Canceling is idempotent: a build already in a terminal state comes back unchanged.

## Path parameters

- `buildId` string, required

## Response `200`

Response for status 200

- object
  - `$schema` string, uri: Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.
  - `data` object, required
    - `capture` object: URL capture progress and advisory evidence; absent for other inputs.
      - `state` string, required
      - `previewSummary` object
      - `progress` object
      - `archiveHash` string
    - `id` string, required: Build id (`bld_`); opaque and never derived from a version id.
    - `spaceId` string, required: Space (`spc_`) the build produces a version for.
    - `status` 'waiting_for_source' | 'uploading_source' | 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled' | 'skipped', required: Build lifecycle status.
    - `input` union, required: Public build input. Internal clone URLs and provider source references are hidden.
      - object
        - `kind` 'url', required
        - `sourceUrl` string, uri, required
      - object
        - `kind` 'archive', required: Build from an uploaded source archive.
      - object
        - `kind` 'repository', required: Build from repository source where clone credentials are not exposed.
        - `ref` string, required: Branch, tag, or ref to build.
        - `commit` string: Exact commit built, once resolved.
        - `branch` string: Branch name when available.
        - `pullRequestNumber` integer
    - `source` object, nullable, required: Publish provenance as declared at build start (client, git ref data, publish message). Present on failed and running builds too; the produced version's `source` is the authoritative copy once one exists. Null when nothing was declared.
      - `kind` 'direct_upload' | 'cli' | 'dashboard' | 'api' | 'git' | 'import' | 'agent' | 'build' | 'variable_update' | 'config_update', required: How this version was produced.
      - `client` string: Publishing client attribution, for example `spacefast-cli/1.2.3`.
      - `branch` string: Git branch the publish came from.
      - `commit` string: Git commit SHA the publish came from.
      - `message` string: Plain-language description of the publish (the version changelog entry, commit message, or release note). This is THE spelling for the publish description; the version files-diff API is the fallback when none is given.
      - `dirty` boolean: Whether the working tree had uncommitted changes at publish time.
      - `metadata` object: Additional provenance (repository, CI run URL, workflow, actor, ...).
      - `git` object
        - `repository` string, nullable
        - `repositoryFullName` string, nullable
        - `repositoryUrl` string, nullable
        - `ref` string, nullable
        - `branch` string, nullable
        - `branchAliasUrl` string, nullable
        - `commit` string, nullable
        - `commitSha` string, nullable
        - `pullRequestNumber` number, nullable
    - `settingsSnapshot` object, required: Resolved build settings. Builds persist this as an immutable `settingsSnapshot`.
      - `rootDirectory` string, nullable, required
      - `installDirectory` string, nullable, required
      - `installCommand` string, nullable, required
      - `buildCommand` string, nullable, required
      - `outputDirectory` string, nullable, required
      - `ignoredBuildCommand` string, nullable, required
      - `frameworkPreset` string, nullable, required
      - `platformPreset` string, nullable, required
      - `allowUnsupportedPlatformFeatures` boolean, required
      - `timeoutSeconds` integer, required
    - `target` object, required: Where a successful build should publish or run in preview mode.
      - `channel` string, nullable, required: Channel to promote when the build succeeds. production is an alias for live; null means no automatic promotion.
      - `preview` boolean, required: Whether the build targets preview behavior.
    - `retryOfBuildId` string, nullable, required: Original build retried by this build.
    - `producedVersionId` string, nullable, required: Version (`ver_`) minted by a successful build; null otherwise.
    - `reusedVersionId` string, nullable, required: Existing version reused by a successful no-change build; null otherwise.
    - `diagnostics` object[], required
      - `code` string, required: Stable snake_case diagnostic code naming the public contract that produced it.
      - `severity` 'info' | 'warning' | 'error', required: How actionable the diagnostic is.
      - `message` string, required: Human-readable explanation with enough detail to act on.
      - `path` string, nullable: Artifact path the diagnostic points at, for example "_headers:12", when one exists.
      - `provider` 'infra' | 'dns' | 'registrar' | 'runtime', nullable: Upstream system the diagnostic originated from, when not Spacefast itself.
      - `details` object, nullable: Machine-readable context for the diagnostic code.
      - `fix` string, nullable: Concrete, agent-actionable remediation hint, when one can be derived.
      - `retryable` boolean, nullable: Whether retrying the same operation can resolve this diagnostic without the caller changing anything.
    - `createdAt` string, date-time, required
    - `startedAt` string, date-time, nullable, required: When the runner picked the build up.
    - `finishedAt` string, date-time, nullable, required: When the build reached a terminal state.

## Other responses

- `default`: Problem details (RFC 9457). Any 4xx/5xx response is one `application/problem+json` document.

---

[API](https://skmtc.dev/spacefast/apis/spacefast-api.md) · [All operations](https://skmtc.dev/spacefast/apis/spacefast-api/llms.txt) · [OpenAPI document](https://skmtc.dev/spacefast/apis/spacefast-api/revisions/bd165bc7c983?raw)