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

A knowledge base API lets your app send a question or a search query and get back relevant passages or a grounded answer, without you running a vector database, an embedding pipeline, or a reranker. This guide covers the endpoints you'll actually call, how API keys and rate limits work, what latency to budget for, how pricing breaks down per question, and how to render citations in your UI so users trust the answer.

What a knowledge base API actually does

Under the hood, a knowledge base API sits in front of a retrieval pipeline. Your documents (PDFs, Word files, Markdown, plain text) get extracted, split into chunks, and indexed for hybrid search, combining keyword matching with semantic similarity so the system finds relevant passages even when the user's wording differs from the source text. If you want the mechanics, Hybrid Search: Why BM25 + Vectors Beats Either Alone for RAG and How RAG Works, Step by Step cover the pipeline in detail, and What Is RAG (Retrieval-Augmented Generation)? A Practical Guide is a good primer if you're new to the concept.

From an integration standpoint, you generally care about two things: can I get raw matching passages (useful for building your own answer logic or a search widget), and can I get a generated answer with citations back to the source documents (useful for a chat-style assistant). Most APIs, including Kopik's, expose both modes so you pick the one that fits your interface.

The core REST endpoints you'll call

The exact paths differ by provider, but almost every knowledge base API follows the same shape. Here's the pattern you should expect, and what each endpoint is for.

A minimal integration only needs two calls: one to list or confirm the base ID, and one to query it. In practice, your app will call /answer when you want a conversational response (

for example, a support widget that answers in full sentences) and /search when you want to build your own results list, like a document finder or an internal wiki search bar. Kopik's full endpoint reference, request and response schemas, and example payloads live at /developers.

1. Create or choose a knowledge base at /dashboard/bases/new, either by uploading your own documents or subscribing to a public one from /bases
2. Generate an API key scoped to that base from your dashboard
3. Send a POST request to the search or answer endpoint with your query and the key in the Authorization header
4. Parse the response: passages array for /search, or answer text plus a citations array for /answer
5. Render the citations next to the answer so users can verify the source before acting on it

Authenticating with API keys

API keys are the standard authentication mechanism for a knowledge base API, and the rules are the same ones you'd apply to any third-party API key: never embed a production key in client-side JavaScript or a mobile app binary, because anyone can extract it from the network tab or the compiled app. Route calls through your own backend, which holds the key in an environment variable, and have your frontend call your backend instead of the knowledge base API directly.

For a private knowledge base, the key authenticates both who you are and which documents you're allowed to query, since private bases are only reachable by the owner and their keys. For a public base from the catalogue, the key authenticates your account for billing purposes: you're charged per question even though the content is shared across many consumers. If you'd rather expose the base conversationally inside an AI coding tool or chat client instead of writing REST calls, How to Connect Claude, Cursor or ChatGPT to a Knowledge Base walks through the MCP alternative, which uses the same underlying API keys.

Latency: what to budget for

Latency for a knowledge base API has two very different profiles depending on which endpoint you call. A /search call that returns raw passages is typically fast, often in the low hundreds of milliseconds, because it's just retrieval: the system runs the hybrid search, ranks results, and returns them without generating any new text. A /answer call is slower because it does retrieval and then runs a generation step over the retrieved context, which adds the time it takes to stream or wait for a language model's completion. Expect something in the range of one to a few seconds for a typical answer, depending on how much context is retrieved and how long the answer is.

• Use /search when your UI needs to feel instant, such as autocomplete-style search-as-you-type
• Use /answer when the user expects a conversational response and is willing to wait a couple of seconds, like a support chat or a document Q&A panel
• If you stream the /answer response token by token, perceived latency drops even though total completion time is the same
• Cache repeated or near-identical queries on your backend to avoid paying for, and waiting on, the same question twice

What it costs per question

Most knowledge base APIs price per question rather than per API call volume, which matters when you're estimating a budget for a feature that might get hit thousands of times a day. Kopik uses prepaid credits consumed per question, or a flat chat subscription at 12 euros a month with a usage gauge for lighter, steady usage. If you're querying a public base from the catalogue, the creator sets the per-question price and keeps 70% of it, so costs vary by base: a narrow, high-value base (say, a regulatory reference built by a specialist) will cost more per question than a broad general-purpose one.

Before launching a feature at scale, run a rough estimate: expected daily questions multiplied by the per-question cost of your chosen base, then compare that against the subscription tier. For a support widget expecting a few hundred questions a day, a flat subscription with a usage gauge is usually more predictable than metered credits. For a low-traffic internal tool, credits avoid paying for capacity you don't use.

Citing sources in your UI

The whole point of grounding answers in a document set is that users can check the work. An /answer response should come back with a citations array pointing to the specific passages used, typically including the document name, a page or section reference, and the excerpt itself. Your UI job is to surface that without cluttering the main answer.

• Show the answer first, then a collapsible
• Sources
• or
• References
• section listing each cited passage
• Link each citation to the source document if your base storage exposes a URL or lets you open the original file
• Highlight which sentence in the answer corresponds to which source when the API returns span-level mapping
• If the answer has no citations, or confidence is low, say so explicitly rather than presenting it as equally reliable

If you want a deeper look at what makes a citation trustworthy versus decorative, including how to spot a passage that's technically relevant but doesn't actually support the claim, see Document Q&A With Citations: How to Check an AI Answer. This matters more for regulated or high-stakes use cases, like internal compliance assistants or customer support tools answering policy questions, where an unverified answer can cause real problems. RAG for Customer Support: Deflect Tickets and Assist Agents With Cited Answers covers a concrete example of citation UI for a support use case.

Choosing passages-only mode vs generated answers

Not every integration needs a generated answer. If you're building a search feature where users scan a results list and open documents themselves (think an internal wiki or a legal research tool), passages mode is often the better fit: it's cheaper, faster, and avoids any risk of the model paraphrasing something incorrectly. Generated answers make sense when users expect a direct response to a specific question, like

what's our refund policy for international orders, where reading three passages themselves would be friction. A reasonable default is to let the API return both: the answer for immediate display, and the underlying passages available on demand for users who want to verify or dig deeper.

A quick pre-launch checklist

1. API key stored server-side only, scoped per environment
2. Rate limiting or request queuing on your backend to avoid bursting past your plan's limits
3. Fallback behavior defined for when the API times out or returns no relevant passages
4. Citations rendered and linked back to source documents in your UI
5. Cost model estimated against expected daily question volume before go-live
6. Logging of queries and response quality so you can catch drift or bad answers early