Adding a Knowledge Base API to Your App: A Developer's Guide

A knowledge base API is a REST (or MCP) interface that lets your app send a question or a search query to an indexed set of documents and get back either raw passages or a generated answer with citations. Most teams need two endpoints: one for search, one for grounded answers, plus an API key per environment. The hard parts are latency budgets, cost control and rendering sources in your UI without lying to the user about where an answer came from.

What you are actually integrating

Before writing any code, it helps to separate three things that often get bundled under the same label. First, indexing: documents are uploaded, split into chunks, and turned into a searchable index (full-text plus semantic). Second, retrieval: given a query, the system finds the most relevant chunks. Third, generation: an optional step where a language model composes an answer from those chunks, with citations back to the source passages. A knowledge base API, done well, exposes all three as separate concerns so you can choose exactly how much automation you want in your app.

If you have never built the indexing side yourself, you don't have to. Services like Kopik let you upload PDFs, Word documents, Markdown or plain text, handle chunking and hybrid indexing automatically, and expose the result through a REST API and an MCP server. That means your integration work is mostly about calling endpoints correctly, not about building a retrieval pipeline from scratch.

The two endpoints you need

Almost every knowledge base API integration boils down to two calls. A search (or passages) endpoint returns the raw chunks that matched a query, ranked by relevance, with their source document and position. An answers endpoint does the same retrieval step internally, then asks a language model to compose a short answer grounded in those chunks, returning both the answer text and the passages it was built from.

That table row got cut short deliberately in the final cell, so here is the full picture written out: search endpoints suit search-as-you-type boxes, citation-only widgets, or feeding your own downstream model; answers endpoints suit chat interfaces, support deflection and anywhere a user expects a direct reply in plain language. Many apps use both: search for instant suggestions, answers for the final response once the user commits to a query.

A minimal request/response shape

Regardless of provider, the request body for an answers call usually needs three things: the knowledge base identifier, the question text, and an optional mode flag (answer vs passages only). The response typically contains the answer string, a confidence or grounding indicator, and an array of cited passages, each with the source document name, a snippet, and sometimes a page or section reference. If your provider's response does not include enough detail to let you link back to the exact passage, you will struggle later when you try to build a trustworthy citations UI, so check this before you commit to an integration.

API keys and authentication

Treat knowledge base API keys the same way you treat payment provider keys: scoped, rotatable, never shipped in client-side JavaScript. A sensible setup looks like this:

1. Create one API key per environment (development, staging, production) so a leaked key from a test environment cannot touch production data.
2. If the platform supports it, create separate keys for separate knowledge bases, especially if you serve multiple customers from the same app.
3. Proxy all knowledge base API calls through your own backend. Never call the knowledge base directly from a browser or mobile client with an embedded key.
4. Log which key made which call, including timestamps and the question asked, so you can audit usage and spot anomalies.
5. Set a monthly budget or usage gauge alert so a bug in a retry loop cannot silently burn through your prepaid credits.

On Kopik, keys are generated per private or public base from the dashboard, and the same credential system backs both the REST API and the MCP server, so you can reuse one key across a web app and an internal tool like Cursor or Claude without managing two separate auth schemes. Full details, including request examples, are in the developer documentation.

Latency: setting a realistic budget

Search-only calls over a well-indexed hybrid store (combining keyword matching like BM25 with vector similarity) typically return in a few hundred milliseconds, which is fast enough for live search boxes. Answer generation adds a language model call on top, and that is where most of your latency budget goes. A rough mental model for a chat-style feature: 100-400ms for retrieval, 1-3 seconds for generation depending on answer length and model size, plus your own network round trip. If you are building a chat UI, stream the answer token by token rather than waiting for the full response; it changes the perceived latency dramatically even though the total time is the same.

