Skip to main content
API docs by Redocly

Tovie Data Agent public API (1.0.0)

Download OpenAPI specification:Download

ProjectsPublic

Project operations.

Get list of projects

Get the list of projects in the account. An administrative API key is required for the operation.

Authorizations:
bearerAuth
query Parameters
pageNum
integer <int32> >= 0
Default: 0

Page number for pagination, starting from 0.

pageSize
integer <int32> [ 1 .. 100 ]
Default: 20

Page size.

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "paging": {
    }
}

Create project

Create a new knowledge base project. An administrative API key is required for the operation.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Project name.

Responses

Request samples

Content type
application/json
{
  • "name": "Information service"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "status": "CREATED",
  • "resources": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Get knowledge base project info

Get information on the knowledge base project. An API key of the project is required for the operation.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "status": "CREATED",
  • "resources": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update project

Update the knowledge base project. An administrative API key is required for the operation.

Authorizations:
bearerAuth
path Parameters
projectId
required
integer <int64> (LongId)

Knowledge base project identifier.

Request Body schema: application/json
required
name
required
string

Project name.

Responses

Request samples

Content type
application/json
{
  • "name": "Information service"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "status": "CREATED",
  • "resources": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Delete project

Delete the knowledge base project. An administrative API key is required for the operation.

Authorizations:
bearerAuth
path Parameters
projectId
required
integer <int64> (LongId)

Knowledge base project identifier.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "description": "string"
}

QueriesPublic

Independent requests for chunk retrieval or response generation. The message history can be optionally passed within the request.

Retrieve chunks

Retrieve chunks relevant to the user’s query from the knowledge base.

Authorizations:
bearerAuth
Request Body schema: application/json
required
query
required
string

Text of the user’s query.

Array of objects (HistoryRecord)

Dialogue history. Entries are displayed in reverse chronological order (from latest to earliest).

object (RetrievingSettings)

Chunk search settings.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "history": [
    ],
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "chunks": [
    ]
}

Generate response

Synchronous request to generate a response to the user’s query.

Please note that request processing may take a significant amount of time. Ensure that the connection timeout set in your HTTP client is more than 1 minute.

Authorizations:
bearerAuth
Request Body schema: application/json
required
query
required
string

Text of the user’s query.

Array of objects (HistoryRecord)

Dialogue history. Entries are displayed in reverse chronological order (from latest to earliest).

object (RagSettings)

Query processing settings.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "history": [
    ],
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "request": "string",
  • "response": "string",
  • "status": "READY_TO_PROCESS",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "comment": "string",
  • "relevantSources": [
    ]
}

Generate response (asynchronous request)

Asynchronous request to generate a response to the user’s query.

The result can be obtained via GET /api/knowledge-hub/query/{queryId} endpoint, where queryId is the request identifier received in the current response.

Authorizations:
bearerAuth
Request Body schema: application/json
required
query
required
string

Text of the user’s query.

Array of objects (HistoryRecord)

Dialogue history. Entries are displayed in reverse chronological order (from latest to earliest).

object (RagSettings)

Query processing settings.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "history": [
    ],
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "request": "string",
  • "response": "string",
  • "status": "READY_TO_PROCESS",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "comment": "string",
  • "relevantSources": [
    ]
}

Processing status of the response generation request

Get the current processing status of the response generation request. Long polling is used if the waitTimeSeconds parameter is specified.

Authorizations:
bearerAuth
path Parameters
queryId
required
integer <int64> (LongId)

Identifier of the response generation request.

query Parameters
waitTimeSeconds
integer <int32> [ 0 .. 30 ]
Default: 3

HTTP request timeout. Used in long polling.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "request": "string",
  • "response": "string",
  • "status": "READY_TO_PROCESS",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "comment": "string",
  • "relevantSources": [
    ]
}

Cancel response generation request

Authorizations:
bearerAuth
path Parameters
queryId
required
integer <int64> (LongId)

Identifier of the response generation request.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "request": "string",
  • "response": "string",
  • "status": "READY_TO_PROCESS",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "comment": "string",
  • "relevantSources": [
    ]
}

ChatsPublic

Requests for chunk retrieval and response generation within a user chat.

Create chat

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
string

Name of the user’s chat.

object (RagSettings)

Query processing settings.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "settings": {
    }
}

Get chat info

