Kapa

https://docs.kapa.ai/
Admin
Kapa is an LLM-powered AI assistant that transforms knowledge bases into chatbots to instantly...
Tokens:154,363
Snippets:1,886
Trust Score:8.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies for the example app

Source: https://docs.kapa.ai/examples/embed-an-ai-assistant-in-your-app-that-answers-questions-and-takes-actions

Commands to clone the repository and install necessary packages.

```bash
git clone https://github.com/kapa-ai/kapa-examples.git

cd kapa-examples/in-product-agent

npm install
```

--------------------------------

### Install the SDK

Source: https://docs.kapa.ai/dev/agent/core

Install the core package via npm.

```bash
npm install @kapaai/agent-core
```

--------------------------------

### Install @kapaai/agent-core

Source: https://docs.kapa.ai/dev/agent/quickstart/core

Commands to install the SDK using various package managers.

```bash
npm install @kapaai/agent-core
```

```bash
yarn add @kapaai/agent-core
```

```bash
pnpm add @kapaai/agent-core
```

--------------------------------

### Install and Authenticate mcp-remote

Source: https://docs.kapa.ai/build-with-ai

Install the package globally and run the authentication command.

```bash
npm install -g mcp-remote
```

```bash
npx mcp-remote https://kapa-docs.mcp.kapa.ai
```

--------------------------------

### List Project Integrations cURL Example

Source: https://docs.kapa.ai/api/reference/query-v-1-projects-integrations-list

Example cURL command to list integrations for a project.

```bash
curl -L 'https://api.kapa.ai/query/v1/projects/:project_id/integrations/' \
-H 'Accept: application/json' \
-H 'X-API-KEY: <X-API-KEY>'
```

--------------------------------

### Install Kapa React SDK

Source: https://docs.kapa.ai/dev/sdk/quickstart

Install the required package via npm to begin integration.

```bash
npm install @kapaai/react-sdk
```

--------------------------------

### Improve Webhook Setup Instructions

Source: https://docs.kapa.ai/improving/writing-best-practices

Demonstrates replacing vague setup instructions with explicit prerequisites and clear configuration steps.

```markdown
## Setting up webhooks  

  

Configure your endpoint URL in the Kapa platform and test the connection.  
```

```markdown
## Setting up CloudSync webhooks  

  

Before configuring webhooks, ensure you have:  

  

- A publicly accessible HTTPS endpoint  

- Valid SSL certificate  

- CloudSync API credentials  

  

Configure your endpoint URL in the CloudSync dashboard under Settings >  
Integrations, then use the "Test connection" button to verify setup.  
```

--------------------------------

### Install React SDK

Source: https://docs.kapa.ai/dev/agent/react

Commands to install the @kapaai/agent-react package using various package managers.

```bash
npm install @kapaai/agent-react
```

```bash
yarn add @kapaai/agent-react
```

```bash
pnpm add @kapaai/agent-react
```

--------------------------------

### Install Kapa.ai React SDK dependencies

Source: https://docs.kapa.ai/dev/sdk/tutorials/embedded-chat

Install the core SDK and necessary UI rendering packages.

```bash
npm install @kapaai/react-sdk react-markdown react-icons
```

--------------------------------

### Start the development server

Source: https://docs.kapa.ai/examples/embed-an-ai-assistant-in-your-app-that-answers-questions-and-takes-actions

Command to launch the local development server.

```bash
npm run dev
```

--------------------------------

### Clone and Initialize the Proxy Example

Source: https://docs.kapa.ai/examples/add-documentation-search-to-mcp-server

Commands to clone the repository and prepare the environment configuration file.

```bash
git clone https://github.com/kapa-ai/fastmcp-proxy-example.git

cd fastmcp-proxy-example

cp env.example .env
```

--------------------------------

### Initialize a React project

Source: https://docs.kapa.ai/dev/sdk/tutorials/embedded-chat

Commands to scaffold a new React application and start the development server.

```bash
npx create-react-app my-app
cd my-app
npm start
```

--------------------------------

### cURL Request Example

Source: https://docs.kapa.ai/api/reference/query-v-1-projects-chat

Example command to perform a chat query using cURL.

```bash
curl -L 'https://api.kapa.ai/query/v1/projects/:project_id/chat/' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-API-KEY: <X-API-KEY>' \
-d '{
  "integration_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "customization_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "source_ids_include": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "source_group_ids_include": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "query": "string",
  "user": {
    "email": "string",
    "unique_client_id": "string",
    "metadata": {
      "company_name": "string",
      "first_name": "string",
      "last_name": "string"
    }
  },
  "metadata": {
    "origin_url": "string"
  }
}'
```

--------------------------------

### Project response schema example

Source: https://docs.kapa.ai/api/reference/org-v-1-projects-read

Example JSON response structure for a successful project retrieval.

```json
{

  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",

  "team": "3fa85f64-5717-4562-b3fc-2c963f66afa6",

  "project_name": "string",

  "pii_config": {

    "entities": [

      "PHONE_NUMBER"

    ],

    "custom_regexes": [

      {

        "name": "string",

        "pattern": "string"

      }

    ],

    "allow_list": [

      "string"

    ]

  },

  "is_internal": true

}
```

--------------------------------

### cURL Request Example

Source: https://docs.kapa.ai/api/reference/query-v-1-projects-documents

Example command to fetch documents using cURL with the required API key header.

