Knowledge base API

Tovie Data Agent provides an API to interact with the knowledge base. The API is intended for integrating the knowledge base with websites and applications, so that your customers and employees can refer to it with questions.

tip

The endpoints, request parameters, response formats, and errors returned are described in detail in the API specification.

API access

In the Tovie Data Agent interface, select your project and go to the API keys section. Click Create API key. You can set the key’s expiration date if necessary.

The API key provides access to the project’s knowledge base. The key must be specified in each API request in the HTTP header:

Authorization: Bearer <your_API_key>

Base URL

https://data-agent.tovie.ai/api/knowledge-hub

Endpoints

The API includes a set of endpoints for interacting with your knowledge:

• Get information on the current knowledge base project.
• Retrieve relevant chunks for user queries.
• Generate responses to user queries.
• Create and maintain user chats.

Project

Endpoint	Summary	Documentation
GET /info	Get project info.	Details

Queries

Process requests for chunk retrieving and response generation. Message history can be optionally provided in the request.

Endpoint	Summary	Documentation
POST /retrieve	Retrieve chunks.	Details
POST /query	Generate response (synchronous request).	Details
POST /async/query	Generate response (asynchronous request).	Details
GET /query/{queryId}	Get response generation status.	Details
POST /query/{queryId}/cancel	Cancel response generation.	Details

Chats and queries within chat

Create a chat, process requests for chunk retrieving and response generation within the chat. The chat message history is taken into account.

Endpoint	Summary	Documentation
POST /chat	Create chat.	Details
GET /chat/{chatId}	Get chat info.	Details
POST /chat/{chatId}/retrieve	Retrieve chunks.	Details
POST /chat/{chatId}/query	Generate response (synchronous request).	Details
POST /async/chat/{chatId}/query	Generate response (asynchronous request).	Details
GET /chat/{chatId}/query/{queryId}	Get response generation status.	Details
POST /chat/{chatId}/query/{queryId}/cancel	Cancel response generation.	Details

Use cases

Single query

You can specify query processing settings in the request. By default, the project settings are used. Additionally, you can pass message history in the request.

Request example:

curl \
--header 'Authorization: Bearer <your_API_key>' \
--header 'Content-Type: application/json' \
--data '{
    "query": "How to create my own knowledge base"
}' \
https://data-agent.tovie.ai/api/knowledge-hub/query

Response example

{
    "id": 20199,
    "request": "How to create my own knowledge base",
    "status": "FINISHED",
    "createdAt": "2024-11-18T12:01:56.166692Z",
    "response": "To create your own knowledge base using Tovie Data Agent, you can follow these steps:\n\n1. **Index the Knowledge Base**: Before using the knowledge base, it needs to be indexed. This involves preparing the data in formats such as PDF, DOCX, TXT, XML, JSON, YAML, MD, MDX, and HTML. If you store your knowledge in Confluence, you can set up integration to download data automatically. Start indexing the knowledge base on the downloaded data. Indexing may take a while, and you can track the progress in the UI.\n\n2. **Connect Channels**: Go to the *Channels* tab to add chat widgets, messengers, social networks, and other interfaces through which your customers and employees can ask questions to the knowledge base.\n\n3. **Test the Knowledge Base**: Go to the *Chat* tab to test your knowledge base. Try different queries to ensure that answers are correct and relevant.\n\n4. **Configure Settings**: You can influence the knowledge base operation by configuring settings such as indexing, search, and response generation. Access the settings section using the navigation panel on the left.\n\nFor more detailed guidance, you can refer to the Tovie Data Agent documentation on their website.",
    "updatedAt": "2024-11-18T12:02:04.481433Z",
    "comment": null
}

Chat

