Skip to main content
API docs by Redocly

Kapa.ai (v1)

Download OpenAPI specification:Download

Terms of Service

API for Kapa.ai

Projects

Every team can have one or more projects with distinct sources, configurations and integrations.

Retrieve a project

Retrieve a project that the user has access to.

Authorizations:
Bearer
path Parameters
id
required
string

The ID of the project.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "team": "95527efb-6695-4aae-916e-c9869b1fb2bd",
  • "project_name": "string"
}

Sources

Sources represent the knowledge sources which kapa bases its answers on. Sources are configured via the kapa.ai platform. See here for more information.

List all sources

List all sources for a project.

Authorizations:
Bearer
path Parameters
project_id
required
string

The ID of the project.

query Parameters
page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page.

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "next": "http://example.com",
  • "previous": "http://example.com",
  • "results": [
    ]
}

Retrieve a source

Retrieve a source for a project.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

A UUID string identifying this [-] Source.

project_id
required
string

The ID of the project.

Responses

Response samples

Content type
application/json
{
  • "project": "9ec8a81a-31b2-4a83-bcd8-cef9150932d2",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "title_prefix": "string",
  • "description": "string",
  • "type": "s3",
  • "contains_internal_data": true,
  • "ready_for_review": true,
  • "ingest_without_review": true,
  • "ingested_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "has_periodic_task": "string",
  • "next_run_at": "string",
  • "last_task_name": "string",
  • "last_task_status": "string",
  • "last_task_error": "string",
  • "periodic_task": "0",
  • "can_be_deleted": "string",
  • "can_be_refreshed": "string",
  • "can_be_duplicated": "string",
  • "deployed_markdown_items": 0,
  • "markdown_pii_config": {
    }
}

Integrations

Integrations are used to deploy your kapa.ai instances. Integrations are configured in the kapa.ai platform.

List all integrations

List all integrations for a project.

Authorizations:
Bearer
path Parameters
project_id
required
string

The ID of the project.

query Parameters
integration_type
Array of strings
Items Enum: "SLACK_CHANNEL" "SLACK_WORKSPACE" "DISCORD_CHANNEL" "DISCORD_SERVER" "WIDGET" "SUPPORT_FORM_DEFLECTOR" "API" "DASHBOARD_CHAT"

Filter by integration type(s). Can be specified multiple times for multiple types.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Chat

You can use several endpoints to chat with your kapa.ai instances.

Chat

Chat with your kapa.ai instance. Calling this endpoint creates a new Thread object in the database and returns the answer to the user's query. A Thread object is a collection of messages in a conversation between the user and the AI model. To ask follow-up questions, use the thread_id returned in the response and call the chat in thread endpoint.

Authorizations:
Bearer
path Parameters
project_id
required
string

The ID of the project.

Request Body schema: application/json
required
integration_id
string <uuid> (Integration id)

Optional integration id for the request. Use the ID of the integration that the user is interacting with. If not provided, the conversation may not be included in some statistics that group by integration.

query
required
string (Query) [ 1 .. 5000 ] characters

The query to ask the bot.

object (EndUserInfo)

Optional user data for end-user tracking. This includes user identifiers as well as metadata with additional information like the name and company of a user.

object (QueryInputMetadata)

Optional metadata for the query input. This includes information like the page URL from which the query was submitted.

Responses

Request samples

Content type
application/json
{
  • "integration_id": "55d7337e-1d0a-49fc-9826-925ba40df035",
  • "query": "string",
  • "user": {
    },
  • "metadata": {}
}

Response samples

Content type
application/json
{
  • "answer": "string",
  • "thread_id": "string",
  • "question_answer_id": "string",
  • "is_uncertain": true,
  • "relevant_sources": [
    ]
}

Custom chat

In contrast to the standard chat API endpoints, the custom chat API grants the users full control over the prompting. The custom chat API has access to the same data sources as the regular chat endpoints. This enables users to develop applications with tailored behavior beyond the scope of standard Kapa functionality.