```bash
curl -L 'https://api.kapa.ai/query/v1/projects/:project_id/documents/' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-API-KEY: <X-API-KEY>' \
-d '{
  "source_group_ids_include": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "urls": [
    "string"
  ],
  "document_ids": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "page": 1,
  "page_size": 5,
  "max_chars_per_document": 50000
}'
```

--------------------------------

### Response schema example

Source: https://docs.kapa.ai/api/reference/ingestion-v-1-projects-sources-list

Example JSON response structure for the list sources request.

```json
{

  "count": 0,

  "next": "string",

  "previous": "string",

  "results": [

    {

      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",

      "name": "string",

      "type": "s3",

      "contains_internal_data": true,

      "created_at": "2024-07-29T15:51:28.071Z",

      "updated_at": "2024-07-29T15:51:28.071Z",

      "source_groups": "string"

    }

  ]

}
```

--------------------------------

### Install Agent SDK dependencies

Source: https://docs.kapa.ai/dev/agent/migrating-from-chat-sdk

Remove the legacy Chat SDK and install the new Agent SDK package.

```bash
# Remove old  

npm uninstall @kapaai/react-sdk  

  

# Install new  

npm install @kapaai/agent-react  
```

--------------------------------

### Set onboarding assistant context

Source: https://docs.kapa.ai/customizing/write-instructions

Configures the assistant to act as a helpful guide for new product users.

```text
Act as an onboarding companion for [Product]. Be welcoming, encouraging, and patient. Prefer 'getting started' resources over deep technical references when both would answer the question.
```

--------------------------------

### CURL Request Example

Source: https://docs.kapa.ai/api/reference/query-v-1-top-questions-periods-read

Example command to retrieve top-questions period data using cURL.

```bash
curl -L 'https://api.kapa.ai/query/v1/top-questions/periods/:id/' \
-H 'Accept: application/json' \
-H 'X-API-KEY: <X-API-KEY>'
```

--------------------------------

### Unsupported Blob URL Example

Source: https://docs.kapa.ai/knowledge-sources/connectors/openapi

Example of a URL format that is not supported for OpenAPI schema ingestion.

```text
blob:https://clerk.com/05c96426-79cc-42f3-8940-aa4c9dcc243f
```

--------------------------------

### Retrieve project via cURL

Source: https://docs.kapa.ai/api/reference/org-v-1-projects-read

Example command to fetch project details using cURL.

```bash
curl -L 'https://api.kapa.ai/org/v1/projects/:id/' \
-H 'Accept: application/json' \
-H 'X-API-KEY: <X-API-KEY>'
```

--------------------------------

### cURL Request Example

Source: https://docs.kapa.ai/api/reference/query-v-1-feedback-upsert

Example command to perform the feedback upsert operation using cURL.

```bash
curl -L 'https://api.kapa.ai/query/v1/feedback/upsert/' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-API-KEY: <X-API-KEY>' \
-d '{
  "comment": {
    "issue": "string",
    "incorrect": true,
    "irrelevant": true,
    "unaddressed": true
  },
  "user_identifier": "string",
  "reaction": "upvote",
  "question_answer": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'
```

--------------------------------

### Example Repository Structure

Source: https://docs.kapa.ai/knowledge-sources/connectors/github-code

A sample directory layout for a Python SDK project to be indexed by the GitHub Code connector.

```text
acme-python-sdk/  

├── src/  

│   └── acme/  

│       ├── client.py  

│       ├── models.py  

│       └── exceptions.py  

├── examples/  

│   ├── basic_usage.py  

│   └── advanced_config.py  

├── tests/  

│   └── ...  

├── docs/  

│   └── ...  

└── README.md
```

--------------------------------

### Compare Context-Dependent vs Self-Contained Documentation

Source: https://docs.kapa.ai/improving/writing-best-practices

Examples demonstrating how to rewrite documentation sections to be actionable when retrieved in isolation.

```markdown
## Updating webhook URLs  

  

Now change the endpoint to your new URL and save the configuration.  
```

```markdown
## Updating webhook URLs  

  

To update webhook endpoints in CloudSync:  

  

1. Navigate to Settings > Webhooks in your CloudSync dashboard  

2. Select the webhook you want to modify  

3. Change the endpoint URL to your new address, and click Save  
```

--------------------------------

### Remedied Contextual Dependency Example

Source: https://docs.kapa.ai/improving/writing-best-practices

A corrected version of the previous example that keeps constraints and implementation guidance in close proximity.

```text
Authentication tokens expire after 24 hours by default. When implementing the  
login flow, ensure you handle token expiration by refreshing tokens before the  
24-hour limit or implementing proper error handling for expired token  
responses.  

  

The system provides several configuration options for different environments,  
including custom token expiration periods.  


```

--------------------------------

### List sources curl request

Source: https://docs.kapa.ai/api/reference/ingestion-v-1-projects-sources-list

Example cURL command to list sources for a project.

```bash
curl -L 'https://api.kapa.ai/ingestion/v1/projects/:project_id/sources/' \
-H 'Accept: application/json' \
-H 'X-API-KEY: <X-API-KEY>'
```

--------------------------------

### Manage widget lifecycle in Vanilla JavaScript

Source: https://docs.kapa.ai/integrations/website-widget/javascript-api/widget-lifecycle

Examples for mounting, opening, and unmounting the widget using the Kapa global object.

