Skip to main content

Chat API

The Chat endpoints give you API access to Kapa's managed agent, the same one you can deploy through the Website Widget, Slack, and Discord integrations, to use any way you like. Answers behave exactly as they do in those integrations; the difference is that the surface is yours, for example a CLI, a help panel you render yourself, or an internal tool.

When a question is submitted, Kapa first performs retrieval over the knowledge sources connected to your project and uses the results to answer with an LLM, grounded in your knowledge sources.

Looking to give context from your knowledge to another agent?

That is agentic retrieval's job, via the Retrieval endpoint or the MCP server, not the Chat endpoints'. Chat already includes an LLM generation step, so wrapping it as a tool inside another agent stacks two model calls on top of each other, which adds too much latency for a good user experience.

History and streaming​

There are separate endpoints for starting a conversation (Chat) and continuing it in a thread (Chat in thread). After starting a conversation, Kapa remembers what was asked before, so you can send follow-up questions without maintaining the conversation history yourself.

Both are available streamed and not streamed. The streamed endpoints are useful if you want to render the response as it is being generated: the user does not have to wait for the model to finish the whole answer but can start reading right away. The Website Widget uses the streamed endpoints.

Create an integration​

Create a Custom (API) integration in the platform and pass its integration ID on requests. This associates the conversations with that integration, so they show up attributed in the dashboard and Analytics, and lets you separate traffic by deployment or use case:

curl --location 'https://api.kapa.ai/query/v1/projects/{project_id}/chat/' \
--header 'X-API-KEY: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "integration_id": "<YOUR_API_INTEGRATION_ID>",
    "query": "How do I get started?"
}'

Behavior and tone follow the same customizations as every other Prebuilt Agent: associate one with the integration, or pass customization_id per request.

Keeping your API key safe​

Never expose your API key in client-side code (e.g., JavaScript running in the browser) because it is impossible to keep it hidden. Attackers can easily extract it and misuse your Kapa project.

If your integration requires user authentication, the best solution is to store the API key securely on your backend and create authenticated proxy routes that forward requests to the Kapa API. This ensures:

  • The API key remains hidden from the client.
  • Requests can be authenticated and rate-limited before reaching your backend.
  • You maintain control over how the API is accessed.

If your integration does not require authentication, securing your API key is more challenging. Simply proxying requests through your backend is not enough, as anyone could call your backend directly.

A common solution is to use a challenge-response mechanism like CAPTCHA to distinguish between human users and automated bots:

  1. Use a CAPTCHA provider (e.g., Google reCAPTCHA, hCaptcha) and integrate their frontend SDK.
  2. When a user interacts with your integration, the CAPTCHA validates they are human and returns a token.
  3. Send this token along with requests to your backend.
  4. On your backend, verify the CAPTCHA token before forwarding the request to Kapa.

While this approach helps prevent automated abuse, it does not provide full security. Attackers can still call your backend directly if they bypass CAPTCHA. Consider combining this with rate limiting, usage quotas, and domain/referrer validation to ensure that requests originate from an expected client.

Rate limits​

Chat endpoints are limited to 20 requests per minute per team by default. The limit is shared across all of the team's projects and integrations, whether traffic comes through the API, the Website Widget, or the bots. When exceeded, the API returns HTTP 429 Too Many Requests. These limits are surge protection rather than usage quotas, and can be raised per team: reach out to support@kapa.ai.

User tracking​

Associate requests with your users by passing a user object. The fields are documented under user tracking on the HTTP API page, in the Agentic retrieval section.

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.