This is an internal document and is for Sestek employees only and will not be accessible if shared with other parties.
Starting with v4.3, a new document status called Pending has been introduced.
When a large number of documents are submitted via the Upload Documents API, not all of them can enter the processing phase simultaneously due to the concurrent indexing limit (currently 5). Documents that cannot be processed immediately remain in the system with the Pending status and wait in the queue to be indexed.
These data sources are returned with "trainStatus": "Pending" in the List Documents endpoint.
If the ingestionStartDate field is not null, it indicates that the same document has been indexed previously. This date represents the timestamp of the last completed indexing operation, not the current pending one.
Documents in the Pending state can be deleted safely.
Example response of List Documents API:
{
"versionGroupId": "{{DocumentId-1}}",
"lastModificationTime": "2025-02-14T10:32:15Z",
"name": "UserGuide.md",
"sizeInBytes": 482193,
"documentType": "0",
"trainStatus": "Pending",
"ingestionStage": "null",
"ingestionErrorMessage": null,
"ingestionStartDate": "2025-02-14T10:30:02Z"
}
This API provides endpoints used to synchronize documents between a third-party Knowledge Management System and Knovvu VA’s Knowledge Base. Supported operations include listing documents, uploading new ones, deleting existing items, and triggering re-indexing to refresh embeddings and search relevance.
A single Knowledge Base can contain multiple versions. Each version has its own unique identifier, but operations are performed using the Knowledge Base Version Group ID (knowledgeBaseVersionGroupId), which is the logical identifier that represents the entire lifecycle of a knowledge base across all its versions. Each new version (v1, v2, v3, …) is stored as a separate internal entity, but all versions belong to the same version group. All operations target the Draft version, which is always the most recent version within the group.
1. Authentication & Authorization
All operations are authenticated and authorized through client credentials, and access is restricted using the data_service_external_knowledge_base scope.
📄 For getting an access token, please refer to the official guide.
2. Upload Documents
Uploads a new or updated document to the Knowledge Base. Supports multiple file and document types.
- The endpoint always returns 204 No Content when the upload request is accepted.
- The processing status of the document must be tracked via the List Documents endpoint.
- ⛔ Documents with
Processingtraining status cannot be re-uploaded. - Documents with
TrainingAvailableorFailedtraining statuses must be retriggered using Refresh Knowledge Base Index endpoint.
| Request Body Parameters | Type | Required | Description |
|---|---|---|---|
file |
IFormFile |
Yes | The document file to upload. |
| documentType | string | ✅ Yes | Type of processing for the document: - TextOnly: Standard processing for plain text documents. Supported: txt, md, pdf, pptx, docx, xlsx, csv, - Advanced : Advanced processing for visually rich documents. Supported: pdf, - Faq: FAQ-specific Excel processing. Supported: xlsx, - DataTable: Numeric data Excel processing. Supported: xlsx |
Example Request:
curl --location '{{BaseUrl}}/api/external/knowledge-bases/{{KnowledgeBaseVersionGroupId}}/documents' \
--header 'Authorization: Bearer ••••••' \
--form 'file=@"/path/to/file"' \
--form 'documentType="TextOnly"'
Response: 204 No Content
3. List Documents
Retrieves all data sources belonging to the latest Knowledge Base Version, including ingestion and training metadata.
- Data sources in
Processingstatus cannot be retrained or overwritten. - Re-indexing should be triggered for data sources in
TrainingAvailableandFailedstatuses.
| Train Status | Description |
|---|---|
Indexed |
Fully processed and ready for search |
TrainingAvailable |
Requires reindexing but can still be used for search |
Pending |
Queued for ingestion due to concurrent indexing limits |
Processing |
Currently ingesting |
Failed |
Ingestion failed |
Example Request:
curl --location --request GET '{{BaseUrl}}/api/external/knowledge-bases/{{KnowledgeBaseVersionGroupId}}/documents' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ••••••' \
}'
Response: 200 OK
[
{
"versionGroupId": "{{DocumentId-1}}",
"lastModificationTime": "2025-02-14T10:32:15Z",
"name": "UserGuide.md",
"sizeInBytes": 482193,
"documentType": "0",
"trainStatus": "Indexed",
"ingestionStage": "Completed",
"ingestionErrorMessage": null,
"ingestionStartDate": "2025-02-14T10:30:02Z"
},
{
"versionGroupId": "{{DocumentId-2}}",
"lastModificationTime": "2025-02-12T14:01:55Z",
"name": "FAQ.md",
"sizeInBytes": 12988,
"documentType": "0",
"trainStatus": "Failed",
"ingestionStage": "Failed",
"ingestionErrorMessage": "{{ErrorMessage}}",
"ingestionStartDate": "2025-02-12T13:59:10Z
}
]
4. Delete Document
Removes a document from the Knowledge Base.
- Documents currently in Processing status cannot be deleted. Deletion should only be performed after ingestion is complete.
Example Request:
curl --location --request DELETE '{{BaseUrl}}/api/external/knowledge-bases/documents/{{DocumentId}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ••••••' \
}'
Response: 204 No Content
5. Refresh Knowledge Base Index
Triggers a reindex process for documents with "TrainStatus":"Failed" and "TrainStatus": "TrainingAvailable" for the latest version of the Knowledge Base.
Example Request:
curl --location --request POST '{{BaseUrl}}/api/external/knowledge-bases/{knowledgeBaseVersionGroupId}/refresh-index' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ••••••' \
}'
Response: 204 No Content