# GET /v1/files

> 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).

In [Files API](https://vestra.ai/developers/reference/api/files.md): Files Bash makes, and files you hand it.

Send `Authorization: Bearer vk_test_...` on every call.

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).

Your API key, scope `runtime` or `all`. On the card: [`files`](https://vestra.ai/developers/files.md). Every call here is a checked sample.

## Request

Query:

- `limit` (`integer`): How many items per page, 1 to 100. Default 20.
- `cursor` (`string`): Where to go on from: the `next_cursor` of the page before, unchanged. Absent: the first page.
- `user_id` (`string`): One user's files, by your id for them. Absent: your company's own Bash's.
- `task_id` (`string`): What one task made (task_...): outputs only.
- `conversation_id` (`string`): One conversation's files, from all its tasks (conv_...).
- `source` (`"upload" | "output"`): Only uploads or only outputs. Default: outputs with task_id or conversation_id, uploads without.

## Answers 200

- `data` (`object[]`): The items on this page.
  - `id` (`string`): The file (file_...): hand it to an ask as an attachment. Example: `file_2nq`.
  - `object` (`"file"`): Always file.
  - `user_id` (`string | null`): Your id for its user; null on your company's own Bash.
  - `filename` (`string | null`): The file's name; null when it has none. Example: `itinerary.pdf`.
  - `mime_type` (`string | null`): Its type, such as application/pdf; null when unknown.
  - `size_bytes` (`integer | null`): Its size, in bytes; null when unknown.
  - `source` (`"upload" | "output"`): upload: a file you handed Bash. output: a file Bash made.
  - `task_id` (`string | null`): The task it belongs to (task_...): the one that made it, or used it; null when none did.
  - `conversation_id` (`string | null`): The conversation of its task (conv_...); null for a file no task touched.
  - `created_at` (`string`): When it was made or uploaded, as an ISO 8601 time.
- `next_cursor` (`string | null`): Send it as `cursor` for the next page; null on the last page.

## Code

**TypeScript**

```ts
const files = await vestra.files.list();
```

**Python**

```python
files = vestra.files.list()
```

**CLI**

```bash
vestra files
```

**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" }
  }
}
```