Skip to main content
The storage module uploads files and images to managed cloud storage and returns proxy URLs, plus reads and deletes existing files. Uploads are sent as multipart/form-data — pass a browser File (e.g. from an <input type="file">) or a Blob. There is no Uint8Array + mimeType path; the browser supplies the content type.
Uploads are attributed to the logged-in user automatically (from the token) — there is no userId param. A user may delete files they own; reads are project-scoped.

​
uploadFile

Uploads a generic file (PDF, video, document, …) without server-side processing. 
const input = document.querySelector('input[type="file"]');
const file = input.files[0];

const uploaded = await sublay.storage.uploadFile({
  file,
  filename: "report.pdf",
  pathParts: ["documents", "reports"],
  entityId: "ent_xyz789",
});
// uploaded.publicPath → proxy URL
​
file
Blob | File
required
The file to upload, as a browser File or Blob.
​
pathParts
string[]
required
Storage path segments. The file is stored under the joined path with a UUID sub-folder appended, e.g. ["documents", "reports"] → documents/reports/<uuid>/<filename>.
​
filename
string
Filename for the multipart part. Defaults to the File.name, or "upload".
​
position
number
Display order when a record has multiple attachments.
​
metadata
object
Custom key-value data stored alongside the file record.
​
entityId
string
Associates the file with an entity for cascade deletion. Only one of entityId / commentId / spaceId may be set.
​
commentId
string
Associates the file with a comment for cascade deletion.
​
spaceId
string
Associates the file with a space.
Returns — Promise<UploadFileResponse>: 
{
  fileId: string;
  type: string;
  relativePath: string;
  publicPath: string; // proxy URL
  size: number;
  mimeType: string;
  createdAt: string;
}

​
uploadImage

Uploads an image, processes it server-side, and stores the original plus all requested variants. The imageOptions object is a discriminated union on mode — the other fields depend on the mode you pick. 
const input = document.querySelector('input[type="file"]');
const file = input.files[0];

const uploaded = await sublay.storage.uploadImage({
  file,
  filename: "avatar.png",
  imageOptions: {
    mode: "exact-dimensions",
    dimensions: {
      thumbnail: { width: 64, height: 64 },
      card: { width: 400, height: 300 },
    },
    format: "webp",
    quality: 85,
  },
  pathParts: ["avatars"],
});
// uploaded.variants → { thumbnail: {...}, card: {...} }
​
file
Blob | File
required
The image to upload, as a browser File or Blob. Must be a format the server can process.
​
imageOptions
ImageOptions
required
Image-processing configuration — a discriminated union on mode. The supported modes and their required fields:
modeRequired fieldsNotes
exact-dimensionsdimensions ({ [variant]: { width, height } })Fixed-size crops.
aspect-ratio-width-basedaspectRatio, widths ({ [variant]: number })Heights computed from the ratio.
aspect-ratio-height-basedaspectRatio, heights ({ [variant]: number })Widths computed from the ratio.
original-aspectsizes ({ [variant]: number })Preserves source ratio; fit limited to inside/outside.
multi-aspect-ratioaspectRatios ({ width, height }[]), sizes1–10 aspect ratios.
All modes also accept optional quality (1–100), format (webp | jpeg | png | original), stripExif (boolean), and fit (cover | contain | inside | outside). Dimension/size values are 50–10000.
​
filename
string
Filename for the multipart part. Defaults to the File.name, or "upload".
​
pathParts
string[]
Storage path segments. Defaults to ["images", "<fileId>"].
​
entityId
string
Associates the image with an entity. Only one of entityId / commentId / spaceId may be set.
​
commentId
string
Associates the image with a comment.
​
spaceId
string
Associates the image with a space.
Returns — Promise<UploadImageResponse>: 
{
  fileId: string;
  type: "image";
  originalPath: string;
  originalSize: number;
  originalWidth: number;
  originalHeight: number;
  variants: Record<string, UploadedImageVariant>; // { path, width, height, size, format, publicPath }
  format: string;
  quality: number;
  createdAt: string;
}

​
getFile

Fetches a file’s metadata and proxy URLs by ID. For images, an image extension (variants, processing details) is included. Reads are project-scoped. 
const file = await sublay.storage.getFile({ fileId: "fil_abc123" });
​
fileId
string
required
The ID of the file to retrieve.
Returns — Promise<GetFileResponse> — a flat projection carrying fileId, type, originalPath, originalSize, originalMimeType, position, metadata, createdAt/updatedAt, the optional association ids (userId, entityId, commentId, spaceId), and — for images — an image object with variants, processingStatus, format, quality, and exifStripped.

​
deleteFile

Deletes a file record and removes all associated storage objects (for images, every generated variant too). 
await sublay.storage.deleteFile({ fileId: "fil_abc123" });
​
fileId
string
required
The ID of the file to delete.
Returns — Promise<void>
The call only succeeds when the logged-in user owns the file; otherwise it returns 403.