Knowledge bases
Left alone, a model answers from what it was trained on. A knowledge base changes that: it is a named set of documents you upload, index, and attach to an Assistant. During a conversation the assistant searches that content and answers from it — so replies reflect your product manual, policy, or catalog, not the model’s best guess.
Create a knowledge base and add files
Section titled “Create a knowledge base and add files”Create the knowledge base in the admin portal (or over the admin API at POST /admin/knowledge) with a
name and a short description. Then upload documents to it — POST /admin/knowledge/:id/files/upload, one
file per request.
Each uploaded file is classified by its content and name, the same way chat uploads are. Documents (PDF,
Word, PowerPoint .pptx, OpenDocument, EPUB, RTF, mail), tables (Excel .xlsx, OpenDocument spreadsheets, CSV,
TSV) and text, code and markup files are read; images, media, archives and unknown types are stored but
not read; executables are refused with 415. The full list, and how to add your own types, is in File
types, kinds & parser limits. Each file that is read is indexed in the
background, the same way as a chat file: its text is
extracted and stored in the file store, split into overlapping chunks, embedded, and stored for search. A
file becomes searchable only once indexing finishes and marks it ready.

The Files tab. Each row carries a Status and an Indexed column. A file is searched only when Indexed shows Yes.
File status
Section titled “File status”Knowledge-base files use the same file status as chat files. The Files tab shows it like this; hover over the status to read the reason:
| Files tab | status | Searched? |
|---|---|---|
| Processing | processing | Not yet |
| Ready | ready | Yes |
| Ready (not searchable) | ready, an image | No. Images are stored, not searched. |
| Not searchable | search_unavailable | No. The text was read but the search index wasn’t built, for example because the embedding provider failed. |
| No text | no_text | No. The file holds no text, for example a scanned PDF. |
| Stored only | stored_only | No. DioscHub doesn’t read this kind of file. |
| Indexing failed | failed | No. The reason says why: damaged, password-protected, too large to read, and so on. |
The Indexed column is canSearch. Over the admin API (GET /admin/knowledge/:id/files, and the
upload and sync responses), each file carries status, reason, warnings, progress, canRead and
canSearch. isIndexed is still returned but deprecated: it equals status === 'ready', which is true for
an image too.
A PDF with a few unreadable pages, or a workbook with one unreadable sheet, is still Ready: the rest is
indexed, and the file lists what it skipped in warnings.
There is no Re-index button on the Files tab. To retry knowledge-base files, run a bulk Re-index with the knowledge-base scope, or replace the file through sync (below).
Replace a file without a gap
Section titled “Replace a file without a gap”A sync replace (POST /admin/knowledge/:id/sync, see the server API)
doesn’t delete the old version first. The new version is indexed while the old one keeps answering
searches, and the file switches over when the new version’s indexing ends. The old version’s bytes, text
and index are deleted then.
- The switch happens whatever the outcome. If the new version can’t be read (damaged, say), the file becomes Indexing failed and the old version is gone, so it is no longer searched. Check the status after a replace.
- Two replaces of the same file at once are taken in turn. A replace that can’t take its turn within a few
seconds, or that finds the file changed under it, is refused with
409and stores nothing. Retry it.
Storage used and the storage limit
Section titled “Storage used and the storage limit”The knowledge-base list shows how much storage knowledge bases use, in total and per knowledge base:
the files themselves, their extracted text and their search index, and the file count (GET /admin/knowledge/storage-usage). Knowledge-base files never count against any user’s storage quota.
You can cap the total with the optional Knowledge-base storage limit on System → Rate Limits → File
uploads (see System settings). It is off by default and is one
limit over all knowledge bases together. When it is set, an upload, a sync add, or a sync replace that
grows a file is refused when it would take storage used past the limit. A replace counts only its growth,
and a remove is never refused. Nothing is deleted when you lower the limit; it only refuses new bytes.
The refusal is HTTP 413:
{ "statusCode": 413, "code": "KB_STORAGE_LIMIT_EXCEEDED", "message": "Knowledge-base storage limit exceeded", "usedBytes": 1073741824, "limitBytes": 1073741824, "requiredBytes": 2097152}The check counts a file’s whole size up front, before its text and index exist. Extracted text and index
bytes are added when indexing finishes, so the figure can end a little above the limit; the next upload is
then refused. Uploads under a limit are checked one at a time; one that can’t get its turn within a few
seconds is refused with 409 and can be retried.
Link the knowledge base to an Assistant or a Role
Section titled “Link the knowledge base to an Assistant or a Role”Uploading files does not, on its own, let any assistant read them. A knowledge base is a shared, organization-wide resource; you decide who sees it by linking it:
- Link it to an Assistant, and every conversation with that Assistant can search it.
- Link it to a Role, and only users resolved to that Role can search it — useful when one document set should reach some users but not others.
Link and unlink from the knowledge base’s admin page (or POST / DELETE /admin/knowledge/:id/links). A single knowledge base can be linked to many Assistants and Roles at once.
How the assistant answers from it
Section titled “How the assistant answers from it”Retrieval is a tool the model calls, not a silent paste of documents into the prompt. When a linked knowledge base is present, the assistant is told it has one and instructed to search before it answers. It issues a query, DioscHub returns the most relevant chunks from the linked, indexed files, and the model composes its reply from those passages. Only files whose status is ready (and that aren’t images) are searched, and the search is scoped to exactly the knowledge bases linked to that Assistant and Role — nothing else.
Each hit names its file and where the passage sits, so the assistant can read around it with
read_kb_file, which pages through a knowledge-base file’s full text. It reads only files the search could
reach, by the same links and the same check on every call. Both tools are withheld when the licence allows
no knowledge bases, and both hand the model file text framed as data; see How the assistant reads
files.
A spreadsheet or CSV in a knowledge base is indexed the same way as a chat file: each kb_search hit
names its sheet and A1 range, and starts with a Columns: line when the header row is known. It gets no workbook outline and no
extracted pictures, though, and the table tools (describe_workbook,
load_table, query_table) don’t work on it. They work only on the user’s own files, and a
knowledge-base file id gets the same “No file with this id is in your files.” as any id outside the
user’s library. For a knowledge-base spreadsheet, the assistant answers from kb_search and
read_kb_file.
Because retrieval draws only on the linked knowledge bases, the way to change what the assistant can cite is to change what you upload and link — not to re-prompt it.
Activate, deactivate, and delete
Section titled “Activate, deactivate, and delete”A knowledge base is either active or inactive. Only active knowledge bases are searched and attachable; deactivating one preserves its files but takes it out of retrieval — the assistant stops drawing on it from the next turn. Reactivate it to bring it back. Use this to retire a document set temporarily without deleting anything.
To delete a knowledge base, first remove its links — DioscHub refuses to delete one that is still linked to an Assistant or Role, so an assistant never loses knowledge out from under it by surprise. Unlink everywhere, then delete.