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

import_surface_attachment

POST /v1/artifacts/attachment-imports

File is on an agent/CI machine

create_upload

POST /v1/artifacts/direct-uploads

User needs a browser picker

open_surface_upload

POST /v1/artifacts/browser-uploads

PDF, CSV, image or reference document

Design-source upload/import tools

/v1/design/sources/*

Artifact is already ready

get_artifact, then reuse

GET /v1/artifacts/{artifact_id}

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.