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:

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:

{
  "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:

{
  "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)