> ## Documentation Index > Fetch the complete documentation index at: https://docs.gp.scale.com/llms.txt > Use this file to discover all available pages before exploring further. # Submit container image build > Submit a container image build from an uploaded build context and return the created build record. The request is multipart form data: a tar.gz `context_archive` with the Dockerfile at its root is streamed to cloud object storage, along with the target `image_name`, an optional `image_tag` (defaults to `latest`), optional Docker `build_args` supplied as a JSON string, and an optional target `platform`. Exactly one of `agent_name` or `agent_id` must be provided: pass `agent_name` to create a brand-new agent for a first-time build (rejected if an agent with that name already exists), or `agent_id` to build for an agent that already exists. The build is handed to the configured cloud build provider and runs asynchronously, so the returned record reflects the build's initial status (typically queued or running) rather than a finished image; poll Get Build or follow Stream Build Logs to observe progression to a terminal state. The request is rejected if the archive is missing or empty, exceeds 500MB, or if `build_args` is not valid JSON. ## OpenAPI ````yaml https://api.sgp.scale.com/openapi-versions/v5/openapi.json post /v5/builds openapi: 3.1.0 info: title: EGP API V5 description: >- This is the parent API for all EGP APIs. If you are looking for the EGP API, please go to https://api.egp.scale.com/docs. contact: name: Scale Generative AI Platform url: https://scale.com/genai-platform version: 0.1.0 servers: - url: https://api.egp.scale.com security: [] paths: /v5/builds: post: tags: - Agentex Cloud Build summary: Submit container image build description: >- Submit a container image build from an uploaded build context and return the created build record. The request is multipart form data: a tar.gz `context_archive` with the Dockerfile at its root is streamed to cloud object storage, along with the target `image_name`, an optional `image_tag` (defaults to `latest`), optional Docker `build_args` supplied as a JSON string, and an optional target `platform`. Exactly one of `agent_name` or `agent_id` must be provided: pass `agent_name` to create a brand-new agent for a first-time build (rejected if an agent with that name already exists), or `agent_id` to build for an agent that already exists. The build is handed to the configured cloud build provider and runs asynchronously, so the returned record reflects the build's initial status (typically queued or running) rather than a finished image; poll Get Build or follow Stream Build Logs to observe progression to a terminal state. The request is rejected if the archive is missing or empty, exceeds 500MB, or if `build_args` is not valid JSON. operationId: POST-V5-/builds parameters: - name: x-selected-account-id in: header required: false schema: anyOf: - type: string - type: 'null' title: Account ID Header requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/AgentexCloudBuildSubmitRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AgentexCloudBuild' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: AgentexCloudBuildSubmitRequest: properties: context_archive: type: string title: Context Archive description: >- tar.gz archive containing the build context (Dockerfile and any files needed for the build) format: binary image_name: type: string title: Image Name description: Name for the built image agent_name: title: Agent Name description: Name of the brand-new agent to create from this build type: string agent_id: title: Agent Id description: ID of the existing agent this build targets type: string image_tag: type: string title: Image Tag description: Tag for the built image default: latest build_args: title: Build Args description: JSON string of build arguments type: string platform: title: Platform description: >- Target platform for the Docker build. Defaults to the build host's native architecture when not specified. type: string enum: - linux/amd64 - linux/arm64 - linux/arm/v7 source_repo: title: Source Repo description: Normalized git remote the build context came from. type: string maxLength: 2048 source_commit: title: Source Commit description: Git commit the build context was at. type: string maxLength: 64 pattern: ^(?:[0-9a-fA-F]{40}|[0-9a-fA-F]{64})$ source_ref: title: Source Ref description: Git branch or tag for source_commit. type: string maxLength: 4096 source_subpath: title: Source Subpath description: Build-context path relative to the repo root. type: string maxLength: 4096 working_tree_hash: title: Working Tree Hash description: Deterministic SHA-256 content hash of the build inputs. type: string maxLength: 64 pattern: ^[0-9a-fA-F]{64}$ source_dirty: title: Source Dirty description: Whether the work tree had uncommitted changes at build time. type: boolean type: object required: - context_archive - image_name title: AgentexCloudBuildSubmitRequest AgentexCloudBuild: properties: id: type: string title: Id description: The unique identifier of the entity. object: type: string const: agentex_cloud_build title: Object default: agentex_cloud_build cloud_provider_build_id: type: string title: Cloud Provider Build Id description: >- 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: type: string title: Agent Name description: The name of the agent that this build belongs to agent_id: title: Agent Id description: The UUID of the agent that this build belongs to type: string image_name: type: string title: Image Name description: The name of the container image to build. image_tag: type: string title: Image Tag description: The tag for the container image. image_url: title: Image Url description: >- The URL of the container image. This is not guaranteed to be present until the build is complete. type: string build_status: $ref: '#/components/schemas/AgentexCloudBuildStatus' description: The current build lifecycle status build_start_time: title: Build Start Time description: When the cloud provider started the build type: string format: date-time build_end_time: title: Build End Time description: When the cloud provider finished the build type: string format: date-time source_repo: title: Source Repo description: >- Normalized git remote the build context came from (host/path, no credentials). anyOf: - type: string - type: 'null' source_commit: title: Source Commit description: Git commit the build context was at, when a git work tree. anyOf: - type: string - type: 'null' source_ref: title: Source Ref description: Git branch or tag for source_commit, when resolvable. anyOf: - type: string - type: 'null' source_subpath: title: Source Subpath description: >- Build-context path relative to the repo root (which agent, in a monorepo). anyOf: - type: string - type: 'null' working_tree_hash: title: Working Tree Hash description: >- Deterministic SHA-256 content hash of the build inputs (not the tarball). anyOf: - type: string - type: 'null' source_dirty: title: Source Dirty description: >- Whether the work tree had uncommitted changes at build time (null outside git). anyOf: - type: boolean - type: 'null' account_id: type: string title: Account Id description: The ID of the account that owns the given entity. created_at: type: string format: date-time title: Created At description: The date and time when the entity was created in ISO format. created_by: $ref: '#/components/schemas/Identity' description: The identity that created the entity. type: object required: - cloud_provider_build_id - agent_name - image_name - image_tag - build_status - source_repo - source_commit - source_ref - source_subpath - working_tree_hash - source_dirty - id - account_id - created_at - created_by HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AgentexCloudBuildStatus: type: string enum: - queued - running - success - failed - cancelling - cancelled - deleting - delete_failed - timed_out - error - unknown title: AgentexCloudBuildStatus Identity: properties: id: type: string title: Id object: type: string const: identity title: Object default: identity type: $ref: '#/components/schemas/IdentityType' type: object required: - id - type title: Identity ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: title: Error Type type: string input: title: Input ctx: type: object title: Context additionalProperties: true type: object required: - loc - msg - type title: ValidationError IdentityType: type: string enum: - user - service_account title: IdentityType securitySchemes: APIKeyHeader: type: apiKey in: header name: x-api-key ````