Initiate Image Build

Initiate an image build process.

Returns a presigned URL to upload the build context (tar.gz file). After uploading, call /images/build//start to begin the build.

POST /api/v1/images/build

Initiate Image Build

cURL

curl --request POST \
  --url https://api.primeintellect.ai/api/v1/images/build \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "image_name": "<string>",
  "image_tag": "<string>",
  "dockerfile_path": "Dockerfile",
  "sourceImage": "<string>",
  "platform": "linux/amd64",
  "teamId": "<string>",
  "visibility": "INHERIT",
  "ownerScope": "platform"
}
'

201

{
  "build_id": "<string>",
  "fullImagePath": "<string>",
  "buildIds": [
    "<string>"
  ],
  "upload_url": "<string>",
  "expires_in": 123,
  "visibility": "PRIVATE"
}

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

201

application/json

Successful Response

BuildImageResponse

BulkImageTransferResponse

Response model for initiating image build.

build_id · string · required

Build ID for tracking

fullImagePath · string · required

Full image path with user ID

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