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 |
|---|---|---|
|
string |
Legacy sample ID |
|
array (array) |
New files generated in definition order |
|
string |
Legacy logical file key |
|
string |
Uploaded file ID |
|
string |
|
|
string |
Display name from the upload result |
|
integer |
File size in bytes |
|
string |
Content type in the sample definition |
|
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.