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

# File Upload

> Upload files to knowledge sources via the REST API or MCP

Upload a file (PDF, Word, PowerPoint, Excel, image, and more) to a knowledge source. AGO converts its content to Markdown, creates a new draft document with it, and keeps the original file as an attachment of that document.

## Supported File Types

| Category | MIME Types |
| - | - |
| Documents | `application/pdf`, `application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/vnd.ms-word.document.macroEnabled.12`, `application/vnd.ms-powerpoint`, `application/vnd.openxmlformats-officedocument.presentationml.presentation`, `application/vnd.ms-excel`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |
| Text | `text/plain`, `text/markdown`, `text/x-markdown`, `text/csv`, `text/html`, `application/json`, `application/xml`, `text/xml` |
| Images | `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/bmp`, `image/tiff` |
| Archives | `application/zip`, `application/x-zip-compressed`, `application/epub+zip` |

Plain text and Markdown files must use UTF-8 encoding.

## Size Limit

The maximum file size is **20 MB**.

## REST API

### Upload a File

```
POST /api/v1/sources/{source_id}/upload
```

**Scope required:** `knowledge:write`

Send the file as `multipart/form-data`.

**Parameters:**

| Parameter | Type | Required | Description |
| - | - | - | - |
| `file` | file | Yes | The file to upload |
| `title` | string | No | Document title. Defaults to filename without extension. |
| `default_language` | string | No | Language code (default: `en`) |

**Example:**

```bash theme={null}
curl -X POST https://your-workspace.api.useago.com/api/v1/sources/{source_id}/upload \
  -H "X-API-Key: ago_v1_sk_your_key_here" \
  -F "file=@report.pdf" \
  -F "title=Quarterly Report" \
  -F "default_language=en"
```

**Response (201)**, shortened:

```json theme={null}
{
  "object": "document",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Quarterly Report",
  "content": "# Quarterly Report\n\nExtracted markdown content...",
  "source_id": "660e8400-e29b-41d4-a716-446655440000",
  "source_name": "Company Docs",
  "status": "draft",
  "default_language": "en",
  "created_at": "2026-02-24T10:30:00Z"
}
```

## MCP

### upload\_source\_file

Upload a file to a knowledge source via the MCP JSON-RPC interface. The file content must be base64-encoded.

**Scope required:** `knowledge:write`

**Parameters:**

| Parameter | Type | Required | Description |
| - | - | - | - |
| `source_id` | string (uuid) | Yes | Target knowledge source ID |
| `file_name` | string | Yes | Original filename with extension (e.g., `report.pdf`) |
| `file_data` | string | Yes | Base64-encoded file content |
| `file_type` | string | No | MIME type. Guessed from filename if omitted. |
| `title` | string | No | Document title. Defaults to filename without extension. |
| `default_language` | string | No | Language code (default: `en`) |

**Example:**

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "upload_source_file",
    "arguments": {
      "source_id": "660e8400-e29b-41d4-a716-446655440000",
      "file_name": "report.pdf",
      "file_data": "JVBERi0xLjQK...",
      "title": "Quarterly Report"
    }
  }
}
```

## Error Handling

Upload errors return `422` with one of these codes:

| Error Code | Description |
| - | - |
| `empty_file` | The uploaded file is empty |
| `file_too_large` | File exceeds the 20 MB size limit |
| `unsupported_file_type` | The file's MIME type is not supported; the message lists the supported types |
| `invalid_encoding` | A text or Markdown file is not UTF-8 |
| `extraction_failed` | AGO could not read text from the file |
| `invalid_base64` | The `file_data` field is not valid base64 (MCP only) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.