Documents

Objective

Build and manage your AI knowledge base. Upload documents so your agents answer questions from your own content using RAG (Retrieval Augmented Generation). Helios keeps each original file and indexes it in your workspace's own knowledge index: it reads the text, detects the document's structure (titles, chapters, articles), and makes it searchable both by meaning and by exact words. Each document can be assigned to one or more agents.

Access

Sidebar -> Documents Route: /app/{tenant}/documents

Roles

• owner, admin, agent — open the module, upload documents, retry failed documents, and refresh a document's structure.
• owner, admin — delete documents and assign or unassign documents to agents. Agents see assignments read-only and do not get the delete action.
• viewer — no access to this module.

Prerequisites

• No API key on managed AI credits. A workspace that runs on its own key indexes with its OpenAI API key (connected in Integrations or under API keys); a Google AI key is not used for documents. On Free without a key of its own, Helios covers indexing up to a monthly indexing allowance.
• A verified email address. Upload is blocked until your email is verified on plans that require it.
• An active subscription. Upload is blocked while the subscription is restricted or suspended.
• Room in your plan's knowledge base, which is measured in knowledge pages (see Plans and limits).

Plans and limits

Your plan sells the knowledge base in knowledge pages: 1 knowledge page = 2,500 characters of text read from your documents, about one printed page. The limit counts the text, not the number of files or megabytes.

Knowledge base usage

The Documents page shows a knowledge base meter with your usage, for example "120 of 200 knowledge pages used", with the reminder "1 knowledge page = 2,500 characters of text read from your documents". On Enterprise it shows the pages in use with no limit.

• When less than one page is left, the meter warns that only a very short document can still be indexed.
• When the knowledge base is full, the meter says so and Upload Document opens a Knowledge base full dialog instead of the upload form. The meter's notice gives owners and admins an Upgrade plan action; other roles are asked to contact a workspace admin.
• If your workspace uses more pages than its plan includes (for example after moving to a smaller plan), your documents keep working, but new ones are not indexed until you delete documents or upgrade.
• When a single document does not fit in the pages left, it is not indexed: its row shows Failed with a message stating how many knowledge pages it needs and how many of your plan's pages are already in use. Delete documents you no longer need, or choose Upgrade plan, then choose Retry indexing on that document.

Upload a document

Steps:

1. Press Upload Document.
2. Drag a file onto the drop area, or click to browse.
3. Complete the fields.
4. (Optional) Open Advanced settings to override chunking.
5. Press Upload Document.

Fields:

Supported file types:

• PDF, DOCX, XLSX, PPTX, TXT, MD, CSV, JSON, HTML, PNG, JPEG, DOC, XLS, RTF, ODT

Some recognizable formats are not supported and are rejected with a specific message that names the format and suggests what to convert it to: HEIC/HEIF, WEBP, and TIFF images (convert to JPEG or PNG), legacy PowerPoint PPT (convert to PPTX), OpenDocument Spreadsheet ODS (convert to XLSX or CSV), and EML email exports (convert to PDF or plain text).

The file content is validated against its real type on upload, not just the file extension. A renamed or corrupted file is rejected even if it claims a supported type.

After upload the document appears as Processing and indexing starts in the background within seconds; you can close the dialog while it runs. Helios reads the text, detects the structure and splits the document so that no article is ever cut in half. Legal documents keep their structure (titles, chapters, articles), so an agent can quote an article verbatim by its number, and a document left at General is still read as a legal text when its content is one.

Document types (chunking presets)

The Document Type controls how the file is split into chunks for search. Choose the one that best matches the content.

If you leave Document Type at its General default, Helios picks a better preset automatically for some files: spreadsheets, CSV, and JSON are chunked with the Technical preset so a full row or record is never split mid-way. An explicit choice of any type is always respected and never overridden.

Advanced chunking settings

Open Advanced settings in the upload dialog to override the preset for technical use cases. When Advanced is on, its values are used instead of the Document Type preset.

Custom values are clamped to safe limits before processing.

Processing and statuses

Each document shows a status:

Each row also carries a knowledge base badge that says whether agents can find the content: Indexed (searchable), Indexing, Failed, or Not indexed (indexing finished, but no searchable text came out of the file). The detail view shows the same state in its Knowledge base field.

