Files

A File is durable storage owned by a Space. It can be uploaded by your application, produced by a Runtime, or exported from a Run. The File resource is the durable record; a Runtime workspace is only the live machine disk used while automation is running.

Three file surfaces

Files produced by a Runtime can be collected into durable storage and remain available after the Run ends. Files staged into a Runtime are copies for that Runtime workspace; staging does not move or delete the durable File.

Upload a File

The Space can be omitted to use the caller’s default Space:

1
const file = await bctrl.files.upload({
2
  file: new Blob(["name,email\n[email protected]"]),
3
  name: "contacts.csv",
4
  path: "imports/2026/contacts.csv",
5
  metadata: { source: "crm" },
6
});
7
8
console.log(file.id, file.path, file.source);

file is a Blob. name, path, and metadata are optional. Use spaceId when uploading to a Space other than the caller’s default:

1
await bctrl.files.upload({
2
  spaceId: "space_production",
3
  file,
4
  path: "incoming/report.pdf",
5
});

Paths are relative to the Space’s storage namespace. Use a path prefix to organize files; absolute paths and ./.. path segments are not allowed.

List and browse Files

1
const page = await bctrl.files.list({
2
  prefix: "imports/2026/",
3
  source: "upload",
4
});
5
6
for await (const file of bctrl.files.iter({ type: "download" })) {
7
  console.log(file.name, file.sizeBytes, file.contentType);
8
}

list() returns one cursor page. iter() follows all pages automatically. Available filters are:

To render a folder tree, request folder summaries:

1
const { data, folders } = await bctrl.files.list({
2
  prefix: "imports/",
3
  include: "folders",
4
});
5
6
for (const folder of folders ?? []) {
7
  console.log(folder.path, folder.fileCount, folder.totalBytes);
8
}
9
10
for (const file of data) {
11
  console.log(file.path);
12
}

With include: "folders", data contains files directly under the requested prefix and folders contains immediate child-folder rollups.

Read, download, update, and delete

1
const file = await bctrl.files.get(fileId);
2
3
const response = await bctrl.files.content(file.id);
4
const bytes = await response.arrayBuffer();
5
6
await bctrl.files.update(file.id, {
7
  name: "contacts-reviewed.csv",
8
  metadata: { reviewed: true },
9
});
10
11
await bctrl.files.delete(file.id);

The File resource also includes downloadUrl when you want to download through the returned URL instead of files.content().

File fields

Runtime workspace files

Use the built-in File Tools to transfer files through a live Runtime workspace:

1
await bctrl.tools.call("runtime.files.stage", {
2
  fileId: file.id,
3
  path: "contacts.csv",
4
}, { runtimeId });
5
6
const collected = await bctrl.tools.call("runtime.files.collect", {
7
  path: "result.json",
8
}, { runtimeId });
9
10
console.log(collected.fileId);

See Stage Runtime file and Collect Runtime file for the Tool fields and path rules. Runtime workspace paths are relative to the workspace; use path, not an absolute host path or the old runtimePath name.

Run files

List durable Files attached to one Run:

1
const runFiles = await bctrl.runs.files.list(runId);
2
for (const file of runFiles.data) {
3
  console.log(file.fileId, file.name, file.size);
4
}

Use run.files.export when you want to combine selected Run files into one durable archive File.

Next

• Spaces — configure the storage namespace available to a Space
• Runtimes — run automation that can produce workspace files
• Runs — inspect the execution that produced a File