This endpoint is not streamed.

Authorizations:
Bearer
path Parameters
project_id
required
string

The ID of the project.

Request Body schema: application/json
required
integration_id
string <uuid> (Integration id)

Optional integration id for the request. Use the ID of the integration that the user is interacting with. If not provided, the conversation may not be included in some statistics that group by integration.

required
Array of objects (Message)

List of messages to be used for the conversation.

retrieval_query
string (Retrieval query) non-empty

Optional query to use for retrieval instead of 'query' message

persist_answer
boolean (Persist answer)
Default: true

Set to False to not save answer in kapa for analytics.

use_retrieval
boolean (Use retrieval)
Default: true

Set to False to perform a pure LLM generation without retrieval.

label_internal_sources
boolean (Label internal sources)
Default: false

Set to True to mark internal sources in context.

generation_model
string (Generation model)
Default: "gpt-4-0613"
Enum: "gpt-4" "gpt-4-0613" "gpt-4-turbo-preview" "gpt-4-1106-preview" "gpt-4-0125-preview" "gpt-4o" "gpt-4o-2024-05-13" "gpt-4o-2024-08-06" "gpt-4o-mini" "gpt-4o-mini-2024-07-18" "gpt-3.5-turbo" "gpt-3.5-turbo-16k" "gpt-3.5-turbo-0125"

The LLM used for generation.

source_ids_include
Array of strings <uuid> [ items <uuid > ]

Optional list of source UUIDs for restricting retrieval.

response_format
string (Response format)
Value: "json_object"

Optional LLM output format.

redact_conversation
boolean (Redact conversation)
Default: false

Set to True to redact question and answer in analytics.

Responses

Request samples

Content type
application/json
{
  • "integration_id": "55d7337e-1d0a-49fc-9826-925ba40df035",
  • "messages": [
    ],
  • "retrieval_query": "string",
  • "persist_answer": true,
  • "use_retrieval": true,
  • "label_internal_sources": false,
  • "generation_model": "gpt-4",
  • "source_ids_include": [
    ],
  • "response_format": "json_object",
  • "redact_conversation": false
}

Response samples

Content type
application/json
{
  • "answer": "string",
  • "thread_id": "1de43264-67cb-48af-89f9-e865c375bb84",
  • "question_answer_id": "7d960536-abce-4add-bdc0-29c0f5637b82",
  • "messages": [
    ],
  • "relevant_sources": [
    ]
}

Chat in thread

Query the Kapa.ai API with a question to continue the conversation in an existing Thread.

Authorizations:
Bearer
path Parameters
thread_id
required
string

The ID of the thread.

Request Body schema: application/json
required
integration_id
string <uuid> (Integration id)

Optional integration id for the request. Use the ID of the integration that the user is interacting with. If not provided, the conversation may not be included in some statistics that group by integration.

query
required
string (Query) [ 1 .. 5000 ] characters

The query to ask the bot.

object (EndUserInfo)

Optional user data for end-user tracking. This includes user identifiers as well as metadata with additional information like the name and company of a user.

object (QueryInputMetadata)

Optional metadata for the query input. This includes information like the page URL from which the query was submitted.

Responses

Request samples

Content type
application/json
{
  • "integration_id": "55d7337e-1d0a-49fc-9826-925ba40df035",
  • "query": "string",
  • "user": {
    },
  • "metadata": {}
}

Response samples

Content type
application/json
{
  • "answer": "string",
  • "thread_id": "1de43264-67cb-48af-89f9-e865c375bb84",
  • "question_answer_id": "string",
  • "is_uncertain": true,
  • "relevant_sources": [
    ]
}

Chat (Streamed)

You can use several endpoints to chat with your kapa.ai instances. These endpoints use streamed responses but are otherwise identical to the regular chat endpoints.

Custom chat streamed

In contrast to the standard chat API endpoints, the custom chat API grants the users full control over the prompting. The custom chat API has access to the same data sources as the regular chat endpoints. This enables users to develop applications with tailored behavior beyond the scope of standard Kapa functionality.

