File Uploads & Downloads

File fields store a fileId string. This page covers the full lifecycle: uploading a file and retrieving a download URL.

requestFileUpload(options, signal?)

Requests a presigned upload URL.

1const upload = await sdk.requestFileUpload({2  fieldKey: 'attachment',         // the file field key in your entity schema3  fileName: 'invoice.pdf',4  mimeType: 'application/pdf',    // optional but recommended5  sizeBytes: file.size,6});78// upload.fileId     — the ID to store on the record9// upload.uploadUrl  — presigned PUT URL (expires in ~15 minutes)10// upload.headers    — headers to include in the PUT request

Upload the File

After receiving the presigned URL, PUT the file bytes directly to storage. The file never passes through your app's server.

1await fetch(upload.uploadUrl, {2  method: 'PUT',3  headers: {4    'Content-Type': file.type,5    ...upload.headers,6  },7  body: file,   // File or Blob8});

Save the fileId on the Record

After the upload completes, store the fileId in the record:

1await sdk.updateRecord('expenses', recordId, {2  attachment: upload.fileId,3});

Complete Example

1async function uploadAttachment(recordId, file) {2  // 1. Request presigned URL3  const upload = await sdk.requestFileUpload({4    fieldKey: 'attachment',5    fileName: file.name,6    mimeType: file.type,7    sizeBytes: file.size,8  });910  // 2. Upload directly to storage11  const uploadResponse = await fetch(upload.uploadUrl, {12    method: 'PUT',13    headers: { 'Content-Type': file.type, ...upload.headers },14    body: file,15  });1617  if (!uploadResponse.ok) {18    throw new Error('Upload to storage failed');19  }2021  // 3. Save fileId on the record22  await sdk.updateRecord('expenses', recordId, {23    attachment: upload.fileId,24  });25}

Expired URL: If the presigned URL expires before the upload completes, call requestFileUpload again to obtain a fresh URL and retry the PUT.

getFileUrl(fileId, signal?)

Returns a presigned download URL for a file attachment. Use this whenever you need to display or download a file stored in a file field.

1const file = await sdk.getFileUrl(record.attachment);2// file.url         — presigned download URL (valid for ~1 hour)3// file.fileName    — original file name as uploaded4// file.mimeType    — MIME type, or null if not recorded at upload5// file.expiresAt   — ISO 8601 expiry timestamp

Opening the file in a new tab:

1const file = await sdk.getFileUrl(record.attachment);2window.open(file.url, '_blank');

Triggering a download:

1const file = await sdk.getFileUrl(record.attachment);2const a = document.createElement('a');3a.href = file.url;4a.download = file.fileName;5a.click();

Expiry: The presigned URL is valid for ~1 hour. Do not cache it long-term — call getFileUrl again if you need a fresh URL.

Limits

Attempting to upload a file that exceeds the storage quota throws ErrorCode.StorageLimitReached.