Builds

A build is one run of a pipeline. Each build has a number unique within its pipeline (the URL key) and a stable id UUID. Its aggregate state — scheduled, running, passed, failed, canceled, skipped — rolls up from the states of its jobs.

These endpoints trigger a build, read it, cancel a running one, list its artifacts, and mint the short-lived token the browser uses to stream live logs. The jobs that make up a build live under Jobs.

Create a build by repo + source slug

Authorization

bearer

AuthorizationBearer <token>

A Harmont session bearer token.

In: header

Path Parameters

org*string

The organization slug.

Request Body

application/json

Build attributes

TypeScript Definitions

Use the request body type in TypeScript.

branch*string

Source branch.

commit*string

Source commit SHA.

env?|

Build-level environment variables.

message?|

Optional build/commit message.

pipeline_ir?|

The pre-rendered v0 IR JSON the engine materialises into jobs. When absent/blank the engine renders the pipeline's IR in a sandbox VM instead.

repo_name*string

The worktree's repository as owner/repo (from its git remote).

source?|

How the build was triggered (e.g. api, ui). Defaults to api.

source_b64?|

Base64-encoded source tarball (the hm run local-code upload). When present, the API stores it at the build's key and derives the internal, runner-token-authenticated source_url.

source_slug*string

The in-repo pipeline name — the @hm.pipeline("…") slug.

Response Body

`application/json`

curl -X POST "https://api.harmont.dev/api/v0/organizations/string/builds" \  -H "Content-Type: application/json" \  -d '{    "branch": "string",    "commit": "string",    "repo_name": "string",    "source_slug": "string"  }'

{
  "branch": "string",
  "commit": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "error_code": "string",
  "error_message": "string",
  "finished_at": "2019-08-24T14:15:22Z",
  "message": "string",
  "number": 0,
  "pipeline_slug": "string",
  "scheduled_at": "2019-08-24T14:15:22Z",
  "source": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "state": "scheduled"
}

{
  "error": {
    "code": "string",
    "doc_url": "string",
    "message": "string",
    "request_id": "string",
    "type": "string"
  }
}

{
  "error": {
    "code": "string",
    "doc_url": "string",
    "message": "string",
    "request_id": "string",
    "type": "string"
  }
}

{
  "error": {
    "code": "string",
    "doc_url": "string",
    "message": "string",
    "request_id": "string",
    "type": "string"
  }
}

{
  "error": {
    "code": "string",
    "doc_url": "string",
    "message": "string",
    "request_id": "string",
    "type": "string"
  }
}

List a pipeline's builds

Authorization

bearer

AuthorizationBearer <token>

A Harmont session bearer token.

In: header

Path Parameters

org*string

The organization slug.

pipeline*string

The pipeline slug.

Query Parameters

limit?integer

Page size (1–100, default 50).

cursor?string

Opaque cursor from a previous page's next_cursor.

Response Body

`application/json`

curl -X GET "https://api.harmont.dev/api/v0/organizations/string/pipelines/string/builds"

{
  "data": [
    {
      "branch": "string",
      "commit": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "error_code": "string",
      "error_message": "string",
      "finished_at": "2019-08-24T14:15:22Z",
      "message": "string",
      "number": 0,
      "pipeline_slug": "string",
      "scheduled_at": "2019-08-24T14:15:22Z",
      "source": "string",
      "started_at": "2019-08-24T14:15:22Z",
      "state": "scheduled"
    }
  ],
  "next_cursor": "string"
}

{
  "error": {
    "code": "string",
    "doc_url": "string",
    "message": "string",
    "request_id": "string",
    "type": "string"
  }
}

Create a build

Authorization

bearer

AuthorizationBearer <token>

A Harmont session bearer token.

In: header

Path Parameters

org*string

The organization slug.

pipeline*string

The pipeline slug.

Request Body

application/json

Build attributes

TypeScript Definitions

Use the request body type in TypeScript.

branch*string

Source branch.

commit*string

Source commit SHA.

env?|

Build-level environment variables.

message?|

Optional build/commit message.

pipeline_ir?|

The pre-rendered v0 IR JSON the engine materialises into jobs. When absent/blank the engine renders the pipeline's IR in a sandbox VM instead.

source?|

How the build was triggered (e.g. api, ui). Defaults to api.

