Scale AI Agentex Cloud Build API

openapi: 3.2.0
info:
  title: EGP API V5 Agentex Cloud Build API
  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: []
tags:
- name: Agentex Cloud Build
paths:
  /v5/builds/{build_id}/cancel:
    post:
      tags:
      - Agentex Cloud Build
      summary: Cancel a build
      description: 'Request cancellation of a build and return 202 Accepted.


        Cancellation runs asynchronously: the endpoint verifies the build exists and then hands it off to a

        background workflow that marks the build as cancelling, asks the cloud build provider to stop it, and

        polls until the build reaches a terminal state before recording the final status. Only builds that are

        still queued or running are actually cancelled; if the build has already finished, or cancellation is

        already in progress, the request is still accepted but has no effect. The returned record reflects the

        build''s state at the time of the call, so it will not yet show the pending cancellation. The request

        is rejected if no such build exists for the caller''s account.'
      operationId: POST-V5-/builds/build_id/cancel
      parameters:
      - name: build_id
        in: path
        required: true
        schema:
          type: string
          title: Build Id
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      responses:
        '202':
          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: []
      x-source: https://docs.gp.scale.com/reference/v5/agentex-cloud-build/cancel-a-build
  /v5/builds/{build_id}:
    get:
      tags:
      - Agentex Cloud Build
      summary: Get a build
      description: 'Retrieve a single build by its ID, including its current lifecycle status.


        Because builds run asynchronously after submission, the status returned here reflects the latest known

        state and may still be queued or running; call this endpoint again to observe progression to a

        terminal state such as success, failed, cancelled, or timed out. Responds with a not-found error if no

        such build exists for the caller''s account.'
      operationId: GET-V5-/builds/build_id
      parameters:
      - name: build_id
        in: path
        required: true
        schema:
          type: string
          title: Build Id
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      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: []
      x-source: https://docs.gp.scale.com/reference/v5/agentex-cloud-build/get-a-build
  /v5/builds/undeployed:
    get:
      tags:
      - Agentex Cloud Build
      summary: List agents built but not deployed
      description: 'List agents that exist only as cloud builds and have no healthy deployment yet.


        Unlike listing builds, this aggregates by agent: it returns one entry per distinct agent name whose

        builds have never reached a healthy deploy, each carrying that agent''s most recent build and its total

        build count. The result is a plain list (not paginated) and is limited to builds the caller is

        permitted to read. Use this to surface agents that were built but still need to be deployed; use

        `GET /v5/builds` when you need the individual build records instead.'
      operationId: GET-V5-/builds/undeployed
      parameters:
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UndeployedAgent'
                title: Response Get-V5-/Builds/Undeployed
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/agentex-cloud-build/list-agents-built-but-not-deployed
  /v5/builds:
    get:
      tags:
      - Agentex Cloud Build
      summary: List container image builds
      description: 'List container image build records for the caller''s account as a paginated collection.


        Each entry is one individual build with its current lifecycle status; pass `agent_name`,

        `source_commit`, or `working_tree_hash` to return only matching builds. Archived builds are

        excluded, and results are limited to builds the caller is permitted to read. Use this to

        enumerate individual builds; to instead list agents that have been built but not yet

        deployed, use `GET /v5/builds/undeployed`.'
      operationId: GET-V5-/builds
      parameters:
      - name: agent_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter builds by agent name
          title: Agent Name
        description: Filter builds by agent name
      - name: source_commit
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
            pattern: ^(?:[0-9a-fA-F]{40}|[0-9a-fA-F]{64})$
          - type: 'null'
          description: Filter builds by source git commit
          title: Source Commit
        description: Filter builds by source git commit
      - name: working_tree_hash
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
            pattern: ^[0-9a-fA-F]{64}$
          - type: 'null'
          description: Filter builds by build-context content hash
          title: Working Tree Hash
        description: Filter builds by build-context content hash
      - name: starting_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Starting After
      - name: ending_before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Ending Before
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 10000
          minimum: 1
          default: 100
          title: Limit
      - name: sort_by
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Sort By
      - name: sort_order
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/SortOrder'
          - type: 'null'
          default: asc
          title: Sort Order
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedList_AgentexCloudBuild_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/agentex-cloud-build/list-container-image-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: []
      x-source: https://docs.gp.scale.com/reference/v5/agentex-cloud-build/submit-container-image-build
  /v5/builds/{build_id}/logs:
    get:
      tags:
      - Agentex Cloud Build
      summary: Stream build logs
      description: 'Stream a build''s logs as Server-Sent Events.


        The response has content-type `text/event-stream`; each event carries one log line as an

        `AgentexCloudBuildLogLine` object, delivered as lines become available from the cloud build provider.

        The stream ends when the provider stops producing output. Responds with a not-found error if no such

        build exists for the caller''s account.'
      operationId: GET-V5-/builds/build_id/logs
      parameters:
      - name: build_id
        in: path
        required: true
        schema:
          type: string
          title: Build Id
      - name: x-selected-account-id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Account ID Header
      responses:
        '200':
          description: Server-Sent Events stream of build logs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentexCloudBuildLogLine'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/AgentexCloudBuildLogLine'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-source: https://docs.gp.scale.com/reference/v5/agentex-cloud-build/stream-build-logs
components:
  schemas:
    AgentexCloudBuildStatus:
      type: string
      enum:
      - queued
      - running
      - success
      - failed
      - cancelling
      - cancelled
      - deleting
      - delete_failed
      - timed_out
      - error
      - unknown
      title: AgentexCloudBuildStatus
    IdentityType:
      type: string
      enum:
      - user
      - service_account
      title: IdentityType
    SortOrder:
      type: string
      enum:
      - asc
      - desc
      title: SortOrder
    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
    UndeployedAgent:
      properties:
        agent_name:
          type: string
          title: Agent Name
          description: The agent name from cloud builds
        latest_build:
          $ref: '#/components/schemas/AgentexCloudBuild'
          description: The most recent cloud build for this agent
        total_builds:
          type: integer
          title: Total Builds
          description: Total number of builds for this agent
      type: object
      required:
      - agent_name
      - latest_build
      - total_builds
      title: UndeployedAgent
      description: An agent that exists only as cloud builds — no healthy deployment yet.
    AgentexCloudBuildLogLine:
      properties:
        line:
          type: string
          title: Line
          description: The log line content
      type: object
      required:
      - line
      title: AgentexCloudBuildLogLine
      description: A single log line from the build process.
    PaginatedList_AgentexCloudBuild_:
      properties:
        object:
          type: string
          const: list
          title: Object
          default: list
        items:
          items:
            $ref: '#/components/schemas/AgentexCloudBuild'
          type: array
          title: Items
        limit:
          type: integer
          title: Limit
          description: The maximum number of items to return.
          default: 100
        total:
          type: integer
          title: Total
          description: The total of items that match the query. This is greater than or equal to the number of items returned.
        has_more:
          type: boolean
          title: Has More
          description: Whether there are more items left to be fetched.
      type: object
      required:
      - items
      - total
      - has_more
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
    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
    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
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
x-assembled-from: Per-operation OpenAPI fragments embedded verbatim in docs.gp.scale.com reference pages; source spec https://api.sgp.scale.com/openapi-versions/v5/openapi.json (404 when assembled)