Tovie Data Agent 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

Tovie Data Agent provides two types of API keys.

• Administrative: grants permissions to add and remove projects, and to create and revoke project API keys.
• Project: grants access to the project’s knowledge base, enabling queries and management of sources and integrations.

To create an API key:

1. Go to Account → API keys.
2. Click Create API key.
3. Select the key type: project or administrative.
4. For a project key, select a project.
5. Enter a name for the key.
6. Specify the expiry date if needed.

The key must be included in every 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:

• Creating, updating, and deleting projects.
• Creating and revoking project API keys.
• Getting knowledge base project information, including a list of available LLMs.
• Adding, updating, and deleting sources.
• Adding and removing integrations for downloading data from external systems.
• Starting and stopping indexing of knowledge base.
• Retrieving relevant chunks for user queries.
• Generating responses to user queries.
• Creating and maintaining user chats.

Projects

Endpoint	Summary	Key*	Documentation
POST /projects	Create project.	A	Details
GET /projects	Get list of projects.	A	Details
PUT /projects/{projectId}	Update project.	A	Details
DELETE /projects/{projectId}	Delete project.	A	Details
GET /info	Get project info.	P	Details

• A means that an administrative API key is required to call the method; P means a project key is required.

API keys

An administrative API key is required to call these methods.

Endpoint	Summary	Documentation
POST /projects/{projectId}/api-keys:	Create project API key.	Details
GET /projects/{projectId}/api-keys	Get list of project API keys.	Details
POST /projects/{projectId}/api-keys/{apiKeyId}/revoke	Revoke project API key.	Details

Sources

A project API key is required to call these methods.

Endpoint	Summary	Documentation
GET /sources	Get list of sources.	Details
POST /sources/links	Add source via link.	Details
PUT /sources/links	Update source via link.	Details
POST /sources/texts	Add source from text.	Details
PUT /sources/texts	Update source from text.	Details
POST /sources/files	Add source from file.	Details
PUT /sources/files	Update source from file.	Details
GET /sources/{sourceId}	Get information about source.	Details
GET /sources/{sourceId}/download	Download source.	Details
DELETE /sources/{sourceId}	Delete source.	Details

Integrations

A project API key is required to call these methods.

Endpoint	Summary	Documentation
GET /integrations	Get list of integrations.	Details
POST /integrations	Create integration.	Details
GET /integrations/{integrationId}	Get information about integration.	Details
DELETE /integrations/{integrationId}	Delete integration.	Details

Segments

Endpoint	Summary	Documentation
GET /segments	Get list of segments.	Details
POST /segments/rename	Rename segment.	Details
POST /sources/segments	Assign segments to sources.	Details
DELETE /sources/segments	Unassign segments from sources.	Details

Indexing

A project API key is required to call these methods.

Endpoint	Summary	Documentation
GET /indexing/start	Start indexing of knowledge base.	Details
GET /indexing/stop	Stop indexing of knowledge base.	Details

Single queries

Process requests for chunk retrieval and response generation. You can optionally include message history in the request.

A project API key is required to call these methods.

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.

A project API key is required to call these methods.

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. You can also pass the message history in your request for more context.

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 the knowledge base can be used, it needs to be indexed. This involves preparing your 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 an integration to download data automatically. Start indexing the knowledge base using the downloaded data. Indexing may take a while, and you can track its progress in the UI.\n\n2. **Connect Channels**: Go to the *Channels* section to add chat widgets, messengers, social networks, and other interfaces through which your customers and employees can ask the knowledge base questions.\n\n3. **Test the Knowledge Base**: Go to the *Test chat* section to test it. Try different queries to ensure the answers are correct and relevant.\n\n4. **Configure Settings**: You can fine-tune the knowledge base’s behavior by configuring settings for indexing, search, and response generation. Access the settings section using the navigation panel on the left.\n\nFor more detailed guidance, refer to the Tovie Data Agent documentation.",
    "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 query. 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 in Tovie Data Agent, follow these steps:\n\n1. **Registration**: Register on Tovie Data Agent. If you already have an account with other Tovie AI products, you can use it to log in to the platform.\n\n2. **Project creation and data uploading**: Create your first project and upload data to Tovie Data Agent. Supported file formats are PDF, DOCX, TXT, XML, JSON, YAML, MD, MDX, HTML, CSV. If you're using Confluence for knowledge storage, set up an integration with Tovie Data Agent for automatic data uploads.\n\n3. **Indexing the knowledge base**: Initiate the knowledge base indexing process on the uploaded data. Indexing might take some time, monitor the progress in the product interface.\n\n4. **Testing and usage**: After indexing, test the knowledge base to ensure it functions correctly. Navigate to the 'Test chat' section and ask questions to verify how the knowledge base responds.\n\nFollowing these steps will help you create and configure your own knowledge base on Tovie Data Agent.",  
       "updatedAt": "2024-11-18T13:59:26.181718Z",
       "comment": null
   }