source_b64?|

Base64-encoded source tarball (expected to be gzipped; the API validates only that it is valid base64, not the archive format) — the hm run local-code upload path. When present, the API stores it at the build's key and derives the internal, runner-token-authenticated source_url; it takes precedence over any caller-supplied source_url.

source_sha256?|

SHA-256 of the source archive, verified by the sandbox before rendering (in-sandbox-render path). Defaults to empty when omitted.

source_url?|

URL to the build's source archive, fetched by the sandbox. Ignored when source_b64 is supplied (the API derives this internally).

Response Body

`application/json`

curl -X POST "https://api.harmont.dev/api/v0/organizations/string/pipelines/string/builds" \  -H "Content-Type: application/json" \  -d '{    "branch": "string",    "commit": "string"  }'

{
  "branch": "string",
  "commit": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "error_code": "string",
  "error_message": "string",
  "finished_at": "2019-08-24T14:15:22Z",
  "message": "string",
  "number": 0,
  "pipeline_slug": "string",
  "scheduled_at": "2019-08-24T14:15:22Z",
  "source": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "state": "scheduled"
}

{
  "error": {
    "code": "string",
    "doc_url": "string",
    "message": "string",
    "request_id": "string",
    "type": "string"
  }
}

{
  "error": {
    "code": "string",
    "doc_url": "string",
    "message": "string",
    "request_id": "string",
    "type": "string"
  }
}

{
  "error": {
    "code": "string",
    "doc_url": "string",
    "message": "string",
    "request_id": "string",
    "type": "string"
  }
}

{
  "error": {
    "code": "string",
    "doc_url": "string",
    "message": "string",
    "request_id": "string",
    "type": "string"
  }
}

Get a build

Authorization

bearer

AuthorizationBearer <token>

A Harmont session bearer token.

In: header

Path Parameters

org*string

The organization slug.

pipeline*string

The pipeline slug.

number*integer

The build number.

Response Body

`application/json`

curl -X GET "https://api.harmont.dev/api/v0/organizations/string/pipelines/string/builds/0"

{
  "branch": "string",
  "commit": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "error_code": "string",
  "error_message": "string",
  "finished_at": "2019-08-24T14:15:22Z",
  "message": "string",
  "number": 0,
  "pipeline_slug": "string",
  "scheduled_at": "2019-08-24T14:15:22Z",
  "source": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "state": "scheduled"
}

{
  "error": {
    "code": "string",
    "doc_url": "string",
    "message": "string",
    "request_id": "string",
    "type": "string"
  }
}

Cancel a build

Authorization

bearer

AuthorizationBearer <token>

A Harmont session bearer token.

In: header

Path Parameters

org*string

The organization slug.

pipeline*string

The pipeline slug.

number*integer

The build number.

Response Body

`application/json`

curl -X PUT "https://api.harmont.dev/api/v0/organizations/string/pipelines/string/builds/0/cancel"

{
  "branch": "string",
  "commit": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "error_code": "string",
  "error_message": "string",
  "finished_at": "2019-08-24T14:15:22Z",
  "message": "string",
  "number": 0,
  "pipeline_slug": "string",
  "scheduled_at": "2019-08-24T14:15:22Z",
  "source": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "state": "scheduled"
}

{
  "error": {
    "code": "string",
    "doc_url": "string",
    "message": "string",
    "request_id": "string",
    "type": "string"
  }
}

Mint a build-scoped log token

Authorization

bearer

AuthorizationBearer <token>

A Harmont session bearer token.

In: header

Path Parameters

org*string

The organization slug.

pipeline*string

The pipeline slug.

number*integer

The build number.

Response Body

`application/json`

curl -X GET "https://api.harmont.dev/api/v0/organizations/string/pipelines/string/builds/0/log-token"

{
  "expires_at": "2019-08-24T14:15:22Z",
  "token": "string"
}

{
  "error": {
    "code": "string",
    "doc_url": "string",
    "message": "string",
    "request_id": "string",
    "type": "string"
  }
}

201application/json

402application/json

403application/json

404application/json

422application/json

200application/json

404application/json

201application/json

402application/json

403application/json

404application/json

422application/json

200application/json

404application/json

200application/json

404application/json

200application/json

404application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`