Skip to main content

Overview

The API gives you the highest degree of flexibility when deploying your Kapa instances or performing analytics. You can leverage the API in various ways:

  • Integrate your Kapa instances into systems for which no off-the-shelf integrations exist.
  • Get aggregate and time series usage statistics
  • Pull full conversation data into third party analytics systems instead of using the Kapa platform.
  • Build your own analytics tools.
  • Use Kapa for purposes outside of question answering like creating content recommendations.

For detailed information check out the API Reference.

Capabilities​

Chat​

The Kapa API offers multiple Chat endpoints for asking questions to your Kapa instances. These endpoints power the Website Widget, Slack and Discord integrations so using these endpoints will let you replicate their behavior exactly.

When submitting a question to the Chat endpoints, Kapa first performs retrieval over the data sources connected to your Kapa instance and uses the search results to answer the question with an LLM.

There are seperate endpoints for starting a conversation (Chat) and continuing a conversation Chat in thread in a thread. After starting a conversation Kapa will remember what you have asked before so you can simply ask follow-up questions without maintaining the conversation history yourself. These endpoints are available as both streamed and not streamed. The streamed endpoints are useful if you want to render their response as it is being generated. The user does not have to wait for the model to finish generating the whole answer but can start reading small chunks of it right away. The Website Widget uses the streamed endpoints.

Retrieval​

The Kapa API offers a Retrieval endpoint that performs semantic search against your knowledge base without LLM generation, optimized for providing context to LLMs and agents. This endpoint provides the same functionality as the Hosted MCP server tool, just via a different transport.

Analytics and data export​

The Kapa API offers two endpoints for exporting your project data programmatically:

  • Activity: Aggregate activity statistics (query counts, feedback, unique users, deflections).
  • List Threads: Paginated conversation threads with question-answer pairs, suitable for syncing into third-party analytics systems.

Custom Chat (deprecated)​

warning

The custom chat endpoints have been deprecated and will be removed in the future. Do not use these endpoints; use the regular Chat endpoints instead.

In addition to the regular Chat endpoints, Kapa offers a lower-level Custom Chat endpoint. In contrast to the regular Chat endpoints it gives you full control over the prompting.

note

The Custom Chat endpoint does not let you alter the behaviour and prompt of your regular Kapa instances that are deployed via the Website Widget, Slack and Discord integrations. It is not compatible with any of the prebuilt integrations.

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 Kapa instance.

Limits​

By default, every team has the following rate limits:

  • Chat endpoints: 20 requests per minute
  • Retrieval endpoint: 60 requests per minute

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

These limits can be customized per team. Reach out to support@kapa.ai if you need to increase them.

User tracking​

You can associate requests with specific users by passing a user object in your Chat and Retrieval endpoint requests. This object supports two types of 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.

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.