Import Documents

On the knowledge base detail page, select Upload Documents to upload local files or Import from URL to add a web page or YouTube URL. Uploading only stores the file and creates a pending record; the document is parsed, chunked, embedded, and made searchable only after you process it.

Supported formats

Uploading files

1. On the knowledge base detail page select Upload Documents.
2. Drop files into the dialog or click to select them (multiple selection allowed).
3. The frontend validates each file's extension and size and immediately drops the files that fail.
4. Click Upload; the dialog shows upload progress.
5. Each file becomes a document with status pending.

Frontend validation only catches problems early — the server validates the extension and size again: an oversized file returns file_too_large and an unsupported one returns invalid_document_type.

Upload limits

• The single-file limit defaults to 50MB, controlled by the site setting kb_document_max_upload_size_mb, adjustable within 1-1024MB.
• The upload dialog reads that site setting and shows the current value (Maximum file size: 50MB), so refresh the page after an administrator changes it.
• The limit is per file: you can select several files at once, but each counts and is created separately.
• There is no ZIP upload and no per-knowledge-base storage quota; watch storage at the team level.

Status and processing stages

Upload/import → extract text → clean → chunk → embed → build lexical index → completed

There are three ways to process, pick the one you need:

• Quick Process: processes with the knowledge base (or document) chunk settings as-is, no preview.
• Start Processing (preview page): review — and if needed edit — chunks with Preview Chunks first, then submit exactly those chunks for embedding.
• Bulk processing: select several documents in the table and use the selection toolbar to Quick Process the pending ones.

Importing from a URL

1. On the knowledge base detail page select Import from URL.
2. Enter a full http:// or https:// address and a document name (1-255 characters). The UI marks the name optional, but the API requires name and rejects an empty submission with a field error, so fill it in.
3. Click Import — the target is safety-checked first (internal, loopback, and cloud metadata addresses are rejected), then a url document is created and the preview page opens.
4. Generate a chunk preview on that page and submit processing: URL content is fetched server-side at that point, so importing never starts processing automatically.

If the import fails (unreachable address, empty content, parsing error) the document keeps an error message; you can open the source URL or delete and retry.

Failures and retries

Retry Failed Chunks is only available for an error document that has failed chunks; when the source file is fine (for example the model failed transiently) it is cheaper than reprocessing because successfully embedded chunks are kept.

Importing through the API

Knowledge base endpoints accept a JWT user session (Authorization: Bearer <ACCESS_TOKEN>), never an API key:

# Upload a file (multipart, the field name is always "file")
curl -X POST "https://your-domain.com/api/v1/knowledge-bases/$KB_ID/documents/upload" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "file=@./handbook.pdf"

# Import a URL (optional "name")
curl -X POST "https://your-domain.com/api/v1/knowledge-bases/$KB_ID/documents/url" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Release Notes", "source_url": "https://example.com/releases"}'

# Process the document (optionally overriding chunk settings)
curl -X POST "https://your-domain.com/api/v1/knowledge-bases/$KB_ID/documents/$DOC_ID/process" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chunk_size": 1000, "chunk_overlap": 100, "clean_text": true}'

Related pages

• Chunking and Document Processing — preview, process, and edit chunks
• Browsing Documents & Metadata — status, fields, and metadata
• Knowledge Base settings reference — upload limit and chunking fields