> ## Documentation Index
> Fetch the complete documentation index at: https://docs.svantic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# File handling

# File Handling & Uploads

Savant supports multiple ways to work with files — from inline attachments in messages to the server-side file storage API for large-file multimodal processing.

## File Upload Methods

| Method               | Best For                     | Max Size | How It Works                                  |
| -------------------- | ---------------------------- | -------- | --------------------------------------------- |
| **Inline text**      | Small text files (\< 100KB)  | \~100KB  | Sent as text in the message body              |
| **Inline base64**    | Small binary files (\< 20MB) | \~20MB   | Base64-encoded in the message body            |
| **File storage API** | Large files (up to 2GB)      | 2GB      | Uploaded to model provider, referenced by URI |
| **Artifact upload**  | Session-scoped storage       | 20MB     | Stored in-memory, accessible via tools        |

## Inline File Attachments

Send files directly as A2A `DataPart` content in your `POST /send` message, or via the REST API:

### Text Files

```json theme={null}
{
    "message": "Analyze this configuration",
    "session_id": "session-1",
    "files": [{
        "name": "config.json",
        "mime_type": "application/json",
        "size": 1024,
        "content": "{ \"key\": \"value\" }"
    }]
}
```

### Binary Files (Base64)

```json theme={null}
{
    "message": "What does this image show?",
    "session_id": "session-1",
    "files": [{
        "name": "screenshot.png",
        "mime_type": "image/png",
        "size": 204800,
        "data": "iVBORw0KGgoAAAANS..."
    }]
}
```

## File Storage API

For large files or when you want native multimodal processing:

### Step 1: Upload the File

**Via API:**

```bash theme={null}
curl -X POST http://localhost:3000/files/upload \
  -F "file=@./document.pdf"
```

**Via SDK:**

```typescript theme={null}
const ref = await session.upload_file_to_storage(
    fs.readFileSync('./document.pdf'),
    'document.pdf',
    'application/pdf',
);
// ref.file_uri → file storage URI for use in messages
```

**Via Base64:**

```bash theme={null}
curl -X POST http://localhost:3000/files/upload-base64 \
  -H "Content-Type: application/json" \
  -d '{
    "data": "JVBERi0xLjQ...",
    "mime_type": "application/pdf",
    "name": "document.pdf"
  }'
```

### Step 2: Reference in a Message

```json theme={null}
{
    "message": "Summarize this insurance policy",
    "session_id": "session-1",
    "files": [{
        "name": "policy.pdf",
        "mime_type": "application/pdf",
        "size": 1048576,
        "file_uri": "https://generativelanguage.googleapis.com/v1beta/files/abc123"
    }]
}
```

**Via SDK:**

```typescript theme={null}
const stream = session.send_with_files('Summarize this policy', [{
    name: 'policy.pdf',
    mime_type: 'application/pdf',
    size: 1048576,
    file_uri: ref.file_uri,
}]);
```

## Artifact Uploads

Artifacts are session-scoped file storage. Agents can access artifacts using the `read_artifact` tool.

### Upload

```bash theme={null}
curl -X POST http://localhost:3000/upload \
  -F "file=@./data.csv" \
  -F "user_id=my-user" \
  -F "session_id=session-1"
```

**Via SDK:**

```typescript theme={null}
const result = await session.upload_file(
    fs.readFileSync('./data.csv'),
    'data.csv',
    'text/csv',
);
```

### Response

```json theme={null}
{
    "success": true,
    "artifact_name": "data.csv",
    "mime_type": "text/csv",
    "size": 2048,
    "version": 0,
    "session_id": "session-1"
}
```

### Supported Artifact Types

| Category  | MIME Types                                           |
| --------- | ---------------------------------------------------- |
| Images    | `image/jpeg`, `image/png`, `image/gif`, `image/webp` |
| Documents | `application/pdf`                                    |
| Data      | `text/plain`, `text/csv`, `application/json`         |

## How Files Reach the Agent

When files are included in a message, they become **Content Parts** in the agent conversation:

| Attachment Type  | Part Type                                               |
| ---------------- | ------------------------------------------------------- |
| Text content     | `text` part (with filename header)                      |
| Base64 data      | `inlineData` part (native multimodal)                   |
| File storage URI | `fileData` part (fastest, no tool calls needed)         |
| Artifact ref     | `text` part (agent uses `read_artifact` tool to access) |

The foundation model processes images and PDFs natively — no OCR or extraction tools are needed for basic understanding.