Upload one or more files to a knowledge base root or to a specific folder.

Overview

Batch upload multiple files in a single request. Each file becomes a new record with automatic content indexing. Omit the folderId query parameter to upload to the KB root; include it to upload into that folder.

Upload Limits

• Max files per request: 1000
• Default max file size: 30MB (configurable via platform settings)
• Use GET /knowledgeBase/limits to check current limits

Supported File Types

Documents (PDF, DOCX, DOC, XLS, XLSX, PPT, PPTX, TXT, CSV, MD), Images (PNG, JPG, JPEG, SVG, WebP), Web (HTML, HTM), and Google Workspace formats.

File Metadata

Use files_metadata to provide additional info like file paths and last modified timestamps. A path with folders (docs/2026/a.txt) creates those folders, as a folder upload does.

Rejected files

A file whose extension is not supported, or that is larger than the size limit, does not fail the request: it is reported as a file:failed event (reason UNSUPPORTED_TYPE or EXCEEDS_SIZE_LIMIT, stage: upload) and the other files go on. A file whose name is already used in the same place fails the same way with reason DUPLICATE_NAME and stage: index. The request still answers 200 when every file failed. There is no 413.

Ignored fields

recordName, recordType and origin are validated (non-empty, and recordName is checked for HTML and format specifiers) but do not affect the records: each record is named after its file, with origin UPLOAD and type FILE. Other fields and unknown query parameters are ignored; rejectedFiles and fileBuffers are set by the gateway itself, so a value sent for them is replaced.

Access

OWNER and WRITER may upload. A READER gets 403; a caller with no role on the knowledge base gets 404. Only a multipart body is read: a JSON body has no files and is refused with 400.

Versioning

Set isVersioned: true to enable version tracking for uploaded files.

Streaming response

This endpoint responds with Content-Type: text/event-stream. The upload and its per-file progress are a single request: the body streams a file:succeeded or file:failed event per file (including files rejected up front for size/type), followed by a final done summary, then closes. See the UploadStreamSSEEvent schema for the event/payload contract.