Authorizations:
bearerAuth
path Parameters
chatId
required
integer <int64> (LongId)

Identifier of the chat in the knowledge base project.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "settings": {
    }
}

Retrieve chunks

Retrieve chunks from the knowledge base that are relevant to the user’s query within the chat.

Authorizations:
bearerAuth
path Parameters
chatId
required
integer <int64> (LongId)

Identifier of the chat in the knowledge base project.

Request Body schema: application/json
required
query
required
string

Text of the user’s query.

object (RetrievingSettings)

Chunk search settings.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "chunks": [
    ]
}

Generate response

Synchronous request to generate a response to the user’s query. The chat message history is taken into account.

Please note that request processing may take a significant amount of time. Ensure that the connection timeout set in your HTTP client is more than 1 minute.

Authorizations:
bearerAuth
path Parameters
chatId
required
integer <int64> (LongId)

Identifier of the chat in the knowledge base project.

Request Body schema: application/json
required
query
required
string

Text of the user’s query.

object (RagSettings)

Query processing settings.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "chatId": 0,
  • "request": "string",
  • "response": "string",
  • "status": "READY_TO_PROCESS",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "comment": "string",
  • "relevantSources": [
    ]
}

Generate response (asynchronous request)

Asynchronous request to generate a response to the user’s query. The chat message history is taken into account.

The result can be obtained via GET /api/knowledge-hub/chat/{chatId}/query/{queryId} endpoint, where queryId is the request identifier received in the current response.

Authorizations:
bearerAuth
path Parameters
chatId
required
integer <int64> (LongId)

Identifier of the chat in the knowledge base project.

Request Body schema: application/json
required
query
required
string

Text of the user’s query.

object (RagSettings)

Query processing settings.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "chatId": 0,
  • "request": "string",
  • "response": "string",
  • "status": "READY_TO_PROCESS",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "comment": "string",
  • "relevantSources": [
    ]
}

Processing status of the response generation request

Get the current processing status of the response generation request within a user chat. Long polling is used if the waitTimeSeconds parameter is specified.

Authorizations:
bearerAuth
path Parameters
chatId
required
integer <int64> (LongId)

Identifier of the chat in the knowledge base project.

queryId
required
integer <int64> (LongId)

Identifier of the response generation request.

query Parameters
waitTimeSeconds
integer <int32> [ 0 .. 30 ]
Default: 3

HTTP request timeout. Used in long polling.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "chatId": 0,
  • "request": "string",
  • "response": "string",
  • "status": "READY_TO_PROCESS",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "comment": "string",
  • "relevantSources": [
    ]
}

Cancel response generation request within a user chat

Authorizations:
bearerAuth
path Parameters
chatId
required
integer <int64> (LongId)

Identifier of the chat in the knowledge base project.

queryId
required
integer <int64> (LongId)

Identifier of the response generation request.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "chatId": 0,
  • "request": "string",
  • "response": "string",
  • "status": "READY_TO_PROCESS",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "comment": "string",
  • "relevantSources": [
    ]
}

SourcesPublic

Sources operations.

Get list of sources

Get the list of knowledge base sources.

Authorizations:
bearerAuth
query Parameters
createDateFrom
string <date>

Select sources added on or after the specified date.

createDateTo
string <date>

Select sources added on or before the specified date.

sourceStatus
string

Select sources with the specified indexing status. Acceptable statuses:

  • READY_TO_INGEST: ready for indexing.
  • PROCESSING: in progress.
  • INGESTED: indexed.
  • FAILED_TO_INGEST: indexing error.

Responses

Response samples

Content type
application/json
{
  • "sources": [
    ]
}

Add from text

Add the provided text as a source to the knowledge base. Indexing begins automatically after the source is added.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
string

Name of the source. It must include the file extension (for example, txt, md, or json) and be unique within the project. If not specified, it is automatically generated.

text
required
string

Text of the source. The maximum size is specified in the file requirements.

segment
string
Deprecated

Knowledge base segment (tag). This parameter is deprecated. Use segments instead.

segments
Array of strings

Knowledge base segments (tags). The source will be available when searching within these segments.

Each segment name must be 1 to 100 characters long and must not contain commas.

Responses

Request samples

