# Cancel a build

Cancels a build that is waiting for source, uploading, queued, or running, and returns it in its new state. A build that already settled comes back unchanged, so repeating the call is safe.

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

## Authorization

`Authorization` Bearer token · header required

`Authorization: Bearer <token>` with an API key (`sfa_` prefix), an OAuth access token, a session token, or a Space machine credential (`sfm_` prefix).

## Path parameters

`buildId` string required

## Responses

### 200 Response for status 200

`$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

Show properties Hide properties

`id` string required

Build ID (`bld_` prefix). Opaque, and never derived from a version ID.

`spaceId` string required

Space (`spc_` prefix) the build publishes into.

`status` string required

Where the build is in its lifecycle. `skipped` means the ignored build command decided no build was needed.

Allowed: `waiting_for_source` `uploading_source` `queued` `running` `succeeded` `failed` `canceled` `skipped`

`input` object required

The source a build ran against, with clone URLs and repository connection identifiers removed.

Show properties Hide properties

One of:

- object
  
  `kind` string required
  
  The build ran against an uploaded source archive.
- object
  
  `kind` string required
  
  The build ran against repository source.

`ref` string required

Branch, tag, or ref the build checked out.

`commit` string

Commit the ref resolved to. Absent until resolved.

`branch` string

Branch the ref belongs to, when it is known.

`pullRequestNumber` integer

Pull request the build was raised for. Absent for builds off a plain branch.

max 9007199254740991

`source` object | any required

Publish provenance as declared when the build started: client, git ref data, and publish message. It is present on running and failed builds, which have no version yet; once a version exists its own `source` is authoritative. Null when nothing was declared.

default: null

Show properties Hide properties

Any of:
- object
  
  `kind` string required
  
  How this version was produced. `variable_update` and `config_update` mark republishes Spacefast makes on its own when a variable or a setting changed; the rest name what published.

Allowed: `direct_upload` `cli` `dashboard` `api` `git` `import` `agent` `build` `variable_update` `config_update`

`client` string

Client and version that published, for example `spacefast-cli/1.2.3`.

max length 255

`branch` string

Git branch the publish was made from.

max length 255

`commit` string

Git commit the publish was made from.

max length 64

`message` string

One-line description of the publish, shown as the version's headline in the dashboard. There is no separate changelog field. The CLI fills it from the git commit message when it can.

max length 2000

`dirty` boolean

Whether the working tree had uncommitted changes when the publish was made.

`metadata` object

Extra provenance as string pairs, such as a repository, a CI run URL, a workflow, or an actor.

`git` object

Show properties Hide properties

`repository` string | any

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`repositoryFullName` string | any

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`repositoryUrl` string | any

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`ref` string | any

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`branch` string | any

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`branchAliasUrl` string | any

URL the branch alias serves this version on. Filled in on read, not by the publisher.

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`commit` string | any

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`commitSha` string | any

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`pullRequestNumber` number | any

GitHub pull request this publish belongs to. Filled in on read, not by the publisher.

Show properties Hide properties

Any of:
- number
  
  `number`
- any
  
  `any`

`settingsSnapshot` object required

Build settings after saved values and per-run overrides are merged. A build freezes these at creation and runs against them for its whole life.

Show properties Hide properties

`rootDirectory` string | any required

Directory the build runs in, relative to the source root. Null builds at the root.

default: null

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`installDirectory` string | any required

Directory dependencies install into, relative to the source root. Null installs in the build directory.

default: null

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`installCommand` string | any required

Command that installs dependencies. Null lets the build runner pick one.

default: null

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`buildCommand` string | any required

Command that produces the output. Null lets the build runner pick one.

default: null

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`outputDirectory` string | any required

Directory the built output is collected from, relative to the build directory. Null lets the build runner detect it.

default: null

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`ignoredBuildCommand` string | any required

Command run before the build to decide whether the build is needed. Exiting 0 ends the build as `skipped`; any other exit code continues. Null always builds.

default: null

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`frameworkPreset` string | any required

Framework the source builds with, for example `next` or `vite`. Null lets the build runner detect it.

default: null

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`platformPreset` string | any required

Platform build convention the source follows, for example `vercel` or `netlify`. Null lets the build runner detect it.

default: null

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`allowUnsupportedPlatformFeatures` boolean required

Runs the build even when the source declares platform features Spacefast does not support. Defaults to `false`, which refuses those sources.

default: false

`timeoutSeconds` integer required

Wall-clock budget for the run, in seconds. Between 60 and 7200; defaults to 900.

min 60 · max 7200 · default: 900

`target` object required

Where a successful build's version goes.

Show properties Hide properties

`channel` string | any required

Channel the produced version is promoted to when the build succeeds. Null publishes the version without promoting it.

default: null

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`preview` boolean required

Marks the run as a preview build. The build environment is exported as a preview, and a preview build only supersedes other preview builds on the same branch.

default: false

`retryOfBuildId` string | any required

Build this run retries. Null when it is not a retry.

default: null

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`producedVersionId` string | any required

Version (`ver_` prefix) this build minted. Null until a build succeeds and mints one.

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`reusedVersionId` string | any required

Version the build reused because the output was unchanged. Null otherwise.

default: null

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`diagnostics` object["] required
default: []

Show properties Hide properties

Array of `object`

`code` string required

Stable snake_case code for this diagnostic.

`severity` string required

How serious the diagnostic is.

Allowed: `info` `warning` `error`

`message` string required

What happened, in a sentence a person can act on.

`path` string | any

File or artifact path the diagnostic refers to, with a line number when known, for example `_headers:12`. Absent when it applies to the whole resource.

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`provider` string | any

Upstream system that raised the diagnostic. Absent when Spacefast raised it.

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`details` object | any

Machine-readable context keyed by the diagnostic code.

Show properties Hide properties

Any of:
- object
  
  `object`
- any
  
  `any`

`fix` string | any

What to change to clear the diagnostic. Absent when there is no known fix.

Show properties Hide properties

Any of:
- string
  
  `string`
- any
  
  `any`

`retryable` boolean | any

True when repeating the same operation unchanged can clear the diagnostic.

Show properties Hide properties

Any of:
- boolean
  
  `boolean`
- any
  
  `any`

`createdAt` string <date-time> required

ISO 8601 timestamp when the build was created.

`matches` ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

`startedAt` string <date-time> | any required

ISO 8601 timestamp when the build runner started the run. Null until it does.

Show properties Hide properties

Any of:
- string<date-time>
  
  `string<date-time>`
- any
  
  `any`

`finishedAt` string <date-time> | any required

ISO 8601 timestamp when the build reached a terminal state. Null while it is still in flight.

Show properties Hide properties

Any of:
- string<date-time>
  
  `string<date-time>`
- any
  
  `any`

### default
Error. Every 4xx and 5xx response is one RFC 9457 problem document served as `application/problem+json`.

`$schema` string <uri>

Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.

`type` string required

URL of the documentation page for this error. Derived from `code`.

`title` string required

Human-readable name of the error type. Derived from `code`.

`status` integer required

HTTP status of the response, repeated in the body.

min -9007199254740991 · max 9007199254740991

`detail` string required

What went wrong in this request.

`code` string required

Stable snake_case error code. Match on this, not on `detail`.

`pointer` string

RFC 6901 JSON Pointer to the request field or batch entry that failed, for example `/files/37/path`. Present on validation failures.

`details` object

Machine-readable context keyed by the error code.

`suggestions` string[]

Recovery steps safe to show to a person.

`next` string[]

Commands or API requests to run next, usable as written.

`requestId` string required

ID of this request, from the `X-Request-Id` header or generated. Quote it when contacting support.

## Try it

### Server

Base URL: https://api.spacefast.com

Custom base URL

Overrides the selected server when set.

## Authorization

Bearer token

Remember on this device

Include my values in samples

## Parameters

`buildId` path*

### Send

#### Request

### cURL

```bash
curl -X POST "https://api.spacefast.com/v1/builds/string/cancel" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### JavaScript

