Uploads and downloads¶
Transfer file bytes outside model context. Keep a verified artifact ID for every input and retain the original file’s units and provenance.
Choose the intake route¶
Situation |
MCP |
REST |
|---|---|---|
Chat host supplies a direct attachment reference |
|
|
File is on an agent/CI machine |
|
|
User needs a browser picker |
|
|
PDF, CSV, image or reference document |
Design-source upload/import tools |
|
Artifact is already ready |
|
|
Surface intake supports the formats declared by the service. STEP/STP and STL are the usual meshing inputs; 3MF follows the reconstruction workflow before downstream use. Document intake is separate from surface intake.
Direct upload¶
Request a reservation using a filename and units/context. Supply size and SHA-256 together only when already known. A matching verified upload can return reused: true with no transfer. Otherwise, execute the returned method/URL/headers against the actual file. In command-capable clients, use transfer.command with a correctly quoted local path.
The transfer capability covers one artifact and expires after 15 minutes. Use only its supplied headers; do not attach your account bearer key to arbitrary storage or download URLs. Inspect the returned ready artifact. After a lost acknowledgement, check the artifact before starting another upload.
An upload being accepted does not imply it is valid geometry, correctly scaled or within every downstream inspection limit. See units and limits.
Attachment import and preparation¶
Use the real download_url and file_id supplied by the host. Never invent them or send a local filesystem path as a remote URL. For potentially long preparations, REST callers send Prefer: respond-async; MCP handles supported preparations asynchronously. Follow the returned operation ID.
Download an existing export¶
Read the job’s mesh_exports to select the requested mesh format and primary artifact; do not pick the first artifact arbitrarily. get_artifact_download returns a fresh download/transfer contract. Stream the file to its requested destination and verify the checksum when saving programmatically. Request a new download link if an old link expires.
Downloads and viewer links are different. A browser link is not evidence that a file was saved locally. Keep capability links private.