Skip to content
For Self-Managed AI Platform users running v11.1, see the self-managed platform documentation
Workload API > Build artifacts > REST: Artifacts and repositories

REST: Artifacts and repositories

Use these paths together with API reference authentication and models. For the full schema and parameter reference, see the Workloads API reference.

Artifacts

These endpoints create, read, update, clone, and delete artifacts.

Verb Path Description
GET /artifacts List artifacts. Filter by type, status, repositoryId, tagKeys, tagValues, createdBy, search, ids. Sort with orderBy (name, createdAt, updatedAt, status; prefix - for descending).
POST /artifacts Create a new artifact in draft status. Every artifact belongs to a repository: omit artifactRepositoryId and the platform creates one dedicated to this artifact; set it to an existing repository's id to add the artifact there instead, or to a new id to have the platform create the repository under that id.
GET /artifacts/{artifact_id} Get a single artifact.
PUT /artifacts/{artifact_id} Replace all artifact fields.
PATCH /artifacts/{artifact_id} Partial update at the top level: fields the body omits keep their current value. Within a containerGroups[].containers[] entry you name, this is not a deep merge—fields that entry omits (readinessProbe, imageBuildConfig.dockerfile, and so on) reset to their defaults rather than staying as they were. Resend a container's full definition whenever you touch part of it. Use to lock the artifact: {"status": "locked"}.
DELETE /artifacts/{artifact_id} Delete an artifact. Returns 409 if the artifact is locked or in use by a Workload.
POST /artifacts/{artifact_id}/clone Clone an existing artifact into a new draft. Body: {"name": "new-artifact-name"}.

Image builds

These endpoints manage container image builds for artifacts that use imageBuildConfig instead of a pre-built imageUri. All builds are scoped to an artifact; there is no top-level builds collection, because a build's only job is to populate imageUri on one container of one artifact—a build has no meaning outside the artifact it belongs to. See Trigger and manage builds for the status model and error reference.

Verb Path Description
POST /artifacts/{artifact_id}/builds Trigger an image build. Takes no request body. Returns 202 with {"buildIds": ["<id>"]}. Requires the editor role.
GET /artifacts/{artifact_id}/builds List image builds, newest first. Parameters: offset (default 0), limit (default 10, maximum 100). No filtering or sorting.
GET /artifacts/{artifact_id}/builds/{build_id} Get a specific build's status and details. Refreshes the status from the build service as part of the request.
DELETE /artifacts/{artifact_id}/builds/{build_id} Cancel and remove a build. Returns 204. This is the cancel operation; there is no separate cancel path. Requires the editor role.

Build output is not served by the Workload API. It is exported as OpenTelemetry logs and read from GET /api/v2/otel/artifact/{artifactId}/logs/—see Build logs.

A single build reads as:

{
  "id": "68f0d4aa11bb22cc33dd44ee",
  "name": "my-agent image build",
  "artifactId": "68f0c1a2b3d4e5f607182930",
  "status": "COMPLETED",
  "createdAt": "2026-08-20T10:15:00Z",
  "updatedAt": "2026-08-20T10:19:42Z",
  "creator": { "id": "...", "username": "...", "email": "..." }
}

status is one of PENDING, IN_PROGRESS, BUILT, COMPLETED, CANCELLED, FAILED, or UNKNOWN—uppercase, unlike the lowercase artifact and Workload statuses.

Permission failures return 404

All build endpoints return 404 Artifact not found when you lack a role on the artifact, rather than 403.

Artifact sharing

These endpoints list and replace the roles granted on an individual artifact.

Verb Path Description
GET /artifacts/{artifact_id}/sharedRoles List roles granted on an artifact.
PATCH /artifacts/{artifact_id}/sharedRoles Replace the artifact role list (up to 100 entries).

Artifact repositories

These endpoints manage repositories that group artifact versions and govern shared access.

Verb Path Description
GET /artifactRepositories List repositories.
GET /artifactRepositories/{artifact_repository_id} Get a repository.
DELETE /artifactRepositories/{artifact_repository_id} Delete a repository. Cascades to non-locked, unused artifacts; returns 409 otherwise.
GET /artifactRepositories/{artifact_repository_id}/sharedRoles List repository roles.
PATCH /artifactRepositories/{artifact_repository_id}/sharedRoles Replace the repository role list.

Every artifact create request results in a repository: the platform creates one automatically, either under the id artifactRepositoryId names or, when the field is omitted, a new repository dedicated to that single artifact.