Skip to main content

HTTP API

The HTTP API is one of the ways to consume Kapa's agentic retrieval: plain HTTP endpoints that return the most relevant chunks, or whole documents, from your knowledge base. If your stack speaks MCP instead, the MCP server exposes the same search as tools. For request-level detail, see the API Reference.

To let agents call retrieval without credentials, for example from a URL in your llms.txt, see Let agents discover and query your docs.

Retrieval​

The Retrieval endpoint is Kapa's retrieval: it searches your knowledge base and returns the most relevant chunks, with no LLM generation, for use as context by LLMs and agents. It is the same retrieval the MCP server exposes as its search tool, over a different transport.

Retrieval modes​

The endpoint runs in one of two retrieval modes, chosen per request with the mode parameter:

  • default is the faster mode: the same tools minus reading on and pruning, limited planning and reasoning, and a tight budget. It returns a fixed number of chunks ranked by relevance.
  • deep runs Kapa's retrieval agent, which searches, reads on, and prunes, and returns a variable number of chunks at a higher latency.

top_k and max_chars cap the result in both modes. The mode also decides the latency; Choose a retrieval mode compares the two modes' latency and results and helps you pick.

note

use_pruning is deprecated. It still prunes low relevance chunks in the default mode, and requests that combine it with the deep mode are rejected. If you use pruning today, or are considering it, switch to the deep mode instead.

If you are integrating the Retrieval endpoint into an agent, see Prompt your agent for grounded answers for uncertainty and citations.

Documents​

The Documents endpoint fetches full documents from your knowledge sources by their source URL or by document ID. While Retrieval returns the most relevant chunks for a query, the Documents endpoint returns whole documents, for when an agent needs the complete page rather than the retrieved chunks.

Requests accept a list of URLs and/or document IDs. URLs can be passed as search results return them, and requested URLs or IDs that match no document are omitted from the results. Each document appears once per page. The results are paginated over the requested URLs and IDs, so a page can hold fewer documents than requests, and each document's content is truncated to max_chars_per_document characters, so that fetching many or large documents does not flood an agent's context window. You can restrict the lookup to specific source groups with source_group_ids_include.

The MCP server exposes this endpoint as its optional documents tool.

Search (deprecated)​

warning

The search endpoint has been deprecated and will be removed in the future. Use the Retrieval endpoint instead.

The Kapa API offers a Search endpoint which powers the search interface of the Website Widget. This endpoint performs keyword search over the data sources connected to your project.

Limits​

By default, every team has the following rate limits:

  • Retrieval endpoint: 60 requests per minute
  • Documents endpoint: 100 requests per minute

These limits apply across all projects and integrations within the team. When exceeded, the API returns HTTP 429 Too Many Requests errors.

The Retrieval limit can be customized per team. Reach out to Kapa support if you need to increase it.

User tracking​

You can associate requests with specific users by passing a user object in your Retrieval endpoint requests; the Chat API accepts the same object, while the Documents endpoint does not accept one. The object supports two identifiers:

  • email: A human-readable identifier. When set, the user's email is visible directly in the Kapa platform, making it easy to see who is asking what.
  • unique_client_id: Any identifier that is meaningful to your system, such as an internal user ID or account number.

Additional descriptive fields can be sent nested under user.metadata: company_name, first_name, and last_name.

Tracked users are visible in the Kapa platform dashboard, and their information is included when exporting conversations via the List Threads endpoint or the List End Users endpoint. This makes it possible to tie Kapa conversations back to specific users in your own systems.