Collections and documents

Set up a collection, give people access, and add files, web pages and interviews.

Set up a collection#

Knowledge > Collections > New collection (admins create; they may name the first manager).

• Usage tag: Public (may be shared with customers) or Internal (for the agent's own understanding: do not quote it or refer to it with customers). The tag is guidance, returned with every result, in each document tool's description and in the MCP instructions, so no agent depends on its prompt author remembering it. It is not an access rule.
• Grants: a user or an API token gets read, write or manage on the collection. Read searches and reads; write ingests, edits and approves; manage grants and revokes, changes settings, exports and deletes. Write and manage for users also need the editor role; tokens only ever read. A collection keeps at least one manager.
• Switches (collection settings): Documents may be sent to the AI model and Agents may read this collection. See Feature switches.
• Hidden by default: a collection you hold nothing on does not exist for you (the API answers 404). Admins see that collections exist so they can fix access, but not what is in them: an admin reads content only after granting themselves access, and that grant is logged.
• Customer-facing agents should get a token with grants on public collections only.

Add documents#

Knowledge > Sources, in a collection you can write to (write access and the editor role).

• Files: drop or browse. PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx), CSV/TSV, HTML, Markdown, text, JSON, XML and images, up to the upload limit. Legacy formats (.doc, .ppt, .xls, .rtf) are not accepted: save them in the new format. The same bytes cannot be added twice to a collection. A failed source can be retried.
• Web pages: Add a web page captures an address (kept as the page that was fetched, so the original can be downloaded). An address that is a file (PDF, Word...) is downloaded as that file. Refresh captures it again: unchanged means nothing is redone, changed means the new content is read again. The same content under two addresses is stored once. See Fetching safely.
• Interviews: capture what a person knows by conversation. See Interviews.

Places are kept so passages can be cited: Page 3, Slide 2, Sheet: Costs. Headings become Markdown headings; web pages lose menus, footers and cookie banners; spreadsheets are read row by row with their column names. Scanned PDF pages and images are read by an OCR model: any vision-capable model on your AI endpoint (Settings > AI > Model that reads images, falling back to the assistant model; up to Most scanned pages read per document). Without one, such pages are skipped with a note, and a file with no readable text fails with the reason. Office files are checked for zip bombs before opening.