How indexing runs:

• It works in steps (read the text, detect the structure, split, embed, write to the index) and saves its progress after each one. A large document, such as a long scan, can need several background runs of a few minutes each; it stays Processing and continues from where it stopped. A document is never marked Failed just because it takes a long time.
• If a step fails for a reason that can pass (a provider or network hiccup), it is retried automatically a few minutes later. After three failed attempts in a row without progress, the document is marked Failed. Problems that retrying cannot fix, such as a full knowledge base, a file with no readable text, or no key to index with, mark it Failed right away.
• The models used for indexing and search are OpenAI's. On managed AI credits, indexing and searching your documents adds no credits, only scanned pages do (see below), but a workspace with no credits left cannot index. When the workspace runs on its own key, indexing and knowledge searches use its OpenAI API key.

For a Failed document, Retry indexing runs indexing again. A document whose original file is kept is retried from that saved file, with nothing to select. An older document, uploaded before original files were kept, asks you to choose the file again; that replacement file is limited to 4 MB, and a larger one is refused with "This replacement file is larger than 4 MB, the most a reprocess can send. Choose a smaller file." Retries count against the same upload rate limit, and a document that is being indexed right now cannot be retried until that run ends.

A page with no text layer, such as a scanned PDF page, is read page by page. On managed AI credits each scanned page uses 1 credit, and scanned pages also count against a monthly scanned-page allowance that depends on your plan; Free does not include one. When the allowance runs out, the document is marked Failed but the pages already read are kept: choose Retry indexing once the allowance renews or after you upgrade, and indexing continues from where it stopped without reading or charging those pages again.

Documents uploaded before the current indexing system that still show Processing can be marked Failed from Helio (Mark stalled documents failed, owner or admin), so you can retry them. It only applies to those older records, unchanged for more than two minutes, and it never touches a document that is being indexed.

Document structure

Once a document is Ready, Refresh structure reads what the knowledge base holds for it and shows it in the Document structure section of the detail view: the document type and how many chapters and articles were indexed. It costs nothing, takes a moment, and you get a notification when it finishes. After the first read the row shows a Structure read badge, with a control to read it again after re-indexing the document.

Document details

Click a document name to open its detail view. It shows:

• File info: size, file type, uploaded date, and the Knowledge base state (Indexed, Indexing, Failed, or Not indexed).
• Document structure: the document type and the number of articles and chapters indexed, plus any title and summary saved for the document earlier.
• Assigned agents.

When the original file is kept, the detail view offers Download original. A document uploaded before original files were kept shows Original file not downloadable; upload it again and the copy will be kept.

Assign documents to agents

Each document row and the detail view include an Assign agents control.

• Toggle an agent to add or remove the document from that agent's knowledge base.
• Assigning the first document to an agent turns its knowledge base (RAG) on; removing the last one turns it off.
• Only owners and admins can change assignments; agents see them read-only.
• You can also manage the same assignments per agent from the Agents editor's knowledge base section.

Search and filters

• Search box: matches file name, display name, description, and document type.
• Status pills: All statuses, Ready, Processing, and Failed, each with a count.
• Type filter: All types, General, Legal / Regulatory, Technical / Code, and FAQ / Q&A.
• Stat chips above the list show Total Documents and Ready, plus Processing and Failed when any exist.

Delete a document

Press the delete icon on a document row and confirm. Only owners and admins see this action. It permanently removes the document from your knowledge base, deletes the stored original file, frees the knowledge pages it used, and removes it from any agents it was assigned to. It cannot be undone. If the document cannot be removed from the knowledge base, nothing is deleted. If its stored file cannot be deleted, the document stays in the list but is already out of the knowledge base. In either case, delete it again.

Good practices

• Give each document a clear Display Name.
• Write a Description so the agent knows when to use the document.
• Pick the right Document Type. Use Legal for laws and contracts to enable verbatim article lookup.
• Split very long documents by topic.
• Refresh a legal document's structure after it is indexed to confirm every article made it in.

Common errors

Screenshot

Related

• AI Agents (RAG)
• Integrations (OpenAI API key, when your workspace runs on its own key)