This endpoint is streamed.

Authorizations:
Bearer
path Parameters
project_id
required
string

The ID of the project.

Request Body schema: application/json
required
integration_id
string <uuid> (Integration id)

Optional integration id for the request. Use the ID of the integration that the user is interacting with. If not provided, the conversation may not be included in some statistics that group by integration.

required
Array of objects (Message)

List of messages to be used for the conversation.

retrieval_query
string (Retrieval query) non-empty

Optional query to use for retrieval instead of 'query' message

persist_answer
boolean (Persist answer)
Default: true

Set to False to not save answer in kapa for analytics.

use_retrieval
boolean (Use retrieval)
Default: true

Set to False to perform a pure LLM generation without retrieval.

label_internal_sources
boolean (Label internal sources)
Default: false

Set to True to mark internal sources in context.

generation_model
string (Generation model)
Default: "gpt-4-0613"
Enum: "gpt-4" "gpt-4-0613" "gpt-4-turbo-preview" "gpt-4-1106-preview" "gpt-4-0125-preview" "gpt-4o" "gpt-4o-2024-05-13" "gpt-4o-2024-08-06" "gpt-4o-mini" "gpt-4o-mini-2024-07-18" "gpt-3.5-turbo" "gpt-3.5-turbo-16k" "gpt-3.5-turbo-0125"

The LLM used for generation.

source_ids_include
Array of strings <uuid> [ items <uuid > ]

Optional list of source UUIDs for restricting retrieval.

response_format
string (Response format)
Value: "json_object"

Optional LLM output format.

redact_conversation
boolean (Redact conversation)
Default: false

Set to True to redact question and answer in analytics.

Responses

Request samples

Content type
application/json
{
  • "integration_id": "55d7337e-1d0a-49fc-9826-925ba40df035",
  • "messages": [
    ],
  • "retrieval_query": "string",
  • "persist_answer": true,
  • "use_retrieval": true,
  • "label_internal_sources": false,
  • "generation_model": "gpt-4",
  • "source_ids_include": [
    ],
  • "response_format": "json_object",
  • "redact_conversation": false
}

Response samples

Content type
application/json
[
  • {
    }
]

Chat streamed

Chat with your kapa.ai instance. This endpoint returns a streamed response. Calling this endpoint creates a new Thread object in the database and returns the answer to the user's query. A Thread object is a collection of messages in a conversation between the user and the AI model. To ask follow-up questions, use the thread_id returned in the response and call the streamed chat in thread endpoint.

Authorizations:
Bearer
path Parameters
project_id
required
string

The ID of the project.

Request Body schema: application/json
required
integration_id
string <uuid> (Integration id)

Optional integration id for the request. Use the ID of the integration that the user is interacting with. If not provided, the conversation may not be included in some statistics that group by integration.

query
required
string (Query) [ 1 .. 5000 ] characters

The query to ask the bot.

object (EndUserInfo)

Optional user data for end-user tracking. This includes user identifiers as well as metadata with additional information like the name and company of a user.

object (QueryInputMetadata)

Optional metadata for the query input. This includes information like the page URL from which the query was submitted.

Responses

Request samples

Content type
application/json
{
  • "integration_id": "55d7337e-1d0a-49fc-9826-925ba40df035",
  • "query": "string",
  • "user": {
    },
  • "metadata": {}
}

Response samples

Content type
application/json
[
  • {
    }
]

Chat in thread streamed

Query the Kapa.ai API with a question to continue the conversation in a Thread. This endpoint returns a streamed response.

Authorizations:
Bearer
path Parameters
thread_id
required
string

The ID of the thread.

Request Body schema: application/json
required
integration_id
string <uuid> (Integration id)

Optional integration id for the request. Use the ID of the integration that the user is interacting with. If not provided, the conversation may not be included in some statistics that group by integration.

query
required
string (Query) [ 1 .. 5000 ] characters