Content type
application/json
{
  • "name": "filename.txt",
  • "text": "string",
  • "segment": "string",
  • "segments": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "segments": [
    ],
  • "status": "string",
  • "lastError": "string",
  • "version": "string",
  • "sizeBytes": 0,
  • "sizeChars": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "type": "FILE"
}

Update with text

Replace the source with the text provided. Indexing begins automatically after the source is updated.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
string

Name of the source. If no source with this name exists, an error is returned.

text
required
string

Text of the source. The maximum size is specified in the file requirements.

segment
string
Deprecated

Knowledge base segment (tag). This parameter is deprecated. Use segments instead.

segments
Array of strings

Knowledge base segments (tags). The source will be available when searching within these segments.

Each segment name must be 1 to 100 characters long and must not contain commas.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "text": "string",
  • "segment": "string",
  • "segments": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "segments": [
    ],
  • "status": "string",
  • "lastError": "string",
  • "version": "string",
  • "sizeBytes": 0,
  • "sizeChars": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "type": "FILE"
}

Add from file

Add the provided file as a source to the knowledge base. Indexing begins automatically after the source is added.

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
required
file
required
string <binary>

File to upload. See the file requirements.

name
string

Name of the source. It must include the file extension and be unique within the project. If not specified, it is automatically generated.

segment
string
Deprecated

Knowledge base segment (tag). This parameter is deprecated. Use segments instead.

segments
Array of strings

Knowledge base segments (tags). The source will be available when searching within these segments.

Each segment name must be 1 to 100 characters long and must not contain commas.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "segments": [
    ],
  • "status": "string",
  • "lastError": "string",
  • "version": "string",
  • "sizeBytes": 0,
  • "sizeChars": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "type": "FILE"
}

Update with file

Replace the source with the file provided. Indexing begins automatically after the source is updated.

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
required
file
required
string <binary>

File to upload. See the file requirements.

name
string

Name of the source. If no source with this name exists, an error is returned.

segment
string
Deprecated

Knowledge base segment (tag). This parameter is deprecated. Use segments instead.

segments
Array of strings

Knowledge base segments (tags). The source will be available when searching within these segments.

Each segment name must be 1 to 100 characters long and must not contain commas.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "segments": [
    ],
  • "status": "string",
  • "lastError": "string",
  • "version": "string",
  • "sizeBytes": 0,
  • "sizeChars": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "type": "FILE"
}

Get source info

Get information about the knowledge base source.

Authorizations:
bearerAuth
path Parameters
sourceId
required
integer <int64> (LongId)

Identifier of the source in the knowledge base project.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "segments": [
    ],
  • "status": "string",
  • "lastError": "string",
  • "version": "string",
  • "sizeBytes": 0,
  • "sizeChars": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "type": "FILE"
}

Delete source

Delete the source from the knowledge base.

Authorizations:
bearerAuth
path Parameters
sourceId
required
integer <int64> (LongId)

Identifier of the source in the knowledge base project.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "description": "string"
}

Export source

Export the source file from the knowledge base.

Authorizations:
bearerAuth
path Parameters
sourceId
required
integer <int64> (LongId)

Identifier of the source in the knowledge base project.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "description": "string"
}

IntegrationsPublic

Integrations operations.

Create integration

Add an integration to the knowledge base. Indexing begins automatically after data is downloaded, both when creating the integration or during automatic synchronisation, if enabled.

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string

Name of the integration.

autoSync
boolean

Enable automatic data synchronisation

downloadAttachmentFiles
boolean

Enable download attached files in acceptable formats, see the file requirements. This setting does not affect downloading images: they are downloaded anyway.

syncIntervalMinutes
integer

Update interval in minutes. The minimum value is 30.

required
object (IntegrationSettings)

Integration settings.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "autoSync": true,
  • "downloadAttachmentFiles": true,
  • "syncIntervalMinutes": 0,
  • "settings": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "autoSync": true,
  • "syncIntervalMinutes": 0,
  • "settings": {
    },
  • "status": "ACTIVE",
  • "lastError": "string"
}

Get list of integrations

Get the list of knowledge base integrations.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "integrations": [
    ]
}

Get integration info

Get information about the integration.

Authorizations:
bearerAuth
path Parameters
integrationId
required
integer <int64> (LongId)

Identifier of the integration.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "autoSync": true,
  • "syncIntervalMinutes": 0,
  • "settings": {
    },
  • "status": "ACTIVE",
  • "lastError": "string"
}

