Skip to content

Files

Upload one PNG, JPEG, WebP or PDF at a time, from 1 byte to 4 MiB. The declared MIME type must match the file signature. Send the file bytes; remote URLs and server filesystem paths are not accepted.

Files larger than 4 MiB (4,194,304 bytes) return HTTP 413 at REST before a backend call. MCP rejects oversized upload_file input with an input or tool error before calling REST. The limit is on decoded file bytes.

Terminal window
curl -X POST "$GLASSWISE_API_BASE_URL/v1/files" \
-H "Authorization: Bearer $TOKEN" \
-F "upload_id=$UPLOAD_UUID" \
-F "workspace_id=$WORKSPACE_ID" \
-F "purpose=image" \
-F "file=@bottle.png;type=image/png"

upload_id is a new UUID you generate before the request. An identical retry with the same workspace, purpose, filename, MIME type and bytes returns the same file. A changed request or an upload still in progress returns 409. All four multipart fields are required. Repeated fields, extra fields, empty files and null values are rejected.

The response contains id, name, mime_type and size in bytes. Uploading does not attach or publish the file. Use its id in an existing resource operation, such as a bottle format’s image_id. The resource must belong to the upload’s workspace and accept its purpose, even when you belong to both workspaces.

Purpose Intended attachment
image Bottle images, originals, winery logos and other image fields; PNG, JPEG or WebP
inspection_report A label’s inspection report; PDF
certificate A certificate file; PNG, JPEG, WebP or PDF
asset A media asset; image or PDF
conformity_declaration A declaration of conformity; PDF
data_sheet A data sheet; PDF
qr, export Standalone files in the supported upload formats

These purposes describe file ownership. They do not add resource creation, QR generation or export operations. Existing authorized files can be downloaded regardless of their upload format, including generated ZIP and spreadsheet exports.

GET /v1/files/{id} returns metadata. GET /v1/files/{id}/download returns { "url": "https://…", "expires_in": 60 }. Expiration may be shorter. Follow the link to retrieve bytes; it is a bearer capability until it expires. Request a fresh link after expiry. Responses must not be cached.

Current workspace members can read managed uploads. Existing files are readable through an attached resource in a workspace you belong to. Existing unattached generated exports are readable only by their uploader. A public bucket alone does not authorize access through this API. Unknown and unauthorized file identifiers return 404. Uploading or reading a file does not grant permission to publish a label or use a gated resource feature.

Attached presentation files are readable by anyone with their plain file URL: bottle and format images, retained originals, wine images, company logos in every role (including producer, bottler and distributor), event images, media-kit team, award and product-card images, media assets and certificates. This includes draft presentation images and draft media kits, so the existing previews and PDF renderer can display them. Data sheets and conformity declarations become public only through a published label. Inspection reports remain private even on published labels. Unattached managed uploads remain private to current workspace members. Shared catalogue certificates can be downloaded through this API when one of your workspace’s labels references them.

DELETE /v1/files/{id} removes only your own managed upload while you remain a member of its workspace. Detach it from every resource first. Any remaining reference, including a gallery, declaration or shared image, returns 409. Deletion does not detach records for you. Files uploaded through older workflows must be removed through their owning resource workflow.

A successful delete returns { "deleted": true }; repeating it returns the same result. A failed byte cleanup remains retryable with DELETE. An interrupted upload can be cleaned up with its upload_id after ten minutes. During upload or cleanup the file cannot be attached or downloaded. After cleanup, use a new upload UUID. There is no automatic orphan expiry.

Use upload_file with upload_id, workspace_id, purpose, name, mime_type and content_base64. The decoded limit is also 4 MiB. get_file, get_file_download and delete_file take id. The connector sends multipart bytes to the API and returns download links rather than large base64 responses.