The query to ask the bot.

object (EndUserInfo)

Optional user data for end-user tracking. This includes user identifiers as well as metadata with additional information like the name and company of a user.

object (QueryInputMetadata)

Optional metadata for the query input. This includes information like the page URL from which the query was submitted.

Responses

Request samples

Content type
application/json
{
  • "integration_id": "55d7337e-1d0a-49fc-9826-925ba40df035",
  • "query": "string",
  • "user": {
    },
  • "metadata": {}
}

Response samples

Content type
application/json
[
  • {
    }
]

Search

Kapa also allows you to query your ingested data using a traditional search endpoint.

Feedback

These endpoints are used to provide feedback on the quality of the answers provided by the bot.

Upsert feedback

Update or insert feedback for a question_answer. Every time a user upvotes or downvotes a question_answer, this endpoint should be called. The user can also leave a comment with the feedback. This endpoint can be called multiple times for the same user and question_answer, and the feedback will be updated accordingly.

Authorizations:
Bearer
Request Body schema: application/json
required
object or null (FeedbackComment)

The comment of the feedback. This should only be provided if the user downvotes an answer.

user_identifier
required
string (User identifier) [ 1 .. 200 ] characters

The user identifier of the feedback. This should be based on some unique identifier for the user, like a browser fingerprint.

reaction
required
string (Reaction)
Enum: "upvote" "downvote"

The reaction of the feedback.

question_answer
required
string <uuid> (Question answer)

The question_answer that the feedback belongs to.

Responses

Request samples

Content type
application/json
{
  • "comment": {
    },
  • "user_identifier": "string",
  • "reaction": "upvote",
  • "question_answer": "484fbe4d-af7f-4b72-aecb-cde0e9e50cf3"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "comment": {
    },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "user_identifier": "string",
  • "reaction": "upvote",
  • "question_answer": "484fbe4d-af7f-4b72-aecb-cde0e9e50cf3"
}

Activity

These endpoints return data about the activity on the platform.

Activity

Returns aggregate as well as time series statistics for a project

Authorizations:
Bearer
path Parameters
project_id
required
string

The ID of the project.

query Parameters
start_date_time
string <date-time>

Start datetime for filtering in ISO 8601 format (e.g., 2020-01-01T00:00:00Z).

end_date_time
string <date-time>

End datetime for filtering in ISO 8601 format (e.g., 2020-01-01T23:59:59Z).

aggregation_period
required
string
Enum: "HOUR" "DAY" "WEEK" "MONTH" "YEAR"

Period for aggregating data.

integration_filter
string

Filter by specific integration ID.

Responses

Response samples

Content type
application/json
{
  • "time_series": [
    ],
  • "aggregate_statistics": {
    }
}

End Users

Endpoints for managing and exporting end user data.

List End Users

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

Authorizations:
Bearer
path Parameters
project_id
required
string

The ID of the project.

query Parameters
has_email
string

Filter users based on whether or not they have an email address.

search
string

Search query to filter end users by email, ID, or unique client ID

ordering
string

Which field to use when ordering the results.

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "display_id": "string",
  • "email": "string",
  • "unique_client_id": "string",
  • "question_answer_count": 0,
  • "latest_thread_id": "b64d73a3-c7f4-498d-9c2d-685530cd059e",
  • "latest_thread_first_question": "string",
  • "latest_activity_at": "2019-08-24T14:15:22Z",
  • "first_activity_at": "2019-08-24T14:15:22Z",
  • "company_name": "string"
}

Question Answers

Question answers represent the individual questions and generated answers in a Thread

List Question Answers

Retrieve a list of question and answer pairs for a specific project.

Authorizations:
Bearer
path Parameters
project_id
required
string

The UUID of the project.

query Parameters
ordering
string

Which field to use when ordering the results.

page
integer

A page number within the paginated result set.

page_size
integer

Number of results to return per page.

Responses

Response samples

Content type
application/json
[
  • {
    }
]