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 referrs 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.ai API, you need an API key for authentication. Reach out to the kapa.ai team to get an API key. API keys can be permissioned for one or multiple Projects.

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​

Integrations are used to seperate question traffic for analytics. E.g., they let you keep track of whether a question comes from the kapa integration in your platform or support form. You can create and manage existing 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
    }
}'