Skip to main content
POST
Initiate Image Build

Rate Limit

150 requests per 60 seconds per IP and token.

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 (admins only). Platform builds must set visibility to 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