Guides
Knowledge base
Upload documents in the dashboard and let retrieval happen at request time, on the keys you choose.
A stack can answer from your own documents without you building a retrieval pipeline yourself. Upload files from the dashboard; retrieval then happens at chat request time, with no extra parameters on your side. Which keys search the knowledge base is a per-key setting, chosen when you create the key and changeable later.
Uploading is a dashboard action, not an API call — there's no public endpoint for adding or removing knowledge-base documents. Retrieval, once documents are indexed, works through the normal chat endpoints.
Uploading
Open the stack's Knowledge page
From the dashboard, open your stack and go to its knowledge base section.
Upload your files
.txt,.md, or.pdf(PDFs must have embedded text — scanned, image-only PDFs aren't supported yet). Indexing runs in the background after upload. Files are limited to 10MB each, and the number of files depends on your plan — see Pricing.Test with a real question
Ask something only the document answers, through chat completions with no
systemmessage — asystemmessage you send bypasses both your configured prompt and the knowledge base for that request.
How retrieval works
At request time, Stac embeds the last user message and searches the stack's indexed documents for the closest matching chunks, then injects them into the prompt, ahead of the conversation.
Whether that happens is decided by the API key used in the request, under API keys → Settings:
| Setting | When the knowledge base is searched |
|---|---|
| Enabled | On every question, even if you send your own system message |
| Disabled | Never |
| Automatic | Only when the request carries no system message — the state of keys created before this setting existed |
With the knowledge base enabled and your own system message in the request,
both coexist: your instruction still stands, and the retrieved excerpt is
appended after it. The knowledge base answers what about, not how to
answer.
Enable it for automations and support — n8n, for instance, always sends its
own system message, so a key left on "automatic" would never search the
knowledge base. For coding tools (Claude Code, Cursor), prefer disabling it:
the retrieved excerpt changes on every turn and defeats the session's context
cache.
A bare greeting ("hi", "hello") never triggers a search, even with the
knowledge base enabled — anything longer does, so "certifications?" is treated
as a real question. See Core concepts and
Chat completions for the
system rule.
Retrieval is best-effort: if the similarity search fails for any reason, the chat request still goes through normally, just without the extra context. A knowledge-base outage never turns into a failed chat request.
What it's for
The knowledge base is meant for grounding chat answers in your own reference material — policies, product docs, FAQs. It's not used by the structured extraction endpoints: those work from the single file you send in that request, on purpose, so a field is never filled from an unrelated document.
Next steps
- Core concepts — how the system prompt and knowledge base are scoped to a stack.
- Chat completions — the
systemmessage rule that governs when retrieval runs.