# Files

> The runner files resource — upload, retrieve, and attach file IDs to a run.

Source: https://maincode.com/docs/agent-sdk-files
Section: Agent SDK · Matilda documentation

---

The `Runner` exposes a `files` resource for uploading and retrieving files. Uploaded files can be attached to agent runs via `fileIds`.

## `runner.files.upload(file, options?)`

Uploads a single file. Files at or above the server's chunked threshold use the parallel multipart protocol; smaller files use single-shot upload.

```ts
const file = new File(['Hello, world!'], 'hello.txt', { type: 'text/plain' });
const result = await runner.files.upload(file, {
  onProgress: (pct) => console.log(`Upload: ${pct}%`),
});
console.log(`File ID: ${result.fileId}, Status: ${result.status}`);
```

### `FileUploadOptions`

Extends `RequestOptions`. All fields optional.

| Field | Type | Description |
| - | - | - |
| `onProgress` | `(pct: number) => void` | Progress callback (0–100). |
| `signal` | `AbortSignal` | Abort the upload. |
| `fingerprint` | `string \| null` | Device fingerprint. |
| `accessToken` | `string \| null` | Override access token. |

Returns `Promise<FileCompleteResponse>`:

```ts
interface FileCompleteResponse {
  fileId: string;
  status: FileAttachmentStatus;
  failureReason?: FileFailureReason;
}

type FileAttachmentStatus = 'pending' | 'scanning' | 'processing' | 'ready' | 'failed' | 'rejected';
```

## `runner.files.uploadMany(files, options?)`

Uploads multiple files in parallel. One file's failure does not abort the others.

```ts
const files = [
  new File(['doc 1'], 'doc1.txt', { type: 'text/plain' }),
  new File(['doc 2'], 'doc2.txt', { type: 'text/plain' }),
];

const results = await runner.files.uploadMany(files);
for (let i = 0; i < results.length; i++) {
  const result = results[i];
  if (result.status === 'fulfilled') {
    console.log(`File ${i}: ${result.value.fileId} (${result.value.status})`);
  } else {
    console.error(`File ${i} failed:`, result.reason);
  }
}
```

Returns `Promise<PromiseSettledResult<FileCompleteResponse>[]>`.

## `runner.files.retrieve(fileId, options?)`

Retrieves metadata for a previously uploaded file.

```ts
const file = await runner.files.retrieve('file-abc123');
console.log(`${file.filename} — ${file.status} (${file.sizeBytes} bytes)`);
```

Returns `Promise<FileAttachment>`:

```ts
interface FileAttachment {
  id: string;
  filename: string;
  contentType: string;
  sizeBytes: number;
  status: FileAttachmentStatus;
  extractedText?: string;
  thumbnailUrl?: string;
  localUri?: string;
  failureReason?: FileFailureReason;
  createdAt: string;
}
```

## Using files in agent runs

Upload a file, then reference its `fileId` in an agent run:

```ts
const fileResult = await runner.files.upload(
  new File(['Quarterly report content...'], 'report.txt', { type: 'text/plain' }),
);

const result = await runner.run(
  { name: 'analyst', purpose: 'analysis', instructions: 'Summarise the report.' },
  'What are the key findings?',
  { fileIds: [fileResult.fileId] },
);
console.log(result.finalOutput);
```