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:
path Parameters
id required | string The ID of the project. |
Responses
Response samples
- 200
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "team": "95527efb-6695-4aae-916e-c9869b1fb2bd",
- "project_name": "string"
}
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:
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
- 200
{- "count": 0,
- "results": [
- {
- "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": {
- "entities": [
- "PHONE_NUMBER"
]
}
}
]
}
Retrieve a source
Retrieve a source for a project.
Authorizations:
path Parameters
id required | string <uuid> A UUID string identifying this [-] Source. |
project_id required | string The ID of the project. |
Responses
Response samples
- 200
{- "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": {
- "entities": [
- "PHONE_NUMBER"
]
}
}
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:
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" "API" "DASHBOARD_CHAT" Filter by integration type(s). Can be specified multiple times for multiple types. |
Responses
Response samples
- 200
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "project": "9ec8a81a-31b2-4a83-bcd8-cef9150932d2",
- "name": "string",
- "description": "string",
- "integration_type": "SLACK_CHANNEL",
- "is_setup_complete": true,
- "is_enabled": true,
- "updated_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z"
}
]
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:
path Parameters
project_id required | string The ID of the project. |
Request Body schema: application/json
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. |
Responses
Request samples
- Payload
{- "integration_id": "55d7337e-1d0a-49fc-9826-925ba40df035",
- "query": "string",
- "user": {
- "email": "string",
- "unique_client_id": "string",
- "fingerprint_id": "string",
- "slack_id": "string",
- "discord_id": "string",
- "metadata": {
- "store_ip": false
}
}
}
Response samples
- 200
{- "answer": "string",
- "thread_id": "string",
- "question_answer_id": "string",
- "is_uncertain": true,
- "relevant_sources": [
- {
- "source_url": "string",
- "title": "string",
- "contains_internal_data": true
}
]
}
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:
path Parameters
project_id required | string The ID of the project. |
Request Body schema: application/json
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 |
use_retrieval | boolean (Use retrieval) Default: true Set to |
label_internal_sources | boolean (Label internal sources) Default: false Set to |
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> 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 |
Responses
Request samples
- Payload
{- "integration_id": "55d7337e-1d0a-49fc-9826-925ba40df035",
- "messages": [
- {
- "role": "system",
- "content": "string"
}
], - "retrieval_query": "string",
- "persist_answer": true,
- "use_retrieval": true,
- "label_internal_sources": false,
- "generation_model": "gpt-4",
- "source_ids_include": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "response_format": "json_object",
- "redact_conversation": false
}
Response samples
- 200
{- "answer": "string",
- "thread_id": "1de43264-67cb-48af-89f9-e865c375bb84",
- "question_answer_id": "7d960536-abce-4add-bdc0-29c0f5637b82",
- "messages": [
- {
- "role": "system",
- "content": "string"
}
], - "relevant_sources": [
- {
- "source_url": "string",
- "title": "string",
- "contains_internal_data": true,
- "content": "string",
- "source_name": "string"
}
]
}
Chat in thread
Query the Kapa.ai API with a question to continue the conversation in an existing Thread
.
Authorizations:
path Parameters
thread_id required | string The ID of the thread. |
Request Body schema: application/json
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. |
Responses
Request samples
- Payload
{- "integration_id": "55d7337e-1d0a-49fc-9826-925ba40df035",
- "query": "string",
- "user": {
- "email": "string",
- "unique_client_id": "string",
- "fingerprint_id": "string",
- "slack_id": "string",
- "discord_id": "string",
- "metadata": {
- "store_ip": false
}
}
}
Response samples
- 200
{- "answer": "string",
- "thread_id": "1de43264-67cb-48af-89f9-e865c375bb84",
- "question_answer_id": "string",
- "is_uncertain": true,
- "relevant_sources": [
- {
- "source_url": "string",
- "title": "string",
- "contains_internal_data": true
}
]
}
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:
path Parameters
project_id required | string The ID of the project. |
Request Body schema: application/json
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 |
use_retrieval | boolean (Use retrieval) Default: true Set to |
label_internal_sources | boolean (Label internal sources) Default: false Set to |
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> 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 |
Responses
Request samples
- Payload
{- "integration_id": "55d7337e-1d0a-49fc-9826-925ba40df035",
- "messages": [
- {
- "role": "system",
- "content": "string"
}
], - "retrieval_query": "string",
- "persist_answer": true,
- "use_retrieval": true,
- "label_internal_sources": false,
- "generation_model": "gpt-4",
- "source_ids_include": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "response_format": "json_object",
- "redact_conversation": false
}
Response samples
- 200
[- {
- "chunk": {
- "type": "partial_answer",
- "content": {
- "text": "string"
}, - "stream_end": true
}
}
]
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:
path Parameters
project_id required | string The ID of the project. |
Request Body schema: application/json
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. |
Responses
Request samples
- Payload
{- "integration_id": "55d7337e-1d0a-49fc-9826-925ba40df035",
- "query": "string",
- "user": {
- "email": "string",
- "unique_client_id": "string",
- "fingerprint_id": "string",
- "slack_id": "string",
- "discord_id": "string",
- "metadata": {
- "store_ip": false
}
}
}
Response samples
- 200
[- {
- "chunk": {
- "type": "partial_answer",
- "content": {
- "relevant_sources": [
]
}, - "stream_end": true
}
}
]
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:
path Parameters
thread_id required | string The ID of the thread. |
Request Body schema: application/json
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. |
Responses
Request samples
- Payload
{- "integration_id": "55d7337e-1d0a-49fc-9826-925ba40df035",
- "query": "string",
- "user": {
- "email": "string",
- "unique_client_id": "string",
- "fingerprint_id": "string",
- "slack_id": "string",
- "discord_id": "string",
- "metadata": {
- "store_ip": false
}
}
}
Response samples
- 200
[- {
- "chunk": {
- "type": "partial_answer",
- "content": {
- "relevant_sources": [
]
}, - "stream_end": true
}
}
]
Search
Query the Kapa.ai API with a search query and return the answer.
Authorizations:
path Parameters
project_id required | string The ID of the project. |
Request Body schema: application/json
query required | string (Query) non-empty The search query. |
num_results | integer (Num results) Default: 10 The number of results to return. |
include_source_names | Array of strings[ items non-empty ] The source types to include in the search. This field is experimental and may be changed or removed in the future. |
Responses
Request samples
- Payload
{- "query": "string",
- "num_results": 10,
- "include_source_names": [
- "string"
]
}
Response samples
- 200
[- {
- "content": "string",
- "source_url": "string",
- "title": "string",
- "source_type": "string"
}
]
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:
Request Body schema: application/json
object (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
- Payload
{- "comment": {
- "issue": "string",
- "incorrect": true,
- "irrelevant": true,
- "unaddressed": true
}, - "user_identifier": "string",
- "reaction": "upvote",
- "question_answer": "484fbe4d-af7f-4b72-aecb-cde0e9e50cf3"
}
Response samples
- 201
{- "id": 0,
- "comment": {
- "issue": "string",
- "incorrect": true,
- "irrelevant": true,
- "unaddressed": true
}, - "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
Returns aggregate as well as time series statistics for a project
Authorizations:
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. |
Responses
Response samples
- 200
{- "time_series": [
- {
- "period": "2019-08-24T14:15:22Z",
- "total_count": 0,
- "total_uncertain_count": 0,
- "count_by_integration": [
- {
- "integration_type": "SLACK",
- "count": 0,
- "description": "string",
- "id": "string"
}
]
}
], - "aggregate_statistics": {
- "total_questions": 0,
- "total_upvotes": 0,
- "total_downvotes": 0,
- "total_questions_uncertain": 0,
- "total_questions_uncertain_or_downvoted": 0,
- "total_unique_users": 0
}
}
Questions
Returns a list of questions answered through the sources of a project.
Authorizations:
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. |
start_date_time | string <date-time> Start date for filtering, in ISO 8601 format (e.g., 2023-01-01T00:00:00Z). |
end_date_time | string <date-time> End date for filtering, in ISO 8601 format (e.g., 2023-01-31T23:59:59Z). |
url_path | string Specific URL path to filter the results by. |
Responses
Response samples
- 200
{- "count": 0,
- "results": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "question": "string",
- "answer": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "is_uncertain": true,
- "total_upvotes": 0,
- "total_downvotes": 0,
- "thread_id": "string"
}
]
}
Statistics
Returns a list of source used by kapa to answer questions together with a count of questions answered by them.
Authorizations:
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. |
start_date | string <date-time> Start date for the data retrieval period in ISO 8601 format (e.g., 2020-01-01T00:00:00Z). |
end_date | string <date-time> End date for the data retrieval period in ISO 8601 format (e.g., 2020-01-02T23:59:59Z). |
url_path | string Specific URL path to filter the statistics by. All non-leaf |
Responses
Response samples
- 200
{- "count": 0,
- "results": [
- {
- "is_leaf": true,
- "node_url": "string",
- "count": 0,
- "percentage_of_total": "string"
}
]
}
Threads are the conversations that the bot has with users. Each thread can have multiple question/answer pairs.
Threads
Returns all threads for a project that match the provided filters / search criteria.
Authorizations:
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. |
reaction_filter | string Enum: "UPVOTE" "DOWNVOTE" Filter by reaction type. |
confidence_filter | string Enum: "UNCERTAIN" "CERTAIN" Filter by confidence level. |
status_tag_filter | string <uuid> Filter by status tag id. |
start_date | string <date-time> Start date for filtering threads (YYYY-MM-DDTHH:MM:SSZ). |
end_date | string <date-time> End date for filtering threads (YYYY-MM-DDTHH:MM:SSZ). |
search_text | string Text to search within threads. |
integration_filter | string Filter by specific integration. |
sort_by_date | string Enum: "asc" "desc" Sort the results in the specified order by date. If not specified results are ordered by date in descending order. |
Responses
Response samples
- 200
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "integration": "string",
- "total_upvotes": 0,
- "total_downvotes": 0,
- "total_comments": 0,
- "total_thread_comments": 0,
- "total_number_of_question_answers": 0,
- "created_at": "2019-08-24T14:15:22Z",
- "initial_question": "string",
- "is_uncertain": true,
- "status_tag": "string",
- "status_tag_id": "bcc09619-3a7b-4037-9d98-031f60c9ecfd"
}
]
Export Threads
Generates a CSV file (max 100k rows) that includes all threads and their associated question/answer's for a project.
Authorizations:
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. |
reaction_filter | string Enum: "UPVOTE" "DOWNVOTE" Filter by reaction type. |
confidence_filter | string Enum: "UNCERTAIN" "CERTAIN" Filter by confidence level. |
status_tag_filter | string <uuid> Filter by status tag id. |
start_date | string <date-time> Start date for filtering threads (YYYY-MM-DDTHH:MM:SSZ). |
end_date | string <date-time> End date for filtering threads (YYYY-MM-DDTHH:MM:SSZ). |
search_text | string Text to search within threads. |
integration_filter | string Filter by specific integration. |
sort_by_date | string Enum: "asc" "desc" Sort the results in the specified order by date. If not specified results are ordered by date in descending order. |
Responses
Question Answers
Returns all question answers for a single thread
Authorizations:
path Parameters
id required | string The ID of the thread. |
Responses
Response samples
- 200
[- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "question": "string",
- "answer": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "is_uncertain": true,
- "relevant_sources": "string",
- "total_upvotes": 0,
- "total_downvotes": 0,
- "total_comments": 0,
- "feedback": "string"
}
]