Artifact read, deletion, and backfill boundaries¶
Identify the artifact category first, then proceed according to file and source state.
Objects and identity¶
Endpoint |
Identifier and purpose |
|---|---|
Workspace agent-artifacts |
Version projections of agent-generated files, identified by artifact_id/version. |
catalog/file-artifacts/{file_id} |
Query processing associations and data assets by file. |
lineage/artifacts/{artifact_id} |
Workflow lineage artifact nodes, output blocks, and revisions. |
workspaces/{id}/runtime-artifacts |
Restricted file publication by active tasks; requires additional runtime credentials. |
These four endpoints are not interchangeable merely because all contain artifact. The five artifact management operations are not endpoints for arbitrary file publication, knowledge base parsing, or workflow reruns.
Source and file visibility¶
An artifact row for a readable file may still hide the source task. The handler checks whether the source task belongs to the current user and matches the context. When the source cannot be displayed, conversation_id, conversation_title, task_id, call_id, tool_id, source_event_id, and source_event_seq are cleared.
Filtering by conversation_id also requires the source conversation and task to belong to the current user. Archived source conversations or agents and unreadable current mounts can hide entries. An empty list, detail404, or empty source fields alone do not prove physical file deletion.
Deletion results¶
Up to 100 items; check succeeded and failed individually. Readable versions, current mounts, volume scope, and state jointly affect results. The implementation marks the specified version deleted, detaches the currently selected volume_files mount, and decrements the reference count. It does not synchronously remove every mount or guarantee erasure of the underlying object.
Repeated deletion may return not_found because the artifact is no longer completed or its mount was removed. already_deleted is not guaranteed every time.
Backfill behavior¶
Scans only files with agent tool/sandbox sources, task/active conversation associations, readable current mounts, and missing artifact records. Use dry_run=true first, then false only after confirming scope. Omitted dry_run, an empty JSON object, JSON null, no body, or Content-Length of 0 defaults to false. limit defaults to 200, maximum 1000.
Backfill creates index-like records. It does not regenerate files, restore lost content, or trigger agent tasks. There is no cursor or next_token. Repeated dry-runs may see the same candidates; do not sum counts as distinct files. Newly created versions start at 1 and use backfill time. generated_at is not the original creation time of the old file.
Errors and result confirmation¶
Invalid parameters, date ranges, or pagination may return 400/code 2. Unavailable details may return 404/code 3; volume authorization/dependency failures may first return 403/503. Regular errors use numeric code/message, not string code/msg.
invalid_argument, not_found, already_deleted, and unavailable in batch results describe individual items. Some read failures also map to not_found. One reason does not establish storage health, actual absence, or permissions. Source-mapping differences remain in internal review records and require retesting with real failure/permission scenarios.