Legacy sample copy protocol

POST /workspaces/{id}/agent-home-guide/samples/{sample_id}/files/materialize. Uses a regular product identity and regular service boundary. The handler reads the ID from the path, not business request fields. The legacy frontend helper sends {}; current home file cards use read-only resolution and do not call this POST.

Available IDs

POST https://api.moi.matrixorigin.cn/v5/workspaces/{id}/agent-home-guide/samples/{sample_id}/files/materialize

builder-expense, builder-resume, builder-qa, doc-report, doc-bid, doc-meeting, data-sales, data-retention, data-weekly, kb-product, kb-policy, kb-feedback, workflow-github, workflow-lead, workflow-issue. These legacy SampleIDs are not interchangeable with the three file GuideIDs.

Writes and failure cleanup

Validate SampleID, sequentially open packaged assets from the configured directory, read file information and localized display names for the request language, and upload unreferenced files through Catalog. Success includes new files and moi://files/{id} URIs. There is no idempotency key; repeated POST does not imply reusing existing references.

On failure, delete each file recorded as successfully uploaded. Cleanup uses an independent timeout context detached from request cancellation. File-close failures also trigger cleanup; deletion failures are combined with the original error. This is not an atomic database transaction and does not guarantee removal of every partial write. If an upload returns both an ID and an error, persistence and underlying recovery require checking the complete upload lifecycle; this alone does not establish a production leak.

Success fields

The string code: "OK" envelope contains this data:

Field

Type

Description

sample_id

string

Legacy sample ID

files

array (array)

New files generated in definition order

files[].file_key

string

Legacy logical file key

files[].id

string

Uploaded file ID

files[].uri

string

moi://files/{id}

files[].name

string

Display name from the upload result

files[].size

integer

File size in bytes

files[].type

string

Content type in the sample definition

files[].md5

string

Optional content MD5

Errors and retesting

Unknown SampleID maps to 404/ErrObjectNotFound, missing packaged assets to 500/ErrSampleAssetMissing, and other failures to 500/ErrServer. GET uses 404 for missing samples; do not copy its error table to the legacy POST. POST has no separate mapping for authorization denial or PDP unavailability.

Record file IDs before and after the operation and retain every cleanup result. Do not delete files of unknown provenance.

Last updated on