Skip to main content
POST
Start build (v2)

Authorizations

X-API-Key
string
header
required

Headers

Idempotency-Key
string

Optional team-scoped key for retrying the request. Use 1 to 255 lowercase ASCII letters, digits, or hyphens (a-z, 0-9, -), such as a lowercase UUID. The HTTP method, path, query, and request content identify the request. When idempotency is enabled, a matching retry of a completed request replays its status and body, including the IDs of any resources it created, without repeating the operation. A failure explicitly classified as safe to retry (Should-Retry: true) permits a fresh attempt with the same key and request. Only one attempt can run at a time. A different request returns 409 with error_code idempotency_request_mismatch. A matching request whose original has no recorded response yet and is within its expected response window returns 409 with error_code idempotency_in_progress. A matching request whose original has no recorded response and whose expected response deadline has passed or is unknown returns 422 with error_code idempotency_outcome_unknown. These conflicts and unknown outcomes do not execute the request again. If the key's record is unavailable or idempotency is misconfigured, the request returns 503; Should-Retry tells whether to retry with the same key. After the retention period expires, the key can start a new operation.

Required string length: 1 - 255
Pattern: ^[a-z0-9-]+$

Path Parameters

templateID
string
required
buildID
string
required

Body

application/json

Exactly one of fromImage or fromTemplate must be given and non-empty.

fromImage
string

Image to use as a base for the template build

Minimum string length: 1
fromTemplate
string

Template to use as a base for the template build

Minimum string length: 1
fromImageRegistry
object
force
boolean
default:false

Whether the whole build should be forced to run regardless of the cache

steps
object[]

List of steps to execute in the template build

startCmd
string

Start command to execute in the template after the build

readyCmd
string

Ready check command to execute in the template after the build

Response

The build has started