# files

> Upload files for your agent, and download the files it makes.

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.

## TypeScript

```ts
const traveller = vestra.user('traveller-42');

// Upload a file. Pass a path, a Blob or bytes, up to 10 MB. Then ask about it.
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.
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);
}
```

## Python

```python
traveller = vestra.user("traveller-42")

# Upload a file. Pass a path, an open file or bytes, up to 10 MB. Then ask about it.
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.
for file in vestra.files.list(conversation=run.conversation).data:
    print(file.filename, len(vestra.files.download(file.id)))
```

## CLI

```bash
# Upload a file. It can be up to 10 MB.
vestra files add ticket.pdf --user traveller-42

# Download what Bash made. List one conversation's files, and download one into this folder.
vestra files conv_8f2k
vestra files get file_2kq
```

## HTTP

```bash
# Upload a file. Send it for one user as multipart form data, with one part named file, up to 10 MB.
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.
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.
curl "$VESTRA_BASE_URL/v1/files/file_2kq" \
  -H "Authorization: Bearer $VESTRA_API_KEY"
```

## MCP

```json
{
  "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 files

- `POST` [/v1/files](https://vestra.ai/developers/reference/api/files/post-v1-files.md): Upload 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/files](https://vestra.ai/developers/reference/api/files/get-v1-files.md): Files, 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}](https://vestra.ai/developers/reference/api/files/get-v1-files-file-id.md): Details and a short-lived download link. Key scope: `runtime` (or `all`).
- `DELETE` [/v1/files/{file_id}](https://vestra.ai/developers/reference/api/files/delete-v1-files-file-id.md): Delete it. Key scope: `runtime` (or `all`).

Next: [`connect`](https://vestra.ai/developers/connect.md)