Skip to main content
POST
Initiate Image Build

Rate Limit

150 requests per 60 seconds per IP and token. Source builds also have per-image account limits.

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 an image from a Dockerfile or public source.

image_name
string | null

Destination image name. Required for Dockerfile builds.

image_tag
string | null

Destination image tag. Required for Dockerfile builds.

sourceImage
string | null

Public source image reference, or comma-separated references, to convert directly into VM images

dockerfile_path
string
default:Dockerfile

Dockerfile builds only: path within the uploaded build context

platform
enum<string>
default:linux/amd64

Target platform. VM artifact builds currently require linux/amd64.

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. Explicit platform builds are admin-only. Docker Hub source builds become PUBLIC platform images automatically. Platform images 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 started by this request

upload_url
string | null

Dockerfile builds only: presigned build-context upload URL; null for source builds

expires_in
integer | null

Dockerfile builds only: upload URL validity in seconds; null for source builds

visibility
enum<string>
default:PRIVATE

Effective visibility for the image when the build completes

Available options:
PRIVATE,
PUBLIC