Submit container image build

Create a container image build record.

This multipart request accepts exactly one image source. Provide context_archive to stream a tar.gz build context to the configured cloud build provider, or provide image_url to register an existing tagged image as an immediately successful build without invoking the provider. build_args and platform apply only to archive builds.

Exactly one of agent_name or agent_id must identify the target agent. agent_name creates a new build-only agent and must be unused. agent_id targets an existing agent. Archive builds normally return in a queued or running state; prebuilt images can immediately be passed to Cloud Deploy using the returned build ID. Archives must be non-empty and no larger than 500 MB.

POST /v5/builds

Submit container image build

cURL

curl --request POST \
  --url https://api.egp.scale.com/v5/builds \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-key: <api-key>' \
  --form 'image_name=<string>' \
  --form 'context_archive=<string>' \
  --form 'image_url=<string>' \
  --form 'agent_name=<string>' \
  --form 'agent_id=<string>' \
  --form image_tag=latest \
  --form 'build_args=<string>' \
  --form 'source_repo=<string>' \
  --form 'source_commit=<string>' \
  --form 'source_ref=<string>' \
  --form 'source_subpath=<string>' \
  --form 'working_tree_hash=<string>' \
  --form source_dirty=true

200

{
  "id": "<string>",
  "cloud_provider_build_id": "<string>",
  "agent_name": "<string>",
  "image_name": "<string>",
  "image_tag": "<string>",
  "build_status": "queued",
  "source_repo": "<string>",
  "source_commit": "<string>",
  "source_ref": "<string>",
  "source_subpath": "<string>",
  "working_tree_hash": "<string>",
  "source_dirty": true,
  "account_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "created_by": {
    "id": "<string>",
    "type": "user",
    "object": "identity"
  },
  "object": "agentex_cloud_build",
  "agent_id": "<string>",
  "image_url": "<string>",
  "image_digest": "<string>",
  "build_start_time": "2023-11-07T05:31:56Z",
  "build_end_time": "2023-11-07T05:31:56Z"
}

Authorizations

x-api-key · string · header · required

Headers

x-selected-account-id · string | null

Body

multipart/form-data

image_name · string · required

Name for the built image

context_archive · file | null

tar.gz archive containing the build context (Dockerfile and any files needed for the build)

image_url · string | null

Existing tagged image to register instead of running a build

agent_name · string | null

Name of the brand-new agent to create from this build

agent_id · string | null

ID of the existing agent this build targets

image_tag · string · default: latest

Tag for the built image

build_args · string | null

JSON string of build arguments

platform · enum<string> | null

Target platform for the Docker build. Defaults to the build host's native architecture when not specified.

Available options: linux/amd64, linux/arm64, linux/arm/v7

source_repo · string | null

Normalized git remote the build context came from.

Maximum string length: 2048

source_commit · string | null

Git commit the build context was at.

Maximum string length: 64

Pattern: ^(?:[0-9a-fA-F]{40}|[0-9a-fA-F]{64})$

source_ref · string | null

Git branch or tag for source_commit.

Maximum string length: 4096

source_subpath · string | null

Build-context path relative to the repo root.

Maximum string length: 4096

working_tree_hash · string | null

Deterministic SHA-256 content hash of the build inputs.

Maximum string length: 64

Pattern: ^[0-9a-fA-F]{64}$

source_dirty · boolean | null

Whether the work tree had uncommitted changes at build time.

Response

200

application/json

Successful Response

id · string · required

The unique identifier of the entity.

cloud_provider_build_id · string · required

The unique identifier of the build from the cloud provider, or an internal UUID when an existing image is copied without a provider build.

agent_name · string · required

The name of the agent that this build belongs to

image_name · string · required

The name of the container image to build.

image_tag · string · required

The tag for the container image.

build_status · enum<string> · required

The current build lifecycle status

Available options: queued, running, success, failed, cancelling, cancelled, deleting, delete_failed, timed_out, error, unknown

source_repo · string | null · required

Normalized git remote the build context came from (host/path, no credentials).

source_commit · string | null · required

Git commit the build context was at, when a git work tree.

source_ref · string | null · required

Git branch or tag for source_commit, when resolvable.

source_subpath · string | null · required

Build-context path relative to the repo root (which agent, in a monorepo).

working_tree_hash · string | null · required

Deterministic SHA-256 content hash of the build inputs (not the tarball).

source_dirty · boolean | null · required

Whether the work tree had uncommitted changes at build time (null outside git).

account_id · string · required

The ID of the account that owns the given entity.

created_at · string<date-time> · required

The date and time when the entity was created in ISO format.

created_by · Identity · object · required

The identity that created the entity.

Show child attributes

object · string · default: agentex_cloud_build

Allowed value: "agentex_cloud_build"

agent_id · string | null

The UUID of the agent that this build belongs to

image_url · string | null

The URL of the container image. This is not guaranteed to be present until the build is complete.

image_digest · string | null

Registry manifest digest of the pushed image (e.g. sha256:...). Reported by the cloud provider when the build completes; null until then, and null on builds whose provider path does not report one. Unlike image_url, it names the exact image bytes and cannot be repointed.

build_start_time · string<date-time> | null

When the cloud provider started the build

build_end_time · string<date-time> | null

When the cloud provider finished the build