Skip to main content

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​

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

  • 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.
  • Retrieving relevant chunks for user queries.
  • Generating responses to user queries.
  • Creating and maintaining user chats.

Project​

EndpointSummaryDocumentation
GET /infoGet project info.Details

Sources​

EndpointSummaryDocumentation
GET /sourcesRetrieve list of sources.Details
POST /sources/linksAdd source via link.Details
PUT /sources/linksUpdate source via link.Details
POST /sources/textsAdd source from text.Details
PUT /sources/textsUpdate source from text.Details
POST /sources/filesAdd source from file.Details
PUT /sources/filesUpdate source from file.Details
GET /sources/{sourceId}Get information about source.Details
GET /sources/{sourceId}/downloadDownload source.Details
DELETE /sources/{sourceId}Delete source.Details

Integrations​

EndpointSummaryDocumentation
GET /integrationsGet list of integrations.Details
POST /integrationsAdd integration.Details
GET /integrations/{integrationId}Get information about integration.Details
DELETE /integrations/{integrationId}Delete integration.More details

Single queries​

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

EndpointSummaryDocumentation
POST /retrieveRetrieve chunks.Details
POST /queryGenerate response (synchronous request).Details
POST /async/queryGenerate response (asynchronous request).Details
GET /query/{queryId}Get response generation status.Details
POST /query/{queryId}/cancelCancel 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.

EndpointSummaryDocumentation
POST /chatCreate chat.Details
GET /chat/{chatId}Get chat info.Details
POST /chat/{chatId}/retrieveRetrieve chunks.Details
POST /chat/{chatId}/queryGenerate response (synchronous request).Details
POST /async/chat/{chatId}/queryGenerate response (asynchronous request).Details
GET /chat/{chatId}/query/{queryId}Get response generation status.Details
POST /chat/{chatId}/query/{queryId}/cancelCancel 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* section 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* section 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 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. 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 'Dialogue' 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
    }