# Builds (/sdk/reference/builds)



{/* Generated by docs-site/scripts/generate-sdk-docs.ts — do not edit. */}

### `cancelBuild` [#cancelbuild]

`PUT /api/v0/organizations/{org}/pipelines/{pipeline}/builds/{number}/cancel`

Cancel a build

Cancels an in-flight build in-process (transitions non-terminal jobs and tears down their sandboxes). Idempotent: cancelling an already-terminal build is a no-op. Returns the reloaded build with its updated state.

```ts
import { cancelBuild } from "@harmont/cloud";
```

```ts
cancelBuild(options): RequestResult<CancelBuildResponse>
```

| Parameter  | In   | Type     | Description            |
| ---------- | ---- | -------- | ---------------------- |
| `org`      | path | `string` | The organization slug. |
| `pipeline` | path | `string` | The pipeline slug.     |
| `number`   | path | `number` | The build number.      |

**Returns** `CancelBuildResponse`

See [`PUT /api/v0/organizations/{org}/pipelines/{pipeline}/builds/{number}/cancel`](/api/reference/builds) for the full request and response schema.

### `createBuild` [#createbuild]

`POST /api/v0/organizations/{org}/pipelines/{pipeline}/builds`

Create a build

Creates a build for the pipeline and starts execution in-process. When `pipeline_ir` is supplied the IR is materialised directly; when it is absent the engine renders the pipeline's IR in a sandbox VM first (rendering never happens on the API host). A manual build against a pipeline that disallows manual builds yields 403; an IR that fails to render/parse/plan yields 422 (the build row is created with its error fields set).

```ts
import { createBuild } from "@harmont/cloud";
```

```ts
createBuild(options): RequestResult<CreateBuildResponse>
```

| Parameter  | In   | Type     | Description            |
| ---------- | ---- | -------- | ---------------------- |
| `org`      | path | `string` | The organization slug. |
| `pipeline` | path | `string` | The pipeline slug.     |

**Body** `CreateBuildRequest` (optional)

**Returns** `CreateBuildResponse`

See [`POST /api/v0/organizations/{org}/pipelines/{pipeline}/builds`](/api/reference/builds) for the full request and response schema.

### `createBuildBySource` [#createbuildbysource]

`POST /api/v0/organizations/{org}/builds`

Create a build by repo + source slug

Creates a build by addressing the pipeline through its repo-natural identity (`repo_name` + `source_slug`) rather than the org-global slug. This is the `hm run` path. Resolution, manual-build gating, billing, and IR handling are otherwise identical to `createBuild`. A repo/source slug that matches no pipeline yields 404.

```ts
import { createBuildBySource } from "@harmont/cloud";
```

```ts
createBuildBySource(options): RequestResult<CreateBuildBySourceResponse>
```

| Parameter | In   | Type     | Description            |
| --------- | ---- | -------- | ---------------------- |
| `org`     | path | `string` | The organization slug. |

**Body** `CreateRepoBuildRequest` (optional)

**Returns** `CreateBuildBySourceResponse`

See [`POST /api/v0/organizations/{org}/builds`](/api/reference/builds) for the full request and response schema.

### `getBuild` [#getbuild]

`GET /api/v0/organizations/{org}/pipelines/{pipeline}/builds/{number}`

Get a build

Returns the build identified by its pipeline-scoped number. An unknown number (or one in another pipeline) is reported as 404.

```ts
import { getBuild } from "@harmont/cloud";
```

```ts
getBuild(options): RequestResult<GetBuildResponse>
```

| Parameter  | In   | Type     | Description            |
| ---------- | ---- | -------- | ---------------------- |
| `org`      | path | `string` | The organization slug. |
| `pipeline` | path | `string` | The pipeline slug.     |
| `number`   | path | `number` | The build number.      |

**Returns** `GetBuildResponse`

See [`GET /api/v0/organizations/{org}/pipelines/{pipeline}/builds/{number}`](/api/reference/builds) for the full request and response schema.

### `getBuildLogToken` [#getbuildlogtoken]

`GET /api/v0/organizations/{org}/pipelines/{pipeline}/builds/{number}/log-token`

Mint a build-scoped log token

Returns a short-lived (\~1 hour) HMAC token the SSE log stream accepts, scoped to this build. Pass it as the stream's `token` query parameter.

```ts
import { getBuildLogToken } from "@harmont/cloud";
```

```ts
getBuildLogToken(options): RequestResult<GetBuildLogTokenResponse>
```

| Parameter  | In   | Type     | Description            |
| ---------- | ---- | -------- | ---------------------- |
| `org`      | path | `string` | The organization slug. |
| `pipeline` | path | `string` | The pipeline slug.     |
| `number`   | path | `number` | The build number.      |

**Returns** `GetBuildLogTokenResponse`

See [`GET /api/v0/organizations/{org}/pipelines/{pipeline}/builds/{number}/log-token`](/api/reference/builds) for the full request and response schema.

### `listBuilds` [#listbuilds]

`GET /api/v0/organizations/{org}/pipelines/{pipeline}/builds`

List a pipeline's builds

Returns the pipeline's builds, newest first, paginated.

```ts
import { listBuilds } from "@harmont/cloud";
```

```ts
listBuilds(options): RequestResult<ListBuildsResponse>
```

| Parameter  | In    | Type     | Description                                         |
| ---------- | ----- | -------- | --------------------------------------------------- |
| `org`      | path  | `string` | The organization slug.                              |
| `pipeline` | path  | `string` | The pipeline slug.                                  |
| `limit`    | query | `number` | Page size (1–100, default 50).                      |
| `cursor`   | query | `string` | Opaque cursor from a previous page's `next_cursor`. |

**Returns** `ListBuildsResponse`

See [`GET /api/v0/organizations/{org}/pipelines/{pipeline}/builds`](/api/reference/builds) for the full request and response schema.