Delete integration

Remove the integration from the knowledge base.

Authorizations:
bearerAuth
path Parameters
integrationId
required
integer <int64> (LongId)

Identifier of the integration.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "description": "string"
}

SegmentsPublic

Knowledge base segments (tags) operations.

Get list of segments

Get the list of knowledge base segments (tags).

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "segments": [
    ]
}

Rename segment

Change the name of a segment (tag) across all assigned sources.

Authorizations:
bearerAuth
Request Body schema: application/json
required
oldName
required
string

Current segment name.

newName
required
string

New segment name. Must be 1 to 100 characters long. Commas are not allowed.

Responses

Request samples

Content type
application/json
{
  • "oldName": "Law",
  • "newName": "Legal documents"
}

Response samples

Content type
application/json
{
  • "updatedFileIds": [
    ]
}

Assign segments to sources

Add the specified segments (tags) to the list of segments assigned to each source.

Authorizations:
bearerAuth
Request Body schema: application/json
required
sourceIds
required
Array of integers <int64> (LongId) [ items <int64 > ]

Identifiers of the sources. If omitted, changes will be applied to all sources in the knowledge base.

segments
required
Array of strings

Segments to assign to the sources. Each segment name must be 1 to 100 characters long and must not contain commas.

Responses

Request samples

Content type
application/json
{
  • "sourceIds": [
    ],
  • "segments": [
    ]
}

Response samples

Content type
application/json
{
  • "updatedFileIds": [
    ]
}

Unassign segments from sources

Remove the specified segments (tags) from the list of segments assigned to each source. If a segment to be removed is not assigned to a given source, it will be skipped.

Authorizations:
bearerAuth
Request Body schema: application/json
required
sourceIds
required
Array of integers <int64> (LongId) [ items <int64 > ]

Identifiers of the sources.

segments
required
Array of strings

Segments to unassign from the sources.

Responses

Request samples

Content type
application/json
{
  • "sourceIds": [
    ],
  • "segments": [
    ]
}

Response samples

Content type
application/json
{
  • "updatedFileIds": [
    ]
}

IndexingPublic

Indexing control.

Start indexing of knowledge base

Start indexing of sources that haven’t been indexed since upload or whose indexing previously failed.

Authorizations:
bearerAuth

Responses

Stop indexing of knowledge base

Terminate the ongoing indexing.

Authorizations:
bearerAuth

Responses

ApiKeysPublic

Operations on project API keys.

Create API key

Create a new API key for the knowledge base project. An administrative API key is required for the operation.

Authorizations:
bearerAuth
path Parameters
projectId
required
integer <int64> (LongId)

Knowledge base project identifier.

Request Body schema: application/json
required
name
required
string

API key name.

expiredAt
string <date-time>

API key expiry date and time. If not specified, a permanent key will be created.

Responses

Request samples

Content type
application/json
{
  • "name": "For website and apps",
  • "expiredAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "projectId": 0,
  • "name": "string",
  • "key": "string",
  • "status": "string",
  • "ownerLogin": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "expiredAt": "2019-08-24T14:15:22Z",
  • "lastUsedAt": "2019-08-24T14:15:22Z"
}

Get list of API keys

Get the list of API keys for the knowledge base project. An administrative API key is required for the operation.

Authorizations:
bearerAuth
path Parameters
projectId
required
integer <int64> (LongId)

Knowledge base project identifier.

query Parameters
pageNum
integer <int32> >= 0
Default: 0

Page number for pagination, starting from 0.

pageSize
integer <int32> [ 1 .. 100 ]
Default: 20

Page size.

onlyActive
boolean
Default: false

Return only active API keys.

Responses

Response samples

Content type
application/json
{
  • "content": [
    ],
  • "paging": {
    }
}

Revoke API key

Revoke the API key for the knowledge base project. An administrative API key is required for the operation.

Authorizations:
bearerAuth
path Parameters
projectId
required
integer <int64> (LongId)

Knowledge base project identifier.

apiKeyId
required
integer <int64> (LongId)

API key identifier.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "projectId": 0,
  • "name": "string",
  • "key": "string",
  • "status": "string",
  • "ownerLogin": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "expiredAt": "2019-08-24T14:15:22Z",
  • "lastUsedAt": "2019-08-24T14:15:22Z"
}