```javascript
const response = await fetch("https://api.spacefast.com/v1/builds/string/cancel", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});
```

### Python

```python
import requests

response = requests.post(
    "https://api.spacefast.com/v1/builds/string/cancel",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)
```

### Response
### 200 default

```json
{
  "$schema": "http://example.com",
  "data": {
    "id": "string",
    "spaceId": "string",
    "status": "waiting_for_source",
    "input": {
      "kind": "archive"
    },
    "source": null,
    "settingsSnapshot": {
      "rootDirectory": null,
      "installDirectory": null,
      "installCommand": null,
      "buildCommand": null,
      "outputDirectory": null,
      "ignoredBuildCommand": null,
      "frameworkPreset": null,
      "platformPreset": null,
      "allowUnsupportedPlatformFeatures": false,
      "timeoutSeconds": 900
    },
    "target": {
      "channel": null,
      "preview": false
    },
    "retryOfBuildId": null,
    "producedVersionId": "string",
    "reusedVersionId": null,
    "diagnostics": [],
    "createdAt": "2019-08-24T14:15:22Z",
    "startedAt": "2019-08-24T14:15:22Z",
    "finishedAt": "2019-08-24T14:15:22Z"
  }
}
```

```json
{
  "$schema": "http://example.com",
  "type": "string",
  "title": "string",
  "status": -9007199254740991,
  "detail": "string",
  "code": "string",
  "pointer": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "suggestions": [
    "string"
  ],
  "next": [
    "string"
  ],
  "requestId": "string"
}
```