Files & outputs

Project files

A file (file_…) belongs to a project. Upload it once (up to 1 GiB, streamed) and mount it into any number of sessions. Mounting never copies the bytes.

Action	Request (`/v1`)
Upload	`POST /v1/files` (multipart `file`)
List	`GET /v1/files?limit=&page=&scope_id=&metadata=key:value`
Metadata / download / delete	`GET /v1/files/{id}`, `GET /v1/files/{id}/content`, `DELETE /v1/files/{id}`
Mount into a session	`resources` on `POST /v1/sessions`, or `POST /v1/sessions/{id}/resources`

BMA extensions on files: Idempotency-Key on upload, X-BMA-File-Metadata (up to 16 string labels) with metadata=key:value filters, and a sha256 digest (X-BMA-File-Digest on downloads). A project may hold up to 100 GiB of files by default.

curl -sS "$BMA_BASE_URL/v1/files" \
  -H "x-api-key: $BMA_API_KEY" -H "anthropic-version: 2023-06-01" -H "anthropic-beta: files-api-2025-04-14" \
  -H "x-bma-project-id: $BMA_PROJECT_ID" \
  -H 'Idempotency-Key: upload-42' \
  -F file=@report.pdf

Inside the machine

Path	Mode	Content
`/mnt/session/uploads/…`	read-only	The session’s files, mounted as a file system; a file is fetched when it is first opened
`/mnt/session/outputs/…`	writable	Anything the agent writes here is collected by BMA as a session file
`/mnt/skills/<skill>/…`	read-only	The skills bound to the agent, one directory each (`SKILL.md` and supporting files)
`/mnt/memory/<store>/…`	per store	The memory stores attached to the session, readable as files; writing needs a `read_write` attachment

Files under outputs belong to the session and survive machine pause, rebuild and deletion. Writing the same path again creates a new version; every version stays readable by id. How the mounts behave:

Read on demand. Nothing is copied before a command starts. Files added to or removed from the session show up in about a second.
Inputs are read-only. Writing under uploads or skills fails with Read-only file system; write results to outputs.
Skills are already there. The skill tool returns the instructions and the directory under /mnt/skills; it installs nothing on machines that mount it.
No storage credentials on the machine. The mounts use a short-lived token scoped to the session and held in memory; it is renewed automatically, including in sessions that run for hours.
Failures recover by themselves. If the mount process crashes, the mount is restored in about a second without restarting the machine. It is also restored after a network drop, a pause and resume, or a server failover. While a file cannot be reached, reads fail with an error instead of returning stale or empty data.
Fallback. Machines that cannot mount (your own executors, macOS and Windows) get the same paths filled by copying files in before commands start, and outputs is scanned and uploaded.

Session files (BMA extension)

For apps that want to hand a file to one session without managing project files, the /v1 API adds:

POST /v1/sessions/{id}/files (multipart file): upload to the session
GET /v1/sessions/{id}/files?limit=&page=: what was uploaded, what the agent produced (source: upload, agent, memory)
GET /v1/sessions/{id}/files/{file_id}/content: download, with X-BMA-File-Digest

Each returned file has a path you can give the agent verbatim. Call them with the generic request methods of the official SDKs or plain HTTP.

Get started

Concepts

Executor & brains

Project files

Inside the machine

Session files (BMA extension)

​Project files

​Inside the machine

​Session files (BMA extension)

Project files

Inside the machine

Session files (BMA extension)