# Agent artifact objects

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

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.

<span id="prepare"></span>

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

<span id="responses"></span>

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