Skip to main content

Quickstart

Follow this guide to make your first API calls. Explore the full API Reference to see all available functionality.

Select a project​

Decide which of your Kapa instances you want to make calls to. The Kapa API refers to instances as Projects. You can find the id of your projects in the Kapa platform under the project management screen. Most API endpoints require you to specify a project_id.

Create an API key​

To start using the Kapa API, you need an API key for authentication. You can create or delete your API keys in the Kapa platform by logging in and navigating to the "API Keys" tab in the navigation menu. Note that only team owners can create or delete API keys. API keys are always associated with a single Project. You can create multiple API keys per Project. Reach out to the Kapa team if you need any assistance.

caution

Do not put your Kapa API key into any frontend code. API keys can not be hidden on the broswer and everyboy will be able to grab your key and make requests to your Kapa instance programmatically. Check out this FAQ for more detailed explanation.

Create an API integration​

In the context of API usage, an API integration_id is used to track usage analytics for your API specifically. This allows you to track your usage of Kapa via the API seperately from other integraion types (ie: Slack, Discord, etc). Note: an API Integration ID alone does NOT permit authentication. You must use an API key and API integration_id together if you wish to make authenticated API calls and track API usage.

You can create and manage integrations in the integrations tab in the Kapa platform.

You can get the IDs of your integrations either from the management screen in the Kapa platform or you can use the API to list all of your integrations:

curl --location 'https://api.placeholder.com/query/v1/projects/{project_id}/integrations/' \
--header 'X-API-KEY: <API_KEY>'

Configure data sources​

Before you can make calls to the Chat endpoints you need to configure your data sources through the Kapa platform. Without data sources Kapa cannot perform retrieval.

Start a conversation​

Send a first question to your Kapa instance.

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

Continue the conversation in a thread​

The first request has created a new thread in the Kapa system. Use the returned thread_id to continue the conversation.

curl --location 'https://api.placeholder.com/query/v1/threads/{thread_id}/chat/' \
--header 'X-API-KEY: <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "integration_id": "<INTEGRATION_ID>",
    "query": "Cool what else can I do?"
}'

Submit feedback for a generation​

Upvote the answer to the last question and provide an additional comment. For this you need the question_answer_id returned by the chat endpoint. The submitted feedback is immediately visible in the Kapa platform. Gathering feedback from your users on Kapa's answers lets you track Kapa's performance over time.

curl --location 'https://api.placeholder.com/query/v1/feedback/upsert/' \
--header 'X-API-KEY: <API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "user_identifier": "Test User",
    "reaction": "upvote",
    "question_answer": "<QUESTION_ANSWER_ID>",
    "comment": {
        "issue": "Thank you this answer was perfect",
        "incorrect": false,
        "irrelevant": false,
        "unaddressed": false
    }
}'