1. Create a chat.

   You can specify the chat name and query processing settings within the chat. By default, the project settings are used.

   Request example:

   curl \
   --header 'Authorization: Bearer <your_API_key>' \
   --header 'Content-Type: application/json' \
   --data '{}' \
   https://data-agent.tovie.ai/api/knowledge-hub/chat
   Response example

   {
       "id": 15045,
       "settings": {
           "pipeline": "semantic",
           "search": {
               "similarityTopK": 5,
               "candidateRadius": 0,
               "reranker": null,
               "fullTextSearch": null,
               "rephraseUserQuery": null,
               "segment": null
           },
           "llm": {
               "model": "GPT-4o",
               "contextWindow": 16000,
               "maxTokens": 1000,
               "temperature": 0.0,
               "topP": 1.0,
               "frequencyPenalty": 0.0,
               "presencePenalty": 0.0
           },
           "responseGeneration": {
               "prompt": "You are a English-speaking question answering system. You help users look for information in the Documentation.\nTry to answer their Question or find documents related to the Question according to the Documentation provided below.\nEach document starts from New document.\nFollow the rules:\n- (1) Firstly, find relevant documents related to the Question. It is possible that there are no related documents in the Documentation.\n- (2) Answer strictly according to the documents. Don't make things up.\n- (3) Question can be formulated as either an ordinary question with a question mark or words (when is the bank open?) or a search query (bank operating hours). You must deal with all types.\n- (4) If there is more than one answer to the Question, list all possible solutions separately.\n- (5) If there is not a direct Answer, but just information on the related topic, answer with it.\n- (6) If you can't find relevant documents, ask a user to reformulate the Question in your answer.\n- (7) Answer the Question in English.\n- (8) If you see a URL to an image in Documentation, use it in your response.\n\nYour task:\n______\n\nDOCUMENTATION: <{context_str}>;\nQUESTION: {query_str};\nANSWER:\n"
           }
       },
       "name": "2024-11-18-13-47-06"
   }

2. Submit an asynchronous request to the knowledge base.

   Specify the chat ID created in the previous step and the user request. Optionally, you can specify query processing settings. By default, the chat settings for request processing are used.

   Request example:

   curl \
   --header 'Authorization: Bearer <your_API_key>' \
   --header 'Content-Type: application/json' \
   --data '{
       "query": "How to create my own knowledge base"
   }' \
   https://data-agent.tovie.ai/api/knowledge-hub/async/chat/15045/query
   Response example

   {
       "id": 17748,
       "chatId": 15045,
       "request": "How to create my own knowledge base",
       "status": "READY_TO_PROCESS",
       "createdAt": "2024-11-18T13:59:17.642584567Z",
       "response": null,
       "updatedAt": "2024-11-18T13:59:17.642585762Z",
       "comment": null
   }

3. Track response readiness.

   In the request, specify the chat ID and the request ID obtained as a result of the asynchronous request. Optionally, you can specify the waitTimeSeconds parameter to use long polling. When the generation is complete, the status FINISHED is returned.

   Request example:

   curl \
   --header 'Authorization: Bearer <your_API_key>' \
   https://data-agent.tovie.ai/api/knowledge-hub/chat/15045/query/17748
   Response example

   {
       "id": 17748,
       "chatId": 15045,
       "request": "How to create my own knowledge base",
       "status": "FINISHED",
       "createdAt": "2024-11-18T13:59:17.642585Z",
       "response": "To create your own knowledge base using Tovie Data Agent, follow these steps:\n\n1. **Indexing the Knowledge Base:**\n   - Before using the knowledge base, it needs to be indexed. This involves preparing the uploaded data, chunking it into small fragments, and vectorising these fragments into vectors. You can start indexing by clicking *Index*. Indexing may take some time depending on the data volume, and you can track the progress in the UI.\n\n2. **Testing the Knowledge Base:**\n   - Once your knowledge base is indexed, you can test it to ensure it operates properly and answers potential user questions correctly. Go to the *Chat* section, ask your questions, and see how the knowledge base responds.\n\n3. **Tuning Settings:**\n   - You can tune settings of search and response generation directly in your chat window. Make sure to apply them to the entire knowledge base.\n\n4. **Connecting Channels:**\n   - To add chat widgets, messengers, social networks, and other interfaces through which your customers and employees can ask questions to the knowledge base, go to the *Channels* tab.\n\nFor more detailed guidance, you can refer to the documentation links provided in the Tovie Data Agent’s resources.",
       "updatedAt": "2024-11-18T13:59:26.181718Z",
       "comment": null
   }