Every sample on every page follows this. Change it any time.

Get a test key
BashBrainTeammatesPricingDevelopersGet a test key

files

Upload files for Bash to use, and download the files it makes. Every file it makes records its task and its conversation, so one call lists everything a conversation produced.

Upload a file

Pass a path, a Blob or bytes, up to 10 MB. Then ask about it.

TypeScript
const traveller = vestra.user('traveller-42'); const ticket = await traveller.files.upload('./ticket.pdf');const run = traveller.ask('Is this ticket refundable?', { attachments: [ticket.id] });await run.text();

Download what Bash made

List one conversation's files, or one task's, and download each one.

TypeScript
const made = await vestra.files.list({ conversation: run.conversation! });for (const file of made.data) {  const bytes = await vestra.files.download(file.id);  console.log(file.filename, bytes.byteLength);}

Upload a file

Pass a path, an open file or bytes, up to 10 MB. Then ask about it.

Python
traveller = vestra.user("traveller-42") ticket = traveller.files.upload("ticket.pdf")run = traveller.ask("Is this ticket refundable?", attachments=[ticket.id])run.text()

Download what Bash made

List one conversation's files, or one task's, and download each one.

Python
for file in vestra.files.list(conversation=run.conversation).data:    print(file.filename, len(vestra.files.download(file.id)))

Upload a file

It can be up to 10 MB.

CLI
vestra files add ticket.pdf --user traveller-42

Download what Bash made

List one conversation's files, and download one into this folder.

CLI
vestra files conv_8f2kvestra files get file_2kq

Upload a file

Send it for one user as multipart form data, with one part named file, up to 10 MB.

HTTP
curl "$VESTRA_BASE_URL/v1/files?user_id=traveller-42" \  -H "Authorization: Bearer $VESTRA_API_KEY" \  -F "file=@ticket.pdf"

Download what Bash made

List one conversation's files (its tasks' outputs), or one task's.

HTTP
curl "$VESTRA_BASE_URL/v1/files?conversation_id=conv_8f2k" \  -H "Authorization: Bearer $VESTRA_API_KEY"

Get one file

The response has a download link that works for a short while.

HTTP
curl "$VESTRA_BASE_URL/v1/files/file_2kq" \  -H "Authorization: Bearer $VESTRA_API_KEY"
MCP
{  "method": "tools/call",  "params": {    "name": "files",    "arguments": { "user": "traveller-42", "conversation": "conv_8f2k" }  }}

Good to know

Outputs and uploads

A file's source is output if Bash made it, and upload if you uploaded it. Listing by task or conversation returns outputs. Listing by user returns uploads, unless you pass source.

Uploading

POST /v1/files takes multipart form data with one part named file, up to 10 MB. To use the file in an ask, pass its id as an attachment.

Download links

GET /v1/files/{id} returns a download link that works for a short while. To get a fresh link, read the file again.

When Bash makes a file

The file.created event names the new file, on the stream and on your webhooks.

The routes behind files4 routes, each with every field in the API reference
POST/v1/filesUpload a file for Bash to use: multipart/form-data with one part named file. user_id in the query names whose Bash it is for; without it, the company's own.Key scope: runtime (or all)
GET/v1/filesFiles, each with its task and conversation: one user's (user_id) or the company's own Bash's, one task's outputs (task_id), or one conversation's, its tasks' outputs (conversation_id). source picks what you handed Bash (upload) or what Bash made (output).Key scope: runtime (or all)
GET/v1/files/{file_id}Details and a short-lived download link.Key scope: runtime (or all)
DELETE/v1/files/{file_id}Delete it.Key scope: runtime (or all)