# Build

## Submit container image build

**post** `/v5/builds`

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.

### Returns

- `AgentexCloudBuild object { id, account_id, agent_name, 17 more }`

  - `id: string`

    The unique identifier of the entity.

  - `account_id: string`

    The ID of the account that owns the given entity.

  - `agent_name: string`

    The name of the agent that this build belongs to

  - `build_status: "queued" or "running" or "success" or 8 more`

    The current build lifecycle status

    - `"queued"`

    - `"running"`

    - `"success"`

    - `"failed"`

    - `"cancelling"`

    - `"cancelled"`

    - `"deleting"`

    - `"delete_failed"`

    - `"timed_out"`

    - `"error"`

    - `"unknown"`

  - `cloud_provider_build_id: string`

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

  - `created_at: string`

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

  - `created_by: Identity`

    The identity that created the entity.

    - `id: string`

    - `type: "user" or "service_account"`

      - `"user"`

      - `"service_account"`

    - `object: optional "identity"`

      - `"identity"`

  - `image_name: string`

    The name of the container image to build.

  - `image_tag: string`

    The tag for the container image.

  - `source_commit: string`

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

  - `source_dirty: boolean`

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

  - `source_ref: string`

    Git branch or tag for source_commit, when resolvable.

  - `source_repo: string`

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

  - `source_subpath: string`

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

  - `working_tree_hash: string`

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

  - `agent_id: optional string`

    The UUID of the agent that this build belongs to

  - `build_end_time: optional string`

    When the cloud provider finished the build

  - `build_start_time: optional string`

    When the cloud provider started the build

  - `image_url: optional string`

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

  - `object: optional "agentex_cloud_build"`

    - `"agentex_cloud_build"`

### Example

```http
curl https://api.egp.scale.com/v5/builds \
    -H 'Content-Type: multipart/form-data' \
    -H "x-api-key: $SGP_API_KEY" \
    -F image_name=image_name
```

#### Response

```json
{
  "id": "id",
  "account_id": "account_id",
  "agent_name": "agent_name",
  "build_status": "queued",
  "cloud_provider_build_id": "cloud_provider_build_id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "created_by": {
    "id": "id",
    "type": "user",
    "object": "identity"
  },
  "image_name": "image_name",
  "image_tag": "image_tag",
  "source_commit": "source_commit",
  "source_dirty": true,
  "source_ref": "source_ref",
  "source_repo": "source_repo",
  "source_subpath": "source_subpath",
  "working_tree_hash": "working_tree_hash",
  "agent_id": "agent_id",
  "build_end_time": "2019-12-27T18:11:19.117Z",
  "build_start_time": "2019-12-27T18:11:19.117Z",
  "image_url": "image_url",
  "object": "agentex_cloud_build"
}
```

## Get a build

**get** `/v5/builds/{build_id}`

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.

### Path Parameters

- `build_id: string`

### Returns

- `AgentexCloudBuild object { id, account_id, agent_name, 17 more }`

  - `id: string`

    The unique identifier of the entity.

  - `account_id: string`

    The ID of the account that owns the given entity.

  - `agent_name: string`

    The name of the agent that this build belongs to

  - `build_status: "queued" or "running" or "success" or 8 more`

    The current build lifecycle status

    - `"queued"`

    - `"running"`

    - `"success"`

    - `"failed"`

    - `"cancelling"`

    - `"cancelled"`

    - `"deleting"`

    - `"delete_failed"`

    - `"timed_out"`

    - `"error"`

    - `"unknown"`

  - `cloud_provider_build_id: string`

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

  - `created_at: string`

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

  - `created_by: Identity`

    The identity that created the entity.

    - `id: string`

    - `type: "user" or "service_account"`

      - `"user"`

      - `"service_account"`

    - `object: optional "identity"`

      - `"identity"`

  - `image_name: string`

    The name of the container image to build.

  - `image_tag: string`

    The tag for the container image.

  - `source_commit: string`

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

  - `source_dirty: boolean`

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

  - `source_ref: string`

    Git branch or tag for source_commit, when resolvable.

  - `source_repo: string`

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

  - `source_subpath: string`

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

  - `working_tree_hash: string`

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

  - `agent_id: optional string`

    The UUID of the agent that this build belongs to

  - `build_end_time: optional string`

    When the cloud provider finished the build

  - `build_start_time: optional string`

    When the cloud provider started the build

  - `image_url: optional string`

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

  - `object: optional "agentex_cloud_build"`

    - `"agentex_cloud_build"`

### Example

```http
curl https://api.egp.scale.com/v5/builds/$BUILD_ID \
    -H "x-api-key: $SGP_API_KEY"
```

#### Response

