Files and attachments

import { blob } from "platform:blob";

Two concepts: a blob is stored bytes, an attachment links a blob to a record. Uploading and attaching are separate steps, so one file can hang off several records without being stored twice.

blob.upload

const record = await blob.upload({
  filename: "report.csv",
  mimeType: "text/csv",
  data: new TextEncoder().encode(csv),
});

data is a Uint8Array. Returns a BlobRecord whose id you attach with.

blob.attach

await blob.attach(issue.record_id, record.blob_id, {
  fieldKey: "evidence",
  displayOrder: 0,
});

Argument	Purpose
recordId	Record to attach to
blobId	Blob to attach
fieldKey	Groups attachments under a named field
displayOrder	Sort order, defaults to 0

blob.listAttachments

const attachments = await blob.listAttachments(issue.record_id);

blob.getData

const { data, filename, mimeType } = await blob.getData(blobId);
const text = new TextDecoder().decode(data);

Whole file in memory

getData returns the entire file as a Uint8Array — there is no streaming. Guest processes run under a memory governor, so reading a large upload can kill the process. Check size before fetching bytes you do not need.

Removing

await blob.removeAttachment(attachmentId); // unlink, keep the blob
await blob.delete(blobId);                 // delete the bytes

Removing an attachment leaves the blob, which matters when it is attached elsewhere. Deleting the blob affects every record referencing it.

Size limits

Uploads are capped server-side, 100 MB by default. Exceeding it fails the call.