Skip to main content
POST
Submit container image build

Authorizations

x-api-key
string
header
required

Headers

x-selected-account-id
string | null

Body

multipart/form-data
context_archive
file
required

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

image_name
string
required

Name for the built image

agent_name
string

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

agent_id
string

ID of the existing agent this build targets

image_tag
string
default:latest

Tag for the built image

build_args
string

JSON string of build arguments

platform
enum<string>

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

Normalized git remote the build context came from.

Maximum string length: 2048
source_commit
string

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

Git branch or tag for source_commit.

Maximum string length: 4096
source_subpath
string

Build-context path relative to the repo root.

Maximum string length: 4096
working_tree_hash
string

Deterministic SHA-256 content hash of the build inputs.

Maximum string length: 64
Pattern: ^[0-9a-fA-F]{64}$
source_dirty
boolean

Whether the work tree had uncommitted changes at build time.

Response

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.

object
string
default:agentex_cloud_build
Allowed value: "agentex_cloud_build"
agent_id
string

The UUID of the agent that this build belongs to

image_url
string

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

build_start_time
string<date-time>

When the cloud provider started the build

build_end_time
string<date-time>

When the cloud provider finished the build