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" "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.

Responses

Request samples

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

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.

Responses

Request samples

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

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.

Responses

Request samples

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

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.

Responses

Request samples

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

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 (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.

Responses

Response samples

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

Source Analytics

These endpoints help you understand which sources are being used the most.

Questions

Returns a list of questions answered through the sources of 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.

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

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

Statistics

Returns a list of source used by kapa to answer questions together with a count of questions answered by them.

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.

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 node_url fields from the response can be used to go deeper into the tree.

Responses

Response samples

Content type
application/json
{}

Threads

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:
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.

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

Content type
application/json
[
  • {
    }
]

Export Threads

Generates a CSV file (max 100k rows) that includes all threads and their associated question/answer's 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.

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:
Bearer
path Parameters
id
required
string

The ID of the thread.

Responses

Response samples

Content type
application/json
[
  • {
    }
]