If retrieval quality is poor, you will often see this disguised as a latency or cost problem rather than a relevance problem, because a weak retriever returns more irrelevant chunks, the model has to work harder to compose a sensible answer, and users ask follow-up questions that re-trigger the whole pipeline. It is worth reading up on hybrid search and on chunking strategy before assuming your problem is infrastructure rather than indexing.

Cost: credits, subscriptions and who pays

Most knowledge base APIs price per question rather than per token, which is easier to forecast but means you need to think about who is actually asking questions. If your app has end users triggering unlimited free-text queries, costs scale with your user base, not with your engineering effort, so budget for that explicitly rather than discovering it in a monthly invoice.

• Prepaid credits per question suit apps with predictable, metered usage, like a support widget that answers a bounded number of tickets per day.
• A flat monthly subscription with a usage gauge (Kopik's chat plan is €12/month) suits internal tools used by a small, steady team where usage is roughly constant.
• Caching recent answers for identical or near-identical questions can cut real cost significantly in support and documentation use cases, where the same question is asked repeatedly.
• Passages-only mode is cheaper than full answer generation if your app already has its own model or just needs to show relevant snippets.

If you are deciding whether to build retrieval infrastructure yourself or buy it as a service, it is worth comparing the total cost of self-hosting a vector database against a managed knowledge base API; the maths rarely favours self-hosting for small and mid-sized teams once you include the engineering time to keep an index fresh.

Citing sources properly in your UI

This is the part developers most often get wrong, and it is also the part that determines whether users trust the feature at all. A citation is only useful if a user can click through to the exact passage, not just the document title. Three rules worth following:

1. Always render citations as clickable references next to the specific sentence or claim they support, not as a generic list of sources at the bottom of the answer.
2. Show the exact snippet the model used, not just the filename, so users can verify the claim in seconds without opening the full document.
3. If the knowledge base API returns a confidence or grounding score, surface it visibly when it is low, rather than presenting every answer with the same confident tone.

If you want a deeper checklist for verifying answers before you ship them to users, see Document Q&A With Citations: How to Check an AI Answer and, for the broader problem of unsupported claims, Reducing AI Hallucinations: A Practical Guide to Grounded Answers. The short version: never let a language model answer from its own training data when the whole point of the feature is that answers come from your documents. A well-built knowledge base API should refuse, or clearly flag, questions it cannot answer from the indexed content rather than guessing.

A basic integration checklist

Once you have chosen a provider and created a base (public or private), the integration steps are broadly the same regardless of stack:

1. Upload your source documents and let the platform chunk and index them; check a sample of answers manually before going live.
2. Generate a scoped API key for the environment you are building against.
3. Build a thin server-side wrapper around the search and answers endpoints, including retries with backoff and a timeout matched to your UI's latency budget.
4. Render citations inline, with snippets, and handle the 'no answer found' case explicitly rather than letting the UI show an empty or generic response.
5. Add usage logging and a cost alert before opening the feature to real users.
6. Revisit chunking and source documents periodically as your underlying content changes; a knowledge base is only as good as its last update.

If your product sits in a regulated or support-heavy space, it is worth reading the sector-specific guides on how teams actually use grounded search in practice, such as RAG for Customer Support Teams or RAG for Law Firms and Legal Teams, both of which cover citation and trust issues that apply well beyond their named sectors.

When to build your own retrieval stack instead

A knowledge base API is not always the right call. If you need extremely tight control over the embedding model, custom re-ranking logic, or you are processing data that cannot leave your own infrastructure under contractual terms, self-hosting may be unavoidable. For most product teams adding search or Q&A over a documentation set, support knowledge base, or policy library, though, the engineering cost of building and maintaining chunking, indexing, hybrid retrieval and citation plumbing from scratch rarely pays off compared with calling a managed REST API and focusing your own engineering time on the product experience around it.

Browse the public catalogue of knowledge bases to see what a finished integration looks like from the querying side, with cited answers rendered against real document sets, before you decide how much of this to build yourself.