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.

Retrieval​

The Retrieval endpoint performs agentic retrieval against your knowledge base and returns the most relevant chunks, ranked, with no LLM generation, optimized for providing context to LLMs and agents. It provides the same functionality as the MCP server's search tool, just via a different transport, running the same multi-step retrieval pipeline tuned for high recall.

The endpoint can optionally also prune the results. With use_pruning enabled, a small LLM filters the retrieved chunks for relevance to the query. On average, this returns significantly fewer chunks at nearly the same recall, meaning almost no relevant chunks are lost. Read more in the Pruning section of the Tune retrieval size guide.

Typical latency:

  • p50: ~3 seconds
  • p95: ~4.5 seconds

The pipeline is multi-step by design, which costs latency compared to a simple embedding or keyword search; enabling use_pruning adds one more model call, roughly another 0.7 seconds per query. The MCP server wraps this endpoint and has the same latency characteristics.

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

Documents​

The Documents endpoint fetches full documents from your knowledge sources by their exact 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 are matched exactly against the URLs of your ingested sources, and requested URLs or IDs that do not exist are omitted from the results. The results are paginated, 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 support@kapa.ai 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.