---
title: "Start a build."
method: POST
path: "/v1/build"
tags: ["Build"]
---

# Start a build.

`POST /v1/build`

## Request

- Base URL: `https://api.scalix.world`
- URL: `https://api.scalix.world/v1/build`
- Auth: HTTP bearer

Starts a container image build and returns the build record.

For a private repository, either install the Scalix GitHub App for the
project (builds then authenticate themselves) or pass `auth_token`.

## Request body

- BuildCreateRequest: A source build to start.
  - `source_type` string, required: Where the source comes from: `git` or `tarball`.
  - `source_url` string, nullable: Repository or archive URL. Must be reachable from the builder.
  - `source_ref` string, nullable: Branch, tag or commit to build. Defaults to `main`. This is the branch field: `git_ref` is not recognised and is ignored if sent.
  - `auth_token` string, password, nullable: Credential for a private repository, used as the password in the clone URL. A fine-grained token with read-only Contents access on that one repository is enough. It is held in memory for the build only: never stored, never written to build logs or error messages. Omit this when the Scalix GitHub App is installed for the project - a short-lived installation token is then minted per build and injected automatically.
  - `dockerfile_path` string, nullable: Path to the Dockerfile within the source tree. Auto-detected if omitted.
  - `image_tag` string, nullable: Tag for the resulting image. Auto-generated if omitted.
  - `build_args` object, nullable: Build-time ARGs passed to the builder. Project environment variables are merged in as well; values sent here win. These are stored on the build record and readable back from `GET /v1/build/{id}`, so treat them as non-secret: use them for things like a public API base URL, not tokens.
  - `timeout_seconds` integer, nullable: Build timeout in seconds. Default 600, maximum 3600.

## Response `200`

Build started

## Other responses

- `401`: Missing or invalid API key
- `500`: Internal error

---

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