> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://platform.bctrl.ai/llms.txt.
> For full documentation content, see https://platform.bctrl.ai/llms-full.txt.

# Space Storage

> Upload, download, and browse durable files scoped to a space.

Space storage is the durable file layer for a space. Use it for inputs, exports, CSVs, PDFs, screenshots, logs, and files that should be reused across runtimes, invocations, and runs.

The preferred SDK entrypoint is `space.storage.files`.

```ts
const space = await bctrl.spaces.get("spc_123");

const uploaded = await space.storage.files.upload(csvBuffer, {
  path: "inputs/report.csv",
  contentType: "text/csv",
});
```

## Upload a file

```ts
const file = await space.storage.files.upload(pdfBytes, {
  path: "inputs/invoice.pdf",
  contentType: "application/pdf",
});

console.log(file.id, file.path);
```

| Parameter             | Type                           | Required | Description                                          |
| --------------------- | ------------------------------ | -------- | ---------------------------------------------------- |
| `data`                | `Buffer \| Uint8Array \| Blob` | Yes      | File content.                                        |
| `options.path`        | `string`                       | No       | Durable path inside the space.                       |
| `options.name`        | `string`                       | No       | Display filename. Defaults from `path` when omitted. |
| `options.contentType` | `string`                       | No       | MIME type for the uploaded file.                     |

## List files

```ts
const { files, nextCursor } = await space.storage.files.list({
  prefix: "inputs/",
  limit: 20,
});

for (const file of files) {
  console.log(file.id, file.path, file.sizeBytes);
}
```

| Parameter | Type     | Required | Description                        |
| --------- | -------- | -------- | ---------------------------------- |
| `prefix`  | `string` | No       | Restrict results to a path prefix. |
| `limit`   | `number` | No       | Max results.                       |
| `cursor`  | `string` | No       | Cursor from a previous page.       |

## Get metadata

```ts
const file = await space.storage.files.get(uploaded.id);
console.log(file.path, file.contentType);
```

## Download a file

```ts
const bytes = await space.storage.files.download(uploaded.id);
```

## Delete a file

```ts
await space.storage.files.delete(uploaded.id);
```

## Mount a storage namespace

Spaces can mount a shared storage namespace when several spaces should see the same durable files.

```ts
const space = await bctrl.spaces.create({
  name: "invoice-agent",
  mounts: {
    storage: {
      space: "shared-invoices",
    },
  },
});
```

## Space storage vs runtime files

Space storage is durable cloud storage.

Runtime files are files inside a live runtime. Use runtime file staging to move a storage file into a runtime, and collection to copy a runtime-local file back into storage.

```ts
const staged = await runtime.files.stage({
  fileId: uploaded.id,
});

const collected = await runtime.files.collect({
  path: "/tmp/output.csv",
  storagePath: "outputs/output.csv",
});
```

## Related

* [Storage](/sdk/core-concepts/storage)
* [Runtime Files](/api/api-reference/runtime-files/stage-file)
* [Run Artifacts](/sdk/observability/run-artifacts)