```json
{
  "id": "id",
  "account_id": "account_id",
  "agent_name": "agent_name",
  "build_status": "queued",
  "cloud_provider_build_id": "cloud_provider_build_id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "created_by": {
    "id": "id",
    "type": "user",
    "object": "identity"
  },
  "image_name": "image_name",
  "image_tag": "image_tag",
  "source_commit": "source_commit",
  "source_dirty": true,
  "source_ref": "source_ref",
  "source_repo": "source_repo",
  "source_subpath": "source_subpath",
  "working_tree_hash": "working_tree_hash",
  "agent_id": "agent_id",
  "build_end_time": "2019-12-27T18:11:19.117Z",
  "build_start_time": "2019-12-27T18:11:19.117Z",
  "image_url": "image_url",
  "object": "agentex_cloud_build"
}
```

## List container image builds

**get** `/v5/builds`

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`.

### Query Parameters

- `agent_name: optional string`

  Filter builds by agent name

- `ending_before: optional string`

- `limit: optional number`

- `sort_by: optional string`

- `sort_order: optional SortOrder`

  - `"asc"`

  - `"desc"`

- `source_commit: optional string`

  Filter builds by source git commit

- `starting_after: optional string`

- `working_tree_hash: optional string`

  Filter builds by build-context content hash

### Returns

- `has_more: boolean`

  Whether there are more items left to be fetched.

- `items: array of AgentexCloudBuild`

  - `id: string`

    The unique identifier of the entity.

  - `account_id: string`

    The ID of the account that owns the given entity.

  - `agent_name: string`

    The name of the agent that this build belongs to

  - `build_status: "queued" or "running" or "success" or 8 more`

    The current build lifecycle status

    - `"queued"`

    - `"running"`

    - `"success"`

    - `"failed"`

    - `"cancelling"`

    - `"cancelled"`

    - `"deleting"`

    - `"delete_failed"`

    - `"timed_out"`

    - `"error"`

    - `"unknown"`

  - `cloud_provider_build_id: string`

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

  - `created_at: string`

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

  - `created_by: Identity`

    The identity that created the entity.

    - `id: string`

    - `type: "user" or "service_account"`

      - `"user"`

      - `"service_account"`

    - `object: optional "identity"`

      - `"identity"`

  - `image_name: string`

    The name of the container image to build.

  - `image_tag: string`

    The tag for the container image.

  - `source_commit: string`

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

  - `source_dirty: boolean`

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

  - `source_ref: string`

    Git branch or tag for source_commit, when resolvable.

  - `source_repo: string`

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

  - `source_subpath: string`

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

  - `working_tree_hash: string`

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

  - `agent_id: optional string`

    The UUID of the agent that this build belongs to

  - `build_end_time: optional string`

    When the cloud provider finished the build

  - `build_start_time: optional string`

    When the cloud provider started the build

  - `image_url: optional string`

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

  - `object: optional "agentex_cloud_build"`

    - `"agentex_cloud_build"`

- `total: number`

  The total of items that match the query. This is greater than or equal to the number of items returned.

- `limit: optional number`

  The maximum number of items to return.

- `object: optional "list"`

  - `"list"`

### Example

```http
curl https://api.egp.scale.com/v5/builds \
    -H "x-api-key: $SGP_API_KEY"
```

#### Response

```json
{
  "has_more": true,
  "items": [
    {
      "id": "id",
      "account_id": "account_id",
      "agent_name": "agent_name",
      "build_status": "queued",
      "cloud_provider_build_id": "cloud_provider_build_id",
      "created_at": "2019-12-27T18:11:19.117Z",
      "created_by": {
        "id": "id",
        "type": "user",
        "object": "identity"
      },
      "image_name": "image_name",
      "image_tag": "image_tag",
      "source_commit": "source_commit",
      "source_dirty": true,
      "source_ref": "source_ref",
      "source_repo": "source_repo",
      "source_subpath": "source_subpath",
      "working_tree_hash": "working_tree_hash",
      "agent_id": "agent_id",
      "build_end_time": "2019-12-27T18:11:19.117Z",
      "build_start_time": "2019-12-27T18:11:19.117Z",
      "image_url": "image_url",
      "object": "agentex_cloud_build"
    }
  ],
  "total": 0,
  "limit": 0,
  "object": "list"
}
```

## Stream build logs

**get** `/v5/builds/{build_id}/logs`

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.

### Path Parameters

- `build_id: string`

### Returns

- `StreamChunk object { line }`

  A single log line from the build process.

  - `line: string`

    The log line content

### Example

```http
curl https://api.egp.scale.com/v5/builds/$BUILD_ID/logs \
    -H "x-api-key: $SGP_API_KEY"