```javascript
// Ensure the widget script is loaded  

loadScriptIfNotExists();  

  

// Render the widget with an onRender callback to open it once rendered  

window.Kapa("render", {  

  onRender: () => window.Kapa("open"),  

});  

  

// If the widget is already rendered on this page, call open directly  

window.Kapa("open");  
```

```javascript
loadScriptIfNotExists();  
// calling render when the script is already rendered is harmless,  
// it will just log a warning: “widget already rendered”  

window.Kapa("render");  
```

```javascript
// Unmount the widget in case it was rendered on another page  

window.Kapa("unmount");  
```

--------------------------------

### Setup function for widget loading

Source: https://docs.kapa.ai/integrations/website-widget/javascript-api/widget-lifecycle

A helper function to inject the widget script into the document head while disabling default auto-rendering.

```javascript
function loadScriptIfNotExists() {  

  const scriptSrc = "https://widget.kapa.ai/kapa-widget.bundle.js";  

  

  // Check if the script already exists in the document  

  if (document.querySelector(`script[src="${scriptSrc}"]`)) {  

    console.log("Website Widget script is already loaded.");  

    return;  

  }  

  

  const script = document.createElement("script");  

  

  // Set the async property correctly  

  script.async = true;  

  script.src = scriptSrc;  

  

  // Define other script attributes  

  const attributes = {  

    "data-website-id": "6d04c434-4090-4ebf-aeb3-8e90645a504d",  

    "data-project-name": "kapa.ai",  

    "data-project-color": "#5B4CFE",  

    "data-project-logo": "kapa.ai/assets/logo.png",  

    "data-render-on-load": "false",  

  };  

  

  // Set attributes on the script element  

  Object.entries(attributes).forEach(([key, value]) => {  

    script.setAttribute(key, value);  

  });  

  

  // Append to the document head  

  document.head.appendChild(script);  

}  
```

--------------------------------

### List source groups using cURL

Source: https://docs.kapa.ai/api/reference/ingestion-v-1-projects-source-groups-list

Example command to list source groups using the cURL utility.

```bash
curl -L 'https://api.kapa.ai/ingestion/v1/projects/:project_id/source-groups/' \
-H 'Accept: application/json' \
-H 'X-API-KEY: <X-API-KEY>'
```

--------------------------------

### Search API Request with cURL

Source: https://docs.kapa.ai/api/reference/query-v-1-projects-search

Example of how to perform a search request using the cURL command-line tool.

```bash
curl -L 'https://api.kapa.ai/query/v1/projects/:project_id/search/' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-API-KEY: <X-API-KEY>' \
-d '{
  "source_group_ids_include": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "source_ids_include": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  ],
  "query": "string",
  "num_results": 10,
  "include_source_names": [
    "string"
  ],
  "source_group_order": [
    "string"
  ],
  "source_ids_order": [
    "string"
  ]
}'
```

--------------------------------

### Install Kapa Widget in Next.js Pages Router

Source: https://docs.kapa.ai/integrations/website-widget/installation/nextjs

Add the widget script to the _document file for legacy Pages Router setups.

```tsx
import { Html, Head, Main, NextScript } from "next/document";  

  

export default function Document() {  

  return (  

    <Html>  

      <Head>  

        <script  

          src="https://widget.kapa.ai/kapa-widget.bundle.js"  

          data-website-id="XXX-XXX-XXX"  

          data-project-name="PROJECT_NAME"  

          data-project-color="#HEX_COLOR_CODE"  

          data-project-logo="https://LINK_TO_LOGO.com/logo.png"  

          async  

        />  

      </Head>  

      <body>  

        <Main />  

        <NextScript />  

      </body>  

    </Html>  

  );  

}  
```

--------------------------------

### Start the MCP Proxy Service

Source: https://docs.kapa.ai/examples/add-documentation-search-to-mcp-server

Command to launch the MCP server and inspector containers using Docker Compose.

```bash
docker compose up
```

--------------------------------

### Agent Reasoning and Tool Execution Example

Source: https://docs.kapa.ai/examples/langchain-knowledge-base-search

A trace showing how the agent combines product data and documentation search tools to answer complex user queries.

```text
You: We keep hitting 429 errors on webhooks. Are we on the wrong plan?  

  

🧠 The agent thinks:  

This sounds like a product question that involves both plan limits and webhook docs.  

I should first see what the docs say about 429 errors on webhooks.  

  

🔧 Calling tool: search_my_awesome_product_knowledge_sources  

    query: webhook 429 rate limit  

✓ Tool completed  

  

📎 The docs say (snippet):  

"If you receive 429 responses for webhooks, it means you've exceeded your plan's rate limit.  

Starter: 100 requests/minute  

Pro: 300 requests/minute  

Enterprise: 1000 requests/minute."  

  

To know which limit applies here, I need to check the user's subscription plan.  

  

🔧 Calling tool: get_subscription_info  

✓ Tool completed  

    plan_name: Pro  

    status: active  

    seats_used: 8  

    seats_total: 10  

    billing_cycle: annual  

    features: [Unlimited projects, Advanced analytics, Priority support, Custom integrations, API access, SSO authentication]  

  

🧠 The agent now knows:  

- You're on the Pro plan  

- For Pro, the docs say the webhook limit is 300 requests/minute  

  

💬 Answer  

You're on the **Pro** plan. According to the docs, Pro limits webhook deliveries to **300 requests per minute**.  

  

Your recent usage is exceeding that, which is why you're seeing 429 errors. You have a few options:  

  

- Reduce webhook volume (for example, batch events or filter which events you send)  

- Add backoff / retry logic on your side  

- Upgrade to a plan with higher webhook limits  

  

I can also show you the docs section that explains these limits in more detail if you'd like.  
```

