Agent artifact objects

Artifacts are identified by artifact_id and version, files by file_id, and placements by placement_id and volume_id. Retain the complete reference after reading a version.

Before you call this API

Obtain the product API base URL, personal access token, Workspace ID, and volume access scope from the same environment. Examples use BASE_URL, MOI_KEY, and WORKSPACE_ID; BASE_URL already includes the product prefix. ARTIFACT_ID and ARTIFACT_VERSION come from the list, not from a file name, download URL, or other message IDs.

List, version read, resolve, and backfill use the volume.read set for filtering; batch deletion uses volume.write. Parent volumes, current placements, and source lifecycles still affect results. Authentication or knowing file_id does not replace volume authorization.

Version details

All fields below have keys in the current HTTP DTO. When a source is invisible, some source fields return an empty string or 0; these empty values do not mean the file is missing.

Field

Type

Description

workspace_id

string

Workspace owning the artifact.

artifact_id

string

Artifact ID.

version

integer

Positive integer version.

artifact_kind

string

Artifact type; file in the example.

status

string

processing/completed/failed/deleted/expired. Current details select completed only.

file_id

string

Currently associated file ID.

placement_id

integer

Catalog file placement selected within current permissions.

volume_id

integer

Volume owning the placement.

file_path、file_name

string

Path and file name in the current placement.

content_type

string

File MIME type.

file_category

string

image/document/spreadsheet/audio/video/archive/other。

size

integer

File size in bytes.

md5

string

Current file MD5.

agent_workspace_id、agent_id

string

Definition Workspace and ID of the source agent.

agent_name

string

Resolvable source agent display name; may be empty when unresolvable.

conversation_id、conversation_title

string

Source conversation ID and title visible to the current user.

task_id

string

Visible source task ID.

call_id、tool_id

string

Visible source call and tool identifiers.

created_by、creator_name

string

File creator and resolvable display name.

source_event_id、source_event_seq

string、integer

Visible source event identifier and sequence number.

generated_at

string

Artifact generation time in RFC3339Nano.

created_at、updated_at

string

Record creation/update time in RFC3339Nano.

Artifact reads resolve the stable file_id to a placement in currently readable volumes and select a deterministic latest placement record. A move or rename may change the returned location. Artifact version is not a placement version; do not assume a saved placement_id remains valid indefinitely.

List object

Field

Type

Description

items

array (version details)

Artifact versions on the current page.

total

integer

Total records under current access and filters.

page、page_size

integer

Current page number and size; defaults to 1 and 10.

snapshot_at

string

Snapshot time for this request in RFC3339Nano; no input accepts it for subsequent pages.

agent_sources

array (source references)

agent_workspace_id/agent_id candidates.

creator_sources

array (creator candidates)

created_by/creator_name candidates; the name may be empty when unresolved.

Candidate sources come from the filter baseline and may cover more than the current items page. created_by candidates are collected before applying their own filter, as are agent candidates. Some hidden system agents are excluded from source candidates while their artifact rows can still appear. A missing candidate does not establish that its artifacts do not exist.

Batch references and per-item results

Each input is {"artifact_id":"artifact-example","version":1}. Both identifiers come from the same read. Omitting version does not select the latest version.

Deletion returns a succeeded reference array and a failed array. Resolve returns items and failed. Resolved items include artifact_id, version, file_id, volume_id, placement_id, file_name, content_type, size, and status. failed items include artifact_id, version, and reason. HTTP200 does not mean every item succeeded.

Backfill statistics

Field

Type

Description

scanned

integer

Candidates retrieved within the selected scope for this request.

inserted

integer

Records actually added; 0 for dry_run.

skipped

integer

Skipped count. For dry_run, equals scanned; its meaning differs from actual execution.

failed

integer

Per-candidate write failures. A whole-request failure may still return an HTTP error.

dry_run

boolean

Whether this request only checks candidates.

Last updated on