```

#### Response

```json
{
  "line": "line"
}
```

## Cancel a build

**post** `/v5/builds/{build_id}/cancel`

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.

### Path Parameters

- `build_id: string`

### Returns

- `AgentexCloudBuild object { id, account_id, agent_name, 17 more }`

  - `id: string`

    The unique identifier of the entity.

  - `account_id: string`

    The ID of the account that owns the given entity.

  - `agent_name: string`

    The name of the agent that this build belongs to

  - `build_status: "queued" or "running" or "success" or 8 more`

    The current build lifecycle status

    - `"queued"`

    - `"running"`

    - `"success"`

    - `"failed"`

    - `"cancelling"`

    - `"cancelled"`

    - `"deleting"`

    - `"delete_failed"`

    - `"timed_out"`

    - `"error"`

    - `"unknown"`

  - `cloud_provider_build_id: string`

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

  - `created_at: string`

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

  - `created_by: Identity`

    The identity that created the entity.

    - `id: string`

    - `type: "user" or "service_account"`

      - `"user"`

      - `"service_account"`

    - `object: optional "identity"`

      - `"identity"`

  - `image_name: string`

    The name of the container image to build.

  - `image_tag: string`

    The tag for the container image.

  - `source_commit: string`

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

  - `source_dirty: boolean`

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

  - `source_ref: string`

    Git branch or tag for source_commit, when resolvable.

  - `source_repo: string`

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

  - `source_subpath: string`

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

  - `working_tree_hash: string`

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

  - `agent_id: optional string`

    The UUID of the agent that this build belongs to

  - `build_end_time: optional string`

    When the cloud provider finished the build

  - `build_start_time: optional string`

    When the cloud provider started the build

  - `image_url: optional string`

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

  - `object: optional "agentex_cloud_build"`

    - `"agentex_cloud_build"`

### Example

```http
curl https://api.egp.scale.com/v5/builds/$BUILD_ID/cancel \
    -X POST \
    -H "x-api-key: $SGP_API_KEY"
```

#### Response

```json
{
  "id": "id",
  "account_id": "account_id",
  "agent_name": "agent_name",
  "build_status": "queued",
  "cloud_provider_build_id": "cloud_provider_build_id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "created_by": {
    "id": "id",
    "type": "user",
    "object": "identity"
  },
  "image_name": "image_name",
  "image_tag": "image_tag",
  "source_commit": "source_commit",
  "source_dirty": true,
  "source_ref": "source_ref",
  "source_repo": "source_repo",
  "source_subpath": "source_subpath",
  "working_tree_hash": "working_tree_hash",
  "agent_id": "agent_id",
  "build_end_time": "2019-12-27T18:11:19.117Z",
  "build_start_time": "2019-12-27T18:11:19.117Z",
  "image_url": "image_url",
  "object": "agentex_cloud_build"
}
```

## List agents built but not deployed

**get** `/v5/builds/undeployed`

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.

### Returns

- `agent_name: string`

  The agent name from cloud builds

- `latest_build: AgentexCloudBuild`

  The most recent cloud build for this agent

  - `id: string`

    The unique identifier of the entity.

  - `account_id: string`

    The ID of the account that owns the given entity.

  - `agent_name: string`

    The name of the agent that this build belongs to

  - `build_status: "queued" or "running" or "success" or 8 more`

    The current build lifecycle status

    - `"queued"`

    - `"running"`

    - `"success"`

    - `"failed"`

    - `"cancelling"`

    - `"cancelled"`

    - `"deleting"`

    - `"delete_failed"`

    - `"timed_out"`

    - `"error"`

    - `"unknown"`

  - `cloud_provider_build_id: string`

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

  - `created_at: string`

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

  - `created_by: Identity`

    The identity that created the entity.

    - `id: string`

    - `type: "user" or "service_account"`

      - `"user"`

      - `"service_account"`

    - `object: optional "identity"`

      - `"identity"`

  - `image_name: string`

    The name of the container image to build.

  - `image_tag: string`

    The tag for the container image.

  - `source_commit: string`

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

  - `source_dirty: boolean`

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

  - `source_ref: string`

    Git branch or tag for source_commit, when resolvable.

  - `source_repo: string`

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

  - `source_subpath: string`

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

  - `working_tree_hash: string`

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

  - `agent_id: optional string`

    The UUID of the agent that this build belongs to

  - `build_end_time: optional string`

    When the cloud provider finished the build

  - `build_start_time: optional string`

    When the cloud provider started the build

  - `image_url: optional string`

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

  - `object: optional "agentex_cloud_build"`

    - `"agentex_cloud_build"`

- `total_builds: number`

  Total number of builds for this agent

### Example

```http
curl https://api.egp.scale.com/v5/builds/undeployed \
    -H "x-api-key: $SGP_API_KEY"