--------------------------------

### Implement multiple entry points with custom buttons

Source: https://docs.kapa.ai/integrations/website-widget/guides/best-practices

Combine the standard widget installation script with a custom button that triggers the widget using window.Kapa.open().

```html
<script  

  async  

  src="https://widget.kapa.ai/kapa-widget.bundle.js"  

  data-website-id="YOUR-INTEGRATION-ID"  

  data-project-name="Your Project"  

  data-project-color="#6306B6"  

  data-project-logo="https://example.com/logo.png"  
></script>  

  

<button onclick="window.Kapa.open()">Ask AI</button>
```

--------------------------------

### Compare Generic vs Specific Troubleshooting Documentation

Source: https://docs.kapa.ai/improving/writing-best-practices

Examples showing the difference between vague troubleshooting steps and documentation that includes specific error messages.

```markdown
## Connection problems  

  

If the connection fails, check your network settings and firewall configuration.  
```

```markdown
## CloudSync connection problems  

  

### Error: "Connection timeout after 30 seconds"  

  

This error occurs when CloudSync cannot reach the…  

  

### Error: "Authentication failed (401)"  

  

This indicates invalid or expired credentials…  
```

--------------------------------

### Markdown conversation payload example

Source: https://docs.kapa.ai/integrations/support-form-deflector/conversation-handoff

Example of the markdown-formatted conversation string received when data-handoff-payload-format is set to markdown.

```markdown
### Kapa AI conversation  

  

Thread: https://link.kapa.ai/sfd/<threadId>  

  

**Question:**  

  

How do I get started?  

  

**Answer:**  

  

You can get started by...  

  

**Sources:**  
- [Getting started](https://docs.example.com/getting-started)
```

--------------------------------

### Chat Stream Response Schema Example

Source: https://docs.kapa.ai/api/reference/query-v-1-threads-chat-chat-stream

An example of the JSON structure returned by the chat stream endpoint.

```json
[
  {
    "chunk": {
      "type": "partial_answer",
      "content": {
        "relevant_sources": [
          {
            "title": "string",
            "source_url": "string",
            "contains_internal_data": true
          }
        ]
      },
      "stream_end": true
    }
  }
]
```

--------------------------------

### Create In-Product Agent with LangChain

Source: https://docs.kapa.ai/examples/langchain-knowledge-base-search

Initializes an agent by combining native Python tools with external MCP tools and configuring the reasoning model.

```python
from langchain.agents import create_agent  

from langchain_openai import ChatOpenAI  

from langchain_mcp_adapters.client import MultiServerMCPClient  

  

from src.tools.subscription import get_subscription_info  

from src.tools.team import get_team_members  

  

SYSTEM_PROMPT_TEMPLATE = """You are an intelligent assistant embedded in {product_name}.  

  

You have access to three types of tools:  

  

- `get_subscription_info`: Use this when users ask about their plan, billing, pricing, seat limits...  

- `get_team_members`: Use this when users ask about who is on their team, roles, permissions...  

- `search_{product_name}_knowledge_sources`: Use this for ANY questions about how to use {product_name}...  

  

... (guidelines omitted for brevity) ...  

"""  

  

async def create_in_product_agent(  

    mcp_server_url: str | None = None,  

    mcp_api_key: str | None = None,  

    product_name: str | None = None,  

    model_name: str = "gpt-5.1",  

):  

    # Read config from env if not passed in  

    mcp_server_url = mcp_server_url or os.getenv("KAPA_MCP_SERVER_URL")  

    mcp_api_key = mcp_api_key or os.getenv("KAPA_API_KEY")  

    product_name = product_name or os.getenv("PRODUCT_NAME", "<Your Product>")  

  

    if not mcp_server_url or not mcp_api_key:  

        raise ValueError("KAPA_MCP_SERVER_URL and KAPA_API_KEY must be set.")  

  

    # 1) Start with native tools  

    tools = [get_subscription_info, get_team_members]  

  

    # 2) Add tools from the hosted MCP server  

    mcp_client = MultiServerMCPClient(  

        {  

            "kapa": {  

                "transport": "streamable_http",  

                "url": mcp_server_url,  

                "headers": {"Authorization": f"Bearer {mcp_api_key}"},  

            }  

        }  

    )  

  

    mcp_tools = await mcp_client.get_tools()  

    tools.extend(mcp_tools)  

  

    print(f"Loaded {len(mcp_tools)} tool(s) from Kapa MCP server:")  

    for tool in mcp_tools:  

        print(f"  → {tool.name}")  

    print()  

  

    # 3) Build the system prompt with your product name  

    system_prompt = SYSTEM_PROMPT_TEMPLATE.format(product_name=product_name)  

  

    # 4) Configure the reasoning model  

    model = ChatOpenAI(  

        model=model_name,  

        reasoning={  

            "effort": "medium",  

            "summary": "detailed",  

        },  

    )  

  

    # 5) Create the agent – this runs the ReAct loop for you  

    agent = create_agent(  

        model=model,  

        tools=tools,  

        system_prompt=system_prompt,  

    )  

  

    return agent
```

