Upload knowledge files
Upload Markdown and text files into an Uploaded files collection to turn a folder of reference material into searchable knowledge documents.
Choose files and a destination
Open Organization > Knowledge, click Add knowledge, and choose an existing Uploaded files collection or enter a new collection name. Choose files, choose a folder, or drop a ZIP archive into the upload area. A ZIP is one upload; upload it separately from loose files. Manual, Web pages and Zendesk collections are not upload destinations.
Only UTF-8 .md and .txt files become documents. Hidden files and folders, including .git and __MACOSX, are ignored. Other file types are skipped, not converted. Convert PDF, Word or HTML documents to Markdown or text before uploading them. Nested ZIP files are not unpacked.
Each document keeps its relative upload path. Folder names become labels unless Markdown front matter supplies a label list. For example, this layout inside a ZIP preserves the support directory:
support/
returns/
refund-timing.md
return-label.txt
The first file has path support/returns/refund-timing.md and labels support and returns. When you choose or drop a single folder instead, Studio removes the selected folder's own name: selecting support gives returns/refund-timing.md with the label returns. Keep the relative paths stable when uploading later versions: paths identify existing documents within the destination collection.
Markdown front matter
An optional YAML block at the very start of a Markdown file supports two keys. Put --- on its own line before and after the block.
| Key | Value | Effect |
|---|---|---|
title | A nonempty string, at most 500 characters | Overrides the title derived from the document. |
labels | A list of label names | Replaces the labels derived from folders. Use [] for no folder-derived labels. |
For example, save this as support/returns/refund-timing.md:
---
title: Refund timing for online returns
labels:
- Returns
- Payments
---
# When a refund arrives
We issue a refund within five working days after receiving the return.
The bank may take another three working days to show it in your account.
This creates a document titled Refund timing for online returns with labels Returns and Payments. The front matter is removed from the saved body. The heading remains in the body.
If title is absent, the first Markdown level-one heading supplies the title; if none is usable, the filename without its extension supplies it. Plain text files use the filename and treat any apparent front matter as literal content.
If labels is absent, each parent folder name becomes a label. Names are trimmed and duplicates removed; capitalization matters, so Returns and returns are different labels. Labels can contain at most 255 characters each. Existing labels with matching names are reused.
Other front matter keys, including summary, do not set document fields. The review reports ignored keys. Invalid titles or labels make that file invalid. YAML anchors, aliases, custom tags and duplicate keys are not accepted.
Review before applying
The review lists new, changed, unchanged, conflicting, invalid and deselected files. Inspect the title and labels, edit them where needed, and deselect files you do not want. You can add labels to the whole upload before confirming it.
For an existing collection, Overwrite changed files permits updates to documents at matching paths. Without it, changed documents at those paths remain conflicts and are not overwritten. Updates keep the document ID; a different path creates a different document. Regenerate summaries for changed documents replaces summaries when the title or body changes. Leave it off to preserve existing summaries. New documents receive a first summary automatically.
Only ZIP uploads offer Delete missing files. It deletes previously uploaded documents whose paths are absent from the ZIP. Folder and loose-file uploads never delete documents missing from their selection. Deletion is unavailable if files are invalid or deselected, including skipped unsupported files, or if no valid files remain. At most 500 documents can be deleted in one upload.
If adding or removing a common root folder changes the paths, the review asks you to confirm Delete and recreate them anyway before deleting missing files. Those recreated documents have new IDs, so individual agent selections can stop matching. Keeping the same relative paths avoids this.
If the collection changes while you review, refresh the preview and check it again before applying. After the import, review successes and failures. Manage access on each agent's Knowledge tab, then publish the agent to make draft changes live. A collection already assigned with All documents makes new documents available to those agents immediately. Use Test a question to check retrieval after reviewing access.
Upload limits
The same server limits apply to ZIP uploads and the file batches Studio prepares from loose files or folders. MiB and KiB below use 1,024-byte units.
| Limit | Maximum |
|---|---|
| Archive or prepared batch | 20 MiB |
| Uncompressed supported file content in total | 20 MiB |
| Visible Markdown and text files, including invalid ones | 500 |
| Archive entries, including directories and ignored files | 2,000 |
| One file before parsing | 1 MiB |
| Body after front matter removal | 350,000 characters |
| Relative path | 1,024 UTF-8 bytes |
| Parent folder segments | 20 |
| Front matter | 16 KiB, 64 lines and 256 YAML tokens |
| Labels per file | 32 |
| New label names in one upload | 1,000 |
Encrypted archives, symbolic links, unsafe paths, duplicate paths and corrupt archives are rejected. A rejected archive creates no documents. A file-level error appears in the review so you can fix the file or proceed with eligible files when the review allows it.
Next steps
- Manage imported content in the knowledge library.
- Assign collections and test retrieval with Knowledge management strategies.