```

#### Response

```json
[
  {
    "agent_name": "agent_name",
    "latest_build": {
      "id": "id",
      "account_id": "account_id",
      "agent_name": "agent_name",
      "build_status": "queued",
      "cloud_provider_build_id": "cloud_provider_build_id",
      "created_at": "2019-12-27T18:11:19.117Z",
      "created_by": {
        "id": "id",
        "type": "user",
        "object": "identity"
      },
      "image_name": "image_name",
      "image_tag": "image_tag",
      "source_commit": "source_commit",
      "source_dirty": true,
      "source_ref": "source_ref",
      "source_repo": "source_repo",
      "source_subpath": "source_subpath",
      "working_tree_hash": "working_tree_hash",
      "agent_id": "agent_id",
      "build_end_time": "2019-12-27T18:11:19.117Z",
      "build_start_time": "2019-12-27T18:11:19.117Z",
      "image_url": "image_url",
      "object": "agentex_cloud_build"
    },
    "total_builds": 0
  }
]
```

## Domain Types

### Agentex Cloud Build

- `AgentexCloudBuild object { id, account_id, agent_name, 17 more }`

  - `id: string`

    The unique identifier of the entity.

  - `account_id: string`

    The ID of the account that owns the given entity.

  - `agent_name: string`

    The name of the agent that this build belongs to

  - `build_status: "queued" or "running" or "success" or 8 more`

    The current build lifecycle status

    - `"queued"`

    - `"running"`

    - `"success"`

    - `"failed"`

    - `"cancelling"`

    - `"cancelled"`

    - `"deleting"`

    - `"delete_failed"`

    - `"timed_out"`

    - `"error"`

    - `"unknown"`

  - `cloud_provider_build_id: string`

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

  - `created_at: string`

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

  - `created_by: Identity`

    The identity that created the entity.

    - `id: string`

    - `type: "user" or "service_account"`

      - `"user"`

      - `"service_account"`

    - `object: optional "identity"`

      - `"identity"`

  - `image_name: string`

    The name of the container image to build.

  - `image_tag: string`

    The tag for the container image.

  - `source_commit: string`

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

  - `source_dirty: boolean`

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

  - `source_ref: string`

    Git branch or tag for source_commit, when resolvable.

  - `source_repo: string`

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

  - `source_subpath: string`

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

  - `working_tree_hash: string`

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

  - `agent_id: optional string`

    The UUID of the agent that this build belongs to

  - `build_end_time: optional string`

    When the cloud provider finished the build

  - `build_start_time: optional string`

    When the cloud provider started the build

  - `image_url: optional string`

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

  - `object: optional "agentex_cloud_build"`

    - `"agentex_cloud_build"`

### Stream Chunk

- `StreamChunk object { line }`

  A single log line from the build process.

  - `line: string`

    The log line content

### Build List Undeployed Response

- `BuildListUndeployedResponse = array of object { agent_name, latest_build, total_builds }`

  - `agent_name: string`

    The agent name from cloud builds

  - `latest_build: AgentexCloudBuild`

    The most recent cloud build for this agent

    - `id: string`

      The unique identifier of the entity.

    - `account_id: string`

      The ID of the account that owns the given entity.

    - `agent_name: string`

      The name of the agent that this build belongs to

    - `build_status: "queued" or "running" or "success" or 8 more`

      The current build lifecycle status

      - `"queued"`

      - `"running"`

      - `"success"`

      - `"failed"`

      - `"cancelling"`

      - `"cancelled"`

      - `"deleting"`

      - `"delete_failed"`

      - `"timed_out"`

      - `"error"`

      - `"unknown"`

    - `cloud_provider_build_id: string`

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

    - `created_at: string`

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

    - `created_by: Identity`

      The identity that created the entity.

      - `id: string`

      - `type: "user" or "service_account"`

        - `"user"`

        - `"service_account"`

      - `object: optional "identity"`

        - `"identity"`

    - `image_name: string`

      The name of the container image to build.

    - `image_tag: string`

      The tag for the container image.

    - `source_commit: string`

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

    - `source_dirty: boolean`

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

    - `source_ref: string`

      Git branch or tag for source_commit, when resolvable.

    - `source_repo: string`

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

    - `source_subpath: string`

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

    - `working_tree_hash: string`

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

    - `agent_id: optional string`

      The UUID of the agent that this build belongs to

    - `build_end_time: optional string`

      When the cloud provider finished the build

    - `build_start_time: optional string`

      When the cloud provider started the build

    - `image_url: optional string`

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

    - `object: optional "agentex_cloud_build"`

      - `"agentex_cloud_build"`

  - `total_builds: number`

    Total number of builds for this agent