--------------------------------

### Question Answer Response Schema Example

Source: https://docs.kapa.ai/api/reference/query-v-1-projects-question-answers-list

An example JSON response structure for the question-answers list endpoint.

```json
[  

  {  

    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  

    "thread_id": "string",  

    "question": "string",  

    "answer": "string",  

    "query_type": "retrieval",  

    "is_uncertain": true,  

    "is_redacted": true,  

    "end_user_id": "string",  

    "created_at": "2024-07-29T15:51:28.071Z",  

    "feedback": [  

      {  

        "reaction": "upvote",  

        "comment": "string",  

        "incorrect": true,  

        "irrelevant": true,  

        "unaddressed": true,  

        "created_at": "2024-07-29T15:51:28.071Z"  

      }  

    ]  

  }  

]
```

--------------------------------

### List Threads Response Schema Example

Source: https://docs.kapa.ai/api/reference/query-v-1-projects-threads-list

An example JSON response structure for a successful thread retrieval request.

```json
[  

  {  

    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  

    "created_at": "2024-07-29T15:51:28.071Z",  

    "last_activity_at": "2024-07-29T15:51:28.071Z",  

    "integration_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  

    "question_answers": [  

      {}  

    ],  

    "has_more_question_answers": true  

  }  

]
```

--------------------------------

### Initialize and use the Agent class

Source: https://docs.kapa.ai/dev/agent/core

Instantiate the Agent class with project configuration and event handlers, then trigger the agent loop using sendMessage.

```typescript
import { Agent } from '@kapaai/agent-core';

const agent = new Agent({
  projectId: 'your-project-id',
  integrationId: 'your-integration-id',
  model: 'kapa-agent-1.0',
  tools: [],
  context: {},
  getSessionToken: async () => {
    const res = await fetch('/api/session', { method: 'POST' });
    return res.json(); // SDK accepts the raw API response directly
  },
  onMessagesChange: (messages) => {
    // Called whenever messages update (new text, tool calls, etc.)
    renderMessages(messages);
  },
  onStreamingChange: (isStreaming) => {
    // Called when streaming starts or stops
    toggleLoadingIndicator(isStreaming);
  },
});

// Send a message — triggers the agent loop
await agent.sendMessage('How do I get started?');
```

--------------------------------

### Implement a basic chat interface with useChat

Source: https://docs.kapa.ai/dev/sdk/components/useChat

A complete example showing how to manage conversation state, submit queries, and handle generation status using the useChat hook.

```javascript
import React, { useState } from "react";  

import { useChat } from "@kapaai/react-sdk";  

  

function ChatInterface() {  

  const [inputValue, setInputValue] = useState("");  

  const { conversation, submitQuery, isGeneratingAnswer, stopGeneration } =  

    useChat();  

  

  const handleSubmit = (e) => {  

    e.preventDefault();  

    if (inputValue.trim()) {  

      submitQuery(inputValue);  

      setInputValue("");  

    }  

  };  

  

  return (  

    <div className="chat-container">  

      <div className="messages">  

        {conversation.map((qa) => (  

          <div key={qa.id || `temp-${qa.question}`}>  

            <div className="user-message">{qa.question}</div>  

            <div className="ai-message">  

              {qa.answer || (isGeneratingAnswer ? "Typing..." : "")}  

            </div>  

          </div>  

        ))}  

      </div>  

  

      <form onSubmit={handleSubmit}>  

        <input  

          value={inputValue}  

          onChange={(e) => setInputValue(e.target.value)}  

          placeholder="Ask a question..."  

          disabled={isGeneratingAnswer}  

        />  

        {isGeneratingAnswer ? (  

          <button type="button" onClick={stopGeneration}>  

            Stop  

          </button>  

        ) : (  

          <button type="submit">Send</button>  

        )}  

      </form>  

    </div>  

  );  

}  
```

--------------------------------

### Problematic Contextual Dependency Example

Source: https://docs.kapa.ai/improving/writing-best-practices

An example of documentation where critical context is separated by unrelated information, leading to ambiguity during chunking.

```text
Authentication tokens expire after 24 hours by default.  
  

  

The system provides several configuration options for different environments.  

  

When implementing the login flow, ensure you handle this appropriately.  


```

--------------------------------

### Initialize Agent and Handle UI Events

Source: https://docs.kapa.ai/dev/agent/quickstart/core

JavaScript implementation for initializing the Agent instance, handling message rendering, and wiring up UI interactions.

