iotoms Docs

Upload a file

POST
/api/v1/storage/uploads

Uploads a file as multipart form data in the file field and returns where it is stored, with a permanent public URL and a temporary signed URL. Accepts images, CSV, PDF, plain text and JSON up to a size limit. Files may be compressed on storage. Counts toward the merchant's storage quota.

How to use it

  1. Send the file in the multipart field named file; images, CSV, PDF, plain text and JSON are accepted, empty files are refused.
  2. Optionally pass checksum as the Base64 SHA-256 of the file so a corrupted upload is rejected.
  3. Save the returned publicUrl on the record that uses it, e.g. an item image. The stored size counts toward the storage quota.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Query Parameters

checksum?string

Optional Base64-encoded SHA-256 digest of the file. When sent, the upload is rejected if the content does not match.

Request Body

multipart/form-data
  1. body
file*unknown

Response Body

OK

*/*
  1. response
fileId*string

ID of the stored file record. Set by the server.

Formatuuid
bucket*string

Name of the storage bucket the file was written to.

objectName*string

Path of the file inside the storage bucket.

mediaType*string

Media type of the file, e.g. image/png. Taken from the upload, or detected from its content when not supplied.

contentEncoding?|

gzip when the file is stored gzip-compressed; empty otherwise.

sizeBytes*integer

Size of the file you uploaded, in bytes.

Formatint64
compressedSizeBytes?|

Size actually stored after compression, in bytes; empty when no compression was applied.

Formatint64
compressionApplied*boolean

True when the server stored a smaller compressed copy of the file.

compressionRatio?|

Share of the original size saved by compression, from 0 to 1 (e.g. 0.4 = 40% smaller); empty when not compressed.

Formatdouble
publicUrl*string

Permanent URL of the stored file. Save this on the record that uses it, e.g. an item image.

signedUrl*string

Temporary pre-signed URL for reading the file; it expires after a configured number of minutes.

checksum?|

The checksum you sent, echoed back once verified; empty if none was sent.

Example Request
curl -X POST 'https://beta.iotoms.com/api/v1/storage/uploads' \  -F 'file=null'
Example Response
{  "fileId": "a1c6a2ab-4b01-4253-b4c9-70e04b3b48fc",  "bucket": "string",  "objectName": "string",  "mediaType": "string",  "contentEncoding": "string",  "sizeBytes": 0,  "compressedSizeBytes": 0,  "compressionApplied": true,  "compressionRatio": 0,  "publicUrl": "string",  "signedUrl": "string",  "checksum": "string"}