Skip to main content
POST
Initiate Image Build

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request model for building or transferring an image.

image_name
string | null

Image name (e.g., 'myapp'). Required for build-context builds; optional for transfers.

image_tag
string | null

Image tag (e.g., 'v1.0.0'). Required for build-context builds; optional for transfers.

dockerfile_path
string
default:Dockerfile

Path to Dockerfile within build context

sourceImage
string | null

Existing public image reference, or comma-separated image references, to transfer instead of uploading a build context

platform
enum<string>
default:linux/amd64

Target platform (linux/amd64 or linux/arm64)

Available options:
linux/amd64,
linux/arm64
teamId
string | null

Team ID if building image in team context

visibility
enum<string>
default:INHERIT

Visibility override to apply when the build completes. INHERIT preserves existing tag visibility or defaults new tags to PRIVATE.

Available options:
INHERIT,
PRIVATE,
PUBLIC
ownerScope
enum<string> | null

Set to 'platform' to build an org-less platform image. Public Docker Hub source transfers are promoted to platform scope automatically; other platform builds remain admin-only. Platform images are PUBLIC and cannot set teamId.

Available options:
platform
Allowed value: "platform"

Response

Successful Response

Response model for initiating image build.

build_id
string
required

Build ID for tracking

fullImagePath
string
required

User-facing Prime image reference, preferring owner slug when available

buildIds
string[]

Build IDs for this request. Multiple IDs are returned for comma-separated transfers.

upload_url
string | null

Presigned URL to upload build context (tar.gz)

expires_in
integer | null

URL validity in seconds

visibility
enum<string>
default:PRIVATE

Effective visibility for the image when the build completes

Available options:
PRIVATE,
PUBLIC