```javascript
import { Agent } from '@kapaai/agent-core';

const agent = new Agent({
  projectId: 'your-project-id',
  integrationId: 'your-integration-id',
  model: 'kapa-agent-1.0',
  tools: [],
  context: {},
  getSessionToken: async () => {
    const res = await fetch('/api/session', { method: 'POST' });
    if (!res.ok) throw new Error('Session failed');
    return res.json();
  },
  onMessagesChange: (messages) => {
    const container = document.getElementById('messages');
    container.innerHTML = '';

    for (const msg of messages) {
      const el = document.createElement('div');

      if (msg.role === 'user') {
        el.textContent = msg.content;
        el.className = 'user-message';
      } else {
        // Render each block (text or tool calls)
        for (const block of msg.blocks) {
          if (block.type === 'text' && block.content) {
            const textEl = document.createElement('div');
            textEl.textContent = block.content;
            el.appendChild(textEl);
          }
          if (block.type === 'tool_calls') {
            for (const tc of block.toolCalls) {
              const toolEl = document.createElement('div');
              toolEl.className = 'tool-card';
              toolEl.textContent = `${tc.displayName || tc.name}: ${tc.status}`;
              if (tc.result) {
                toolEl.textContent += ` — ${JSON.stringify(tc.result)}`;
              }
              el.appendChild(toolEl);
            }
          }
        }
      }

      container.appendChild(el);
    }

    container.scrollTop = container.scrollHeight;
  },
  onStreamingChange: (streaming) => {
    document.getElementById('streaming-indicator').style.display =
      streaming ? 'block' : 'none';
    document.getElementById('send-btn').style.display =
      streaming ? 'none' : 'block';
    document.getElementById('stop-btn').style.display =
      streaming ? 'block' : 'none';
  },
});

// Wire up buttons
document.getElementById('send-btn').onclick = () => {
  const input = document.getElementById('input');
  const text = input.value.trim();
  if (text) {
    input.value = '';
    agent.sendMessage(text);
  }
};

document.getElementById('stop-btn').onclick = () => agent.stopGeneration();
document.getElementById('new-chat-btn').onclick = () => agent.resetConversation();

document.getElementById('input').onkeydown = (e) => {
  if (e.key === 'Enter') document.getElementById('send-btn').click();
};
```

--------------------------------

### Problematic Semantic Discoverability Example

Source: https://docs.kapa.ai/improving/writing-best-practices

An example of a heading and content that lacks specific product terminology, preventing retrieval for targeted queries.

```markdown
## Configure timeouts  

  

Configure custom timeout settings and retry logic for improved reliability in  
production environments. Access these options through the admin panel.  


```

--------------------------------

### Initialize the documentation agent

Source: https://docs.kapa.ai/examples/build-a-documentation-chatbot-with-mastra-and-kapa

Configure the agent to use the tools provided by the MCP client.

```typescript
export const docsAgent = new Agent({

  // ...instructions and identity, rewritten later in this tutorial

  model: 'openai/gpt-5-mini',

  tools: await mcpClient.listTools(),

  memory: new Memory(),

});
```

--------------------------------

### GET /query/v1/projects/:project_id/integrations/

Source: https://docs.kapa.ai/api/reference/query-v-1-projects-integrations-list

Retrieves a list of all integrations for a specified project.

```APIDOC
## GET /query/v1/projects/:project_id/integrations/

### Description
List all integrations for a project.

### Method
GET

### Endpoint
https://api.kapa.ai/query/v1/projects/:project_id/integrations/

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

### Response
#### Success Response (200)
- **id** (uuid) - The unique identifier of the integration.
- **project** (uuid) - The project that the integration belongs to.
- **name** (string) - The name of the integration.
- **description** (string) - The description of the integration.
- **integration_type** (string) - The type of the integration.
- **updated_at** (date-time) - The date and time when this record was last updated.
- **created_at** (date-time) - The date and time when this record was created.

#### Response Example
[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "project": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "description": "string",
    "integration_type": "SLACK_CHANNEL",
    "updated_at": "2024-07-29T15:51:28.071Z",
    "created_at": "2024-07-29T15:51:28.071Z"
  }
]
```

--------------------------------

### Create kapa.js initialization script

Source: https://docs.kapa.ai/integrations/website-widget/installation/fern

Create this file in your docs directory to load the Kapa widget. Replace the placeholder values with your specific project details.

```javascript
var script = document.createElement("script");  

script.src = "https://widget.kapa.ai/kapa-widget.bundle.js";  

script.setAttribute("data-website-id", "YOUR_WEBSITE_ID");  

script.setAttribute("data-project-name", "YOUR_PROJECT_NAME");  

script.setAttribute("data-project-color", "YOUR_PROJECT_COLOR");  

script.setAttribute("data-project-logo", "https://LINK_TO_LOGO.com/logo.png");  

script.async = true;  

document.head.appendChild(script);
```

--------------------------------

### Build Sphinx Documentation

Source: https://docs.kapa.ai/integrations/website-widget/installation/sphinx

Run the build command to apply the widget changes to your documentation.

```bash
make html  
```

--------------------------------

### GET https://api.kapa.ai/org/v1/projects/:id/

Source: https://docs.kapa.ai/api/reference/org-v-1-projects-read

Retrieve a project that the user has access to.

```APIDOC
## GET https://api.kapa.ai/org/v1/projects/:id/

### Description
Retrieve a project that the user has access to.

### Method
GET

### Endpoint
https://api.kapa.ai/org/v1/projects/:id/

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the project.

### Authorization
- **X-API-KEY** (apiKey) - Required - Header parameter for authentication.

### Response
#### Success Response (200)
- **id** (uuid) - The unique identifier of the project.
- **team** (uuid) - The team to which the project belongs.
- **project_name** (string) - The name of the project.
- **pii_config** (object) - Configuration for PII redaction.
- **is_internal** (boolean) - Whether the project is labeled as internal.

#### Response Example
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "team": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "project_name": "string",
  "pii_config": {
    "entities": ["PHONE_NUMBER"],
    "custom_regexes": [{"name": "string", "pattern": "string"}],
    "allow_list": ["string"]
  },
  "is_internal": true
}
```

--------------------------------

### GET /ingestion/v1/projects/:project_id/sources/

Source: https://docs.kapa.ai/api/reference/ingestion-v-1-projects-sources-list

Retrieves a list of all sources for a specified project.

```APIDOC
## GET https://api.kapa.ai/ingestion/v1/projects/:project_id/sources/

### Description
List all sources for a project.

### Method
GET

### Endpoint
https://api.kapa.ai/ingestion/v1/projects/:project_id/sources/

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

### Response
#### Success Response (200)
- **count** (integer) - The total number of items in the collection.
- **next** (uri) - A link to the next page of items, or null if there is no next page.
- **previous** (uri) - A link to the previous page of items, or null if this is the first page.
- **results** (object[]) - Array of source objects.

#### Response Example
{
  "count": 0,
  "next": "string",
  "previous": "string",
  "results": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "type": "s3",
      "contains_internal_data": true,
      "created_at": "2024-07-29T15:51:28.071Z",
      "updated_at": "2024-07-29T15:51:28.071Z",
      "source_groups": "string"
    }
  ]
}
```

--------------------------------

### GET /end_users

Source: https://docs.kapa.ai/api/reference/end-users

Retrieves a list of all end users associated with a project.

```APIDOC
## GET /end_users

### Description
List all end users (ie: users who interact with your Kapa bot) for a project.

### Method
GET

### Endpoint
/end_users
```

--------------------------------

### Configure Core Widget Parameters

Source: https://docs.kapa.ai/integrations/website-widget/configuration/behavior

Initialize the widget with required website ID and optional branding parameters.

```html
<script  

  async  

  src="https://widget.kapa.ai/kapa-widget.bundle.js"  

  data-website-id="XXX-XXX-XXX"  

  data-project-name="kapa.ai"  

  data-project-color="#6306B6"  

  data-project-logo="https://example.com/logo.png"  

></script>
```

--------------------------------

### Configure Sidebar View Mode

Source: https://docs.kapa.ai/integrations/website-widget/configuration/theming

Example of initializing the widget with the sidebar view mode enabled, including settings to keep the modal open and hide the launcher button.

```html
<script  

  ...  

  data-view-mode="sidebar"  

  data-modal-open-by-default="true"  

  data-launcher-button-hidden="true"  

></script>
```

--------------------------------

### GET /organizations/<YOUR_ORG>/events/

Source: https://docs.kapa.ai/examples/build-a-support-triage-agent-with-claude-managed-agents-and-kapa

Query performance traces and event data.

```APIDOC
## GET /organizations/<YOUR_ORG>/events/

### Description
Query performance events, such as transaction durations and counts.

### Method
GET

### Endpoint
https://sentry.io/api/0/organizations/<YOUR_ORG>/events/

### Parameters
#### Query Parameters
- **field** (string) - Required - Fields to aggregate (e.g., transaction, count(), p95(transaction.duration))
- **query** (string) - Required - Filter criteria
- **statsPeriod** (string) - Optional - Time window
- **per_page** (integer) - Optional - Results per page
```

--------------------------------

### GET https://api.kapa.ai/query/v1/threads/:id/

Source: https://docs.kapa.ai/api/reference/query-v-1-threads-read

Retrieve details about a thread by its unique identifier.

```APIDOC
## GET https://api.kapa.ai/query/v1/threads/:id/

### Description
Retrieve details about a thread.

### Method
GET

### Endpoint
https://api.kapa.ai/query/v1/threads/:id/

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the thread.

### Response
#### Success Response (200)
- **id** (uuid) - The unique identifier of the thread.
- **integration** (object) - The integration associated with the thread.
- **question_answers** (object[]) - List of question and answer objects associated with the thread.
- **created_at** (date-time) - The date and time when this record was created.

#### Response Example
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "integration": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "project": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "string",
    "description": "string",
    "integration_type": "SLACK_CHANNEL",
    "updated_at": "2024-07-29T15:51:28.071Z",
    "created_at": "2024-07-29T15:51:28.071Z"
  },
  "question_answers": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "thread_id": "string",
      "question": "string",
      "answer": "string",
      "query_type": "retrieval",
      "is_uncertain": true,
      "is_redacted": true,
      "end_user_id": "string",
      "created_at": "2024-07-29T15:51:28.071Z",
      "feedback": [
        {
          "reaction": "upvote",
          "comment": "string",
          "incorrect": true,
          "irrelevant": true,
          "unaddressed": true,
          "created_at": "2024-07-29T15:51:28.071Z"
        }
      ],
      "relevant_sources": "string"
    }
  ],
  "created_at": "2024-07-29T15:51:28.071Z"
}
```

--------------------------------

### Define a basic React component

Source: https://docs.kapa.ai/dev/sdk/tutorials/embedded-chat

A simple functional component example for rendering text.

```jsx
function Welcome() { return <h1>Hello, World!</h1>; }
```

--------------------------------

### Scaffold the Mastra template

Source: https://docs.kapa.ai/examples/build-a-documentation-chatbot-with-mastra-and-kapa

Initialize a new project using the Mastra docs-chatbot template.

```bash
npx create-mastra@latest --template docs-chatbot

cd docs-chatbot
```

--------------------------------

### Initialize Kapa Widget in Mintlify

Source: https://docs.kapa.ai/integrations/website-widget/installation/mintlify

Create a JavaScript file in your docs directory to load the Kapa widget script with your project configuration.

```javascript
const script = document.createElement("script");  

script.src = "https://widget.kapa.ai/kapa-widget.bundle.js";  

script.async = true;  

script.setAttribute("data-website-id", "XXX-XXX-XXX");  

script.setAttribute("data-project-name", "PROJECT_NAME");  

script.setAttribute("data-project-color", "#HEX_COLOR_CODE");  

script.setAttribute("data-project-logo", "https://LINK_TO_LOGO.com/logo.png");  

document.head.appendChild(script);  
```

--------------------------------

### List Threads CURL Request

Source: https://docs.kapa.ai/api/reference/query-v-1-projects-threads-list

Example command to retrieve threads using cURL.

```bash
curl -L 'https://api.kapa.ai/query/v1/projects/:project_id/threads/' \
-H 'Accept: application/json' \
-H 'X-API-KEY: <X-API-KEY>'
```

--------------------------------

### Project Integration Response Schema

Source: https://docs.kapa.ai/api/reference/query-v-1-projects-integrations-list

Example JSON response structure for a project integration.

```json
[  

  {  

    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  

    "project": "3fa85f64-5717-4562-b3fc-2c963f66afa6",  

    "name": "string",  

    "description": "string",  

    "integration_type": "SLACK_CHANNEL",  

    "updated_at": "2024-07-29T15:51:28.071Z",  

    "created_at": "2024-07-29T15:51:28.071Z"  

  }  

]
```

--------------------------------

### window.Kapa("render", options)

Source: https://docs.kapa.ai/integrations/website-widget/javascript-api/widget-lifecycle

Asynchronously mounts and initializes the global Kapa object. It optionally accepts an 'onRender' callback that executes after the widget has been fully rendered.

```APIDOC
## window.Kapa("render", options)

### Description
Asynchronously mounts and initializes the global Kapa object. Use this to manually control when the widget appears on the page.

### Parameters
- **options** (object) - Optional - Configuration object for the render process.
  - **onRender** (function) - Optional - A callback function that executes after the widget has been fully rendered.
```

--------------------------------

### Query Project Activity via cURL

Source: https://docs.kapa.ai/api/reference/query-v-1-projects-activity-read

Example request to fetch project activity data using the cURL command-line tool.

```bash
curl -L 'https://api.kapa.ai/query/v1/projects/:project_id/activity/' \
-H 'Accept: application/json' \
-H 'X-API-KEY: <X-API-KEY>'
```

--------------------------------

### GET /organizations/<YOUR_ORG>/issues/<issue-id>/

Source: https://docs.kapa.ai/examples/build-a-support-triage-agent-with-claude-managed-agents-and-kapa

Retrieve detailed information about a specific issue.

```APIDOC
## GET /organizations/<YOUR_ORG>/issues/<issue-id>/

### Description
Get status, counts, and timestamps for a specific issue.

### Method
GET

### Endpoint
https://sentry.io/api/0/organizations/<YOUR_ORG>/issues/<issue-id>/
```

--------------------------------

### GET /query/v1/projects/:project_id/end-users/

Source: https://docs.kapa.ai/api/reference/query-v-1-projects-end-users-list

Retrieves a list of end users for a given project ID.

```APIDOC
## GET https://api.kapa.ai/query/v1/projects/:project_id/end-users/

### Description
List all end users (i.e., users who interact with your Kapa bot) for a project.

### Method
GET

### Endpoint
https://api.kapa.ai/query/v1/projects/:project_id/end-users/

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

#### Query Parameters
- **has_email** (string) - Optional - Has Email
- **search** (string) - Optional - A search term.
- **ordering** (string) - Optional - Which field to use when ordering the results.

### Response
#### Success Response (200)
- **id** (uuid) - The unique identifier of the end user.
- **display_id** (string) - Display id
- **email** (string) - Email (nullable)
- **unique_client_id** (string) - Unique client id (nullable)
- **company_name** (string) - Company name (nullable)
- **created_at** (date-time) - Creation timestamp
- **google_sub_id** (string) - Google sub id (nullable)
- **github_sub_id** (string) - Github sub id (nullable)
- **kapa_oidc_sub_id** (string) - Kapa oidc sub id (nullable)

#### Response Example
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "display_id": "string",
  "email": "string",
  "unique_client_id": "string",
  "company_name": "string",
  "created_at": "2024-07-29T15:51:28.071Z",
  "google_sub_id": "string",
  "github_sub_id": "string",
  "kapa_oidc_sub_id": "string"
}
```

--------------------------------

### Configure the MCP client

Source: https://docs.kapa.ai/examples/build-a-documentation-chatbot-with-mastra-and-kapa

Set up the MCP client to connect to the local MCP server via SSE.

```typescript
import { MCPClient } from '@mastra/mcp';



export const mcpClient = new MCPClient({

  servers: {

    // Connect to local MCP server via SSE

    localTools: {

      url: new URL(process.env.MCP_SERVER_URL || 'http://localhost:4112/sse'),

    },

  },

});
```

--------------------------------

### Set marketing deployment context

Source: https://docs.kapa.ai/customizing/write-instructions

Configures the assistant to act as a representative on a marketing website.

```text
You are on [Company]'s marketing website, talking to potential customers who are evaluating the product. When unsure about a detail, do not hedge with 'the docs don't state' language. Answer what you know and invite the user to connect with the team.
```
Tokens:
Raw