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	Managed Agents API (`/v1`)	Native API (`/api/v1/orgs/{org}/projects/{project}`)
Upload	`POST /files` (multipart `file`)	`POST /files?filename=…` (`application/octet-stream`)
List	`GET /files?limit=&page=&scope_id=&metadata=key:value`	same
Metadata / download / delete	`GET /files/{id}`, `GET /files/{id}/content`, `DELETE /files/{id}`	same
Mount into a session	`resources` on `POST /sessions`, or `POST /sessions/{id}/resources`	`POST /agents/{agent}/sessions/{id}/resources`
Promote a session artifact to a project file	—	`POST /agents/{agent}/sessions/{id}/artifacts/{artifact_id}/promote`

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 "x-bma-project-id: $BMA_PROJECT_ID" \
  -H 'Idempotency-Key: upload-42' \
  -F file=@report.pdf

Inside the machine

Path	Content
`/mnt/session/uploads/…`	Mounted files, read-only, synced before each command starts
`/mnt/session/outputs/…`	Anything the agent writes here is uploaded to BMA as a session file

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.

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. Typed helpers: uploadSessionFile / listSessionFiles / downloadSessionFile in bma-sdk.

Artifacts (native API)

Large tool output and agent uploads are stored as artifacts with a size and sha256 digest. bma-sdk downloads them with DownloadArtifact / downloadArtifact / download_artifact, which verify both.

Get started

Concepts

Executor & brains

Project files

Inside the machine

Session files (BMA extension)

Artifacts (native API)

​Project files

​Inside the machine

​Session files (BMA extension)

​Artifacts (native API)

Project files

Inside the machine

Session files (BMA extension)

Artifacts (native API)