> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipeshub.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Knowledge base
# Knowledge Base API
The Knowledge Base Service provides a centralized repository for managing and accessing personal data through files and documents. This service enables document storage, retrieval, and management while integrating with the AI backend for intelligent search capabilities.
## Base URL
All endpoints are prefixed with `/api/v1/kb`
## Authentication
All endpoints require authentication via Bearer token:
```http theme={null}
Authorization: Bearer YOUR_TOKEN
```
## Architecture Overview
The Knowledge Base Service is built on a Node.js backend with ArangoDB for graph-based data persistence. The service consists of several key components:
* **Record Management** - Core document storage and metadata handling
* **File Storage Integration** - Connects with external storage services
* **Event Broadcasting** - Kafka-based events for system integration
* **AI Indexing** - Automatic content indexing for search capabilities
The service integrates with these components:
* **Storage Service** - Handles actual file storage and versioning
* **AI Backend** - Processes and indexes content for search
* **Enterprise Search** - Provides search capabilities across the knowledge base
* **IAM Service** - Handles user authentication and authorization
* **Configuration Manager** - Manages application settings
## Data Models
### Records
Records represent the core entities in the knowledge base:
* Metadata about stored content (name, type, source)
* References to physical files in storage
* Versioning information
* Indexing status and history
### File Records
File Records contain file-specific metadata:
* File format information (extension, MIME type)
* Size and storage information
* Access URLs and paths
* Checksum and integrity information
### Knowledge Base
Knowledge Base represents a collection of records:
* Organizational grouping of records
* Permission structure
* Metadata about the collection
## API Endpoints
Manage knowledge base instances including creation, listing, updates, and deletion.
Create a new knowledge base for organizing documents.
**Endpoint:** `POST /api/v1/kb/`
**Request Body Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------------------- |
| kbName | string | Yes | Name for the knowledge base (1-255 characters) |
```json theme={null}
{
"kbName": "Company Documents"
}
```
**Status:** `201 Created`
```json theme={null}
{
"id": "kb123456",
"name": "Company Documents",
"orgId": "org123456",
"createdAt": "2025-04-27T12:00:00.000Z",
"updatedAt": "2025-04-27T12:00:00.000Z",
"isDeleted": false,
"isArchived": false,
"permissions": "OWNER"
}
```
Retrieve all knowledge bases accessible to the user with filtering and pagination.
**Endpoint:** `GET /api/v1/kb/`
**Query Parameters:**
| Parameter | Type | Default | Description |
| ----------- | ------ | --------- | -------------------------------------------------------------- |
| page | number | 1 | Page number for pagination |
| limit | number | 20 | Number of items per page (1-100) |
| search | string | - | Search term for filtering knowledge bases (max 100 characters) |
| permissions | string | - | Comma-separated list of permissions to filter by |
| sortBy | string | createdAt | Field to sort by (createdAt, updatedAt, name) |
| sortOrder | string | desc | Sort order (asc, desc) |
```http theme={null}
GET /api/v1/kb/?page=1&limit=10&search=documents&permissions=OWNER,ADMIN&sortBy=name&sortOrder=asc
```
**Status:** `200 OK`
```json theme={null}
{
"knowledgeBases": [
{
"id": "kb123456",
"name": "Company Documents",
"orgId": "org123456",
"createdAt": "2025-04-27T12:00:00.000Z",
"updatedAt": "2025-04-27T12:00:00.000Z",
"isDeleted": false,
"isArchived": false,
"permissions": "OWNER",
"recordCount": 45
}
],
"pagination": {
"page": 1,
"limit": 10,
"totalCount": 1,
"totalPages": 1
},
"meta": {
"requestId": "req-123",
"timestamp": "2025-04-27T12:05:00.000Z"
}
}
```
Retrieve a specific knowledge base by its ID.
**Endpoint:** `GET /api/v1/kb/:kbId`
**Path Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------- |
| kbId | string | Yes | Knowledge base UUID |
**Status:** `200 OK`
```json theme={null}
{
"knowledgeBase": {
"id": "kb123456",
"name": "Company Documents",
"orgId": "org123456",
"createdAt": "2025-04-27T12:00:00.000Z",
"updatedAt": "2025-04-27T12:00:00.000Z",
"isDeleted": false,
"isArchived": false,
"permissions": "OWNER",
"recordCount": 45
},
"meta": {
"requestId": "req-456",
"timestamp": "2025-04-27T12:10:00.000Z"
}
}
```
Update knowledge base properties.
**Endpoint:** `PUT /api/v1/kb/:kbId`
**Path Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------- |
| kbId | string | Yes | Knowledge base UUID |
**Request Body Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------- |
| name | string | No | New name for the knowledge base |
```json theme={null}
{
"name": "Updated Company Documents"
}
```
**Status:** `200 OK`
```json theme={null}
{
"message": "Knowledge base updated successfully",
"knowledgeBase": {
"id": "kb123456",
"name": "Updated Company Documents",
"updatedAt": "2025-04-27T12:15:00.000Z"
},
"meta": {
"requestId": "req-789",
"timestamp": "2025-04-27T12:15:00.000Z"
}
}
```
Soft-delete a knowledge base and all its contents.
**Endpoint:** `DELETE /api/v1/kb/:kbId`
**Path Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------- |
| kbId | string | Yes | Knowledge base UUID |
**Status:** `200 OK`
```json theme={null}
{
"message": "Knowledge base deleted successfully",
"meta": {
"requestId": "req-101112",
"timestamp": "2025-04-27T12:20:00.000Z"
}
}
```
Manage individual records within knowledge bases including creation, retrieval, updates, and deletion.
Retrieve all records accessible to the user across all knowledge bases.
**Endpoint:** `GET /api/v1/kb/records`
**Query Parameters:**
| Parameter | Type | Default | Description |
| -------------- | ------ | ------------------ | ----------------------------------------------------------------------------------------- |
| page | number | 1 | Page number for pagination |
| limit | number | 20 | Number of items per page (1-100) |
| search | string | - | Search term for filtering records (max 100 characters) |
| recordTypes | string | - | Comma-separated list of record types (FILE, EMAIL, WEBPAGE, MESSAGE, OTHERS) |
| origins | string | - | Comma-separated list of origins (UPLOAD, CONNECTOR) |
| connectors | string | - | Comma-separated list of connector names |
| indexingStatus | string | - | Comma-separated list of indexing statuses (NOT\_STARTED, IN\_PROGRESS, FAILED, COMPLETED) |
| permissions | string | - | Comma-separated list of permissions to filter by |
| dateFrom | number | - | Filter by creation timestamp (milliseconds) |
| dateTo | number | - | Filter by creation timestamp (milliseconds) |
| sortBy | string | createdAtTimestamp | Field to sort by |
| sortOrder | string | desc | Sort order (asc, desc) |
| source | string | all | Source filter (all, local, connector) |
```http theme={null}
GET /api/v1/kb/records?page=1&limit=20&recordTypes=FILE&origins=UPLOAD&indexingStatus=COMPLETED&sortBy=createdAtTimestamp&sortOrder=desc
```
**Status:** `200 OK`
```json theme={null}
{
"records": [
{
"id": "rec789012",
"externalRecordId": "doc123456",
"recordName": "Company Policy.pdf",
"recordType": "FILE",
"origin": "UPLOAD",
"indexingStatus": "COMPLETED",
"createdAtTimestamp": 1714208400000,
"updatedAtTimestamp": 1714208400000,
"version": 1,
"isDeleted": false,
"isArchived": false,
"fileRecord": {
"name": "Company Policy.pdf",
"extension": "pdf",
"mimeType": "application/pdf",
"sizeInBytes": 2048576,
"isFile": true,
"webUrl": "/record/rec789012"
},
"knowledgeBase": {
"id": "kb123456",
"name": "Company Documents"
}
}
],
"pagination": {
"page": 1,
"limit": 20,
"totalCount": 45,
"totalPages": 3
},
"filters": {
"applied": {
"recordTypes": ["FILE"],
"origins": ["UPLOAD"],
"indexingStatus": ["COMPLETED"]
},
"available": {
"recordTypes": [
{ "value": "FILE", "count": 40 },
{ "value": "EMAIL", "count": 5 }
],
"origins": [
{ "value": "UPLOAD", "count": 30 },
{ "value": "CONNECTOR", "count": 15 }
],
"indexingStatus": [
{ "value": "COMPLETED", "count": 42 },
{ "value": "IN_PROGRESS", "count": 2 },
{ "value": "FAILED", "count": 1 }
]
}
},
"meta": {
"requestId": "req-456",
"timestamp": "2025-04-27T12:05:00.000Z"
}
}
```
Retrieve all records within a specific knowledge base.
**Endpoint:** `GET /api/v1/kb/:kbId/records`
**Path Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------- |
| kbId | string | Yes | Knowledge base UUID |
**Query Parameters:** Same as "Get All Records" endpoint
**Status:** `200 OK`
Same response structure as "Get All Records" but filtered to the specific knowledge base.
Retrieve a specific record by its ID with full metadata.
**Endpoint:** `GET /api/v1/kb/record/:recordId`
**Path Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| recordId | string | Yes | Record UUID |
**Status:** `200 OK`
```json theme={null}
{
"record": {
"_key": "rec789012",
"orgId": "org123456",
"recordName": "Company Policy.pdf",
"externalRecordId": "doc123456",
"recordType": "FILE",
"origin": "UPLOAD",
"createdAtTimestamp": 1714208400000,
"updatedAtTimestamp": 1714208400000,
"sourceCreatedAtTimestamp": 1714208400000,
"sourceLastModifiedTimestamp": 1714208400000,
"isDeleted": false,
"isArchived": false,
"indexingStatus": "COMPLETED",
"version": 1,
"webUrl": "/record/rec789012",
"mimeType": "application/pdf",
"fileRecord": {
"name": "Company Policy.pdf",
"extension": "pdf",
"mimeType": "application/pdf",
"sizeInBytes": 2048576,
"isFile": true,
"webUrl": "/record/rec789012"
}
},
"knowledgeBase": {
"id": "kb123456",
"name": "Company Documents",
"orgId": "org123456"
},
"permissions": "OWNER",
"relatedRecords": [],
"meta": {
"requestId": "req-789",
"timestamp": "2025-04-27T12:10:00.000Z"
}
}
```
Update a record with new metadata or file content.
**Endpoint:** `PUT /api/v1/kb/record/:recordId`
**Path Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| recordId | string | Yes | Record UUID |
**Request Body Parameters:**
| Parameter | Type | Required | Description |
| ---------- | ------ | -------- | ---------------------------------------- |
| recordName | string | No | New name for the record |
| file | file | No | New file content (creates a new version) |
**Content-Type:** `multipart/form-data` (when uploading file)
**File Constraints:**
* Maximum file size: 30MB
* Supported MIME types: Based on extensionToMimeType mapping
* File extension must match existing record's extension for versioned updates
```bash theme={null}
curl -X PUT \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "recordName=Updated Company Policy.pdf" \
-F "file=@updated_policy.pdf" \
/api/v1/kb/record/rec789012
```
**Status:** `200 OK`
```json theme={null}
{
"message": "Record updated with new file version",
"record": {
"_key": "rec789012",
"recordName": "Updated Company Policy.pdf",
"externalRecordId": "doc123456",
"version": 2,
"updatedAtTimestamp": 1714294800000,
"indexingStatus": "NOT_STARTED"
},
"meta": {
"requestId": "req-101112",
"timestamp": "2025-04-27T12:15:00.000Z"
}
}
```
Soft-delete a record by setting its deleted flag.
**Endpoint:** `DELETE /api/v1/kb/record/:recordId`
**Path Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| recordId | string | Yes | Record UUID |
**Status:** `200 OK`
```json theme={null}
{
"message": "Record deleted successfully",
"meta": {
"requestId": "req-131415",
"timestamp": "2025-04-27T12:20:00.000Z"
}
}
```
Stream the actual file content of a record for download.
**Endpoint:** `GET /api/v1/kb/stream/record/:recordId`
**Path Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| recordId | string | Yes | Record UUID |
**Status:** `200 OK`
**Headers:**
* `Content-Type`: File's MIME type
* `Content-Disposition`: `attachment; filename="filename.ext"`
* `Content-Length`: File size in bytes
**Body:** Raw file content stream
Force reindexing of a record by the AI backend.
**Endpoint:** `POST /api/v1/kb/reindex/record/:recordId`
**Path Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| recordId | string | Yes | Record UUID |
**Status:** `200 OK`
```json theme={null}
{
"reindexResponse": {
"success": true,
"recordId": "rec789012"
},
"meta": {
"requestId": "req-161718",
"timestamp": "2025-04-27T12:25:00.000Z"
}
}
```
Upload files and folders to knowledge bases with support for bulk operations and folder structures.
Upload files directly to a knowledge base, creating records and folder structures as needed.
**Endpoint:** `POST /api/v1/kb/:kbId/upload`
**Path Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------- |
| kbId | string | Yes | Knowledge base UUID |
**Request Body Parameters:**
| Parameter | Type | Required | Description |
| -------------- | --------- | -------- | -------------------------------------------------------- |
| files | file\[] | Yes | Array of files to upload (max 1000 files, 30MB per file) |
| file\_paths | string\[] | Yes | Array of file paths corresponding to files |
| last\_modified | number\[] | Yes | Array of last modified timestamps (milliseconds) |
| isVersioned | boolean | No | Whether files should be versioned (default: true) |
**Content-Type:** `multipart/form-data`
**File Constraints:**
* Maximum files per upload: 1000
* Maximum file size: 30MB per file
* Supported MIME types: Based on extensionToMimeType mapping
* File paths must be unique and not contain invalid characters
```bash theme={null}
curl -X POST \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "files=@document1.pdf" \
-F "files=@folder/document2.docx" \
-F "file_paths=document1.pdf" \
-F "file_paths=folder/document2.docx" \
-F "last_modified=1714208400000" \
-F "last_modified=1714208500000" \
-F "isVersioned=true" \
/api/v1/kb/kb123456/upload
```
**Status:** `201 Created`
```json theme={null}
{
"message": "Upload completed successfully",
"data": {
"total_created": 2,
"folders_created": 1,
"records_created": 2,
"knowledgeBase": {
"id": "kb123456",
"name": "Company Documents"
},
"createdRecords": [
{
"id": "rec789012",
"name": "document1.pdf",
"type": "FILE",
"folderId": null
},
{
"id": "rec789013",
"name": "document2.docx",
"type": "FILE",
"folderId": "folder456"
}
],
"createdFolders": [
{
"id": "folder456",
"name": "folder",
"path": "folder"
}
]
},
"meta": {
"requestId": "req-192021",
"timestamp": "2025-04-27T12:30:00.000Z"
}
}
```
Upload files to a specific folder within a knowledge base.
**Endpoint:** `POST /api/v1/kb/:kbId/folder/:folderId/upload`
**Path Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------- |
| kbId | string | Yes | Knowledge base UUID |
| folderId | string | Yes | Target folder UUID |
**Request Body Parameters:** Same as "Upload to Knowledge Base"
```bash theme={null}
curl -X POST \
-H "Authorization: Bearer YOUR_TOKEN" \
-F "files=@document.pdf" \
-F "file_paths=document.pdf" \
-F "last_modified=1714208400000" \
/api/v1/kb/kb123456/folder/folder456/upload
```
**Status:** `201 Created`
```json theme={null}
{
"message": "Folder upload completed successfully",
"data": {
"total_created": 1,
"folders_created": 0,
"records_created": 1,
"targetFolder": {
"id": "folder456",
"name": "Target Folder"
},
"createdRecords": [
{
"id": "rec789014",
"name": "document.pdf",
"type": "FILE",
"folderId": "folder456"
}
]
},
"meta": {
"requestId": "req-222324",
"timestamp": "2025-04-27T12:35:00.000Z"
}
}
```
Manage folder structures within knowledge bases including content retrieval, updates, and deletion.
Retrieve all records and subfolders within a specific folder.
**Endpoint:** `GET /api/v1/kb/:kbId/folder/:folderId/records`
**Path Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------- |
| kbId | string | Yes | Knowledge base UUID |
| folderId | string | Yes | Folder UUID |
**Query Parameters:** Same filtering and pagination parameters as record endpoints
**Status:** `200 OK`
```json theme={null}
{
"folder": {
"id": "folder456",
"name": "Documents Folder",
"path": "documents",
"parentId": null,
"createdAt": "2025-04-27T12:00:00.000Z",
"updatedAt": "2025-04-27T12:00:00.000Z"
},
"contents": {
"records": [
{
"id": "rec789012",
"recordName": "Company Policy.pdf",
"recordType": "FILE",
"createdAtTimestamp": 1714208400000,
"fileRecord": {
"name": "Company Policy.pdf",
"extension": "pdf",
"mimeType": "application/pdf",
"sizeInBytes": 2048576
}
}
],
"folders": [
{
"id": "subfolder789",
"name": "Policies",
"path": "documents/policies",
"recordCount": 5
}
]
},
"pagination": {
"page": 1,
"limit": 20,
"totalCount": 6,
"totalPages": 1
},
"meta": {
"requestId": "req-252627",
"timestamp": "2025-04-27T12:40:00.000Z"
}
}
```
Update folder properties such as name.
**Endpoint:** `PUT /api/v1/kb/:kbId/folder/:folderId`
**Path Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------- |
| kbId | string | Yes | Knowledge base UUID |
| folderId | string | Yes | Folder UUID |
**Request Body Parameters:**
| Parameter | Type | Required | Description |
| ---------- | ------ | -------- | ----------------------- |
| folderName | string | Yes | New name for the folder |
```json theme={null}
{
"folderName": "Updated Folder Name"
}
```
**Status:** `200 OK`
```json theme={null}
{
"message": "Folder updated successfully",
"meta": {
"requestId": "req-282930",
"timestamp": "2025-04-27T12:45:00.000Z"
}
}
```
Delete a folder and all its contents.
**Endpoint:** `DELETE /api/v1/kb/:kbId/folder/:folderId`
**Path Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------- |
| kbId | string | Yes | Knowledge base UUID |
| folderId | string | Yes | Folder UUID |
**Status:** `200 OK`
```json theme={null}
{
"message": "Folder deleted successfully",
"meta": {
"requestId": "req-313233",
"timestamp": "2025-04-27T12:50:00.000Z"
}
}
```
Administrative endpoints for managing connectors, bulk operations, and system maintenance.
Retrieve statistics for a specific connector.
**Access Control:** Admin users only
**Endpoint:** `GET /api/v1/kb/stats/:connector`
**Path Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------------------------------------- |
| connector | string | Yes | Connector name (onedrive, google\_drive, confluence, slack, etc.) |
**Status:** `200 OK`
```json theme={null}
{
"connector": "google_drive",
"stats": {
"totalRecords": 1250,
"indexedRecords": 1200,
"failedRecords": 50,
"lastSyncTimestamp": 1714208400000,
"indexingStatus": {
"NOT_STARTED": 10,
"IN_PROGRESS": 5,
"COMPLETED": 1200,
"FAILED": 35
},
"recordTypes": {
"FILE": 1200,
"EMAIL": 50
}
},
"meta": {
"requestId": "req-343536",
"timestamp": "2025-04-27T12:55:00.000Z"
}
}
```
Force reindexing of all failed records for a specific connector.
**Access Control:** Admin users only
**Endpoint:** `POST /api/v1/kb/reindex-all/connector`
**Request Body Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------------- |
| connector | string | Yes | Connector name to reindex |
| orgId | string | No | Organization ID (defaults to user's org) |
```json theme={null}
{
"connector": "google_drive",
"orgId": "org123456"
}
```
**Status:** `200 OK`
```json theme={null}
{
"message": "Reindexing initiated for all failed records",
"data": {
"connector": "google_drive",
"recordsToReindex": 35,
"batchId": "batch-789012"
},
"meta": {
"requestId": "req-373839",
"timestamp": "2025-04-27T13:00:00.000Z"
}
}
```
Force resynchronization of all records for a specific connector.
**Access Control:** Admin users only
**Endpoint:** `POST /api/v1/kb/resync/connector`
**Request Body Parameters:**
| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | ----------------------------------------------- |
| connector | string | Yes | Connector name to resync |
| orgId | string | No | Organization ID (defaults to user's org) |
| fullResync | boolean | No | Whether to perform full resync (default: false) |
```json theme={null}
{
"connector": "google_drive",
"orgId": "org123456",
"fullResync": true
}
```
**Status:** `200 OK`
```json theme={null}
{
"message": "Connector resync initiated successfully",
"data": {
"connector": "google_drive",
"syncType": "full",
"estimatedRecords": 1250,
"syncId": "sync-404142"
},
"meta": {
"requestId": "req-404142",
"timestamp": "2025-04-27T13:05:00.000Z"
}
}
```
## Event System
The Knowledge Base Service broadcasts events through Kafka to notify other services about record changes. These events trigger actions like content indexing, search updates, and audit logging.
### Event Types
| Event Type | Description |
| --------------- | ---------------------------------------- |
| `newRecord` | Triggered when a new record is created |
| `updateRecord` | Triggered when a record is updated |
| `deletedRecord` | Triggered when a record is deleted |
| `reindexRecord` | Triggered when a record needs reindexing |
### Event Payload Structure
```json theme={null}
{
"orgId": "org123456",
"recordId": "rec789012",
"recordName": "Company Policy.pdf",
"recordType": "FILE",
"version": 1,
"signedUrlRoute": "https://storage.example.com/api/v1/document/internal/doc123456/download",
"origin": "UPLOAD",
"extension": "pdf",
"mimeType": "application/pdf",
"createdAtTimestamp": "1714208400000",
"updatedAtTimestamp": "1714208400000",
"sourceCreatedAtTimestamp": "1714208400000"
}
```
```json theme={null}
{
"orgId": "org123456",
"recordId": "rec789012",
"version": 2,
"signedUrlRoute": "https://storage.example.com/api/v1/document/internal/doc123456/download",
"updatedAtTimestamp": "1714294800000",
"sourceLastModifiedTimestamp": "1714294800000"
}
```
```json theme={null}
{
"orgId": "org123456",
"recordId": "rec789012",
"version": 2,
"extension": "pdf",
"mimeType": "application/pdf"
}
```
## Schema Definitions
```typescript theme={null}
interface IRecordDocument {
// Identifiers
_key: string;
orgId: string;
// Core metadata
recordName: string;
externalRecordId: string;
externalRevisionId?: string;
recordType: RecordType; // 'FILE' | 'WEBPAGE' | 'MESSAGE' | 'EMAIL' | 'OTHERS'
origin: OriginType; // 'UPLOAD' | 'CONNECTOR'
// Timestamps
createdAtTimestamp: number;
updatedAtTimestamp?: number;
lastSyncTimestamp?: number;
sourceCreatedAtTimestamp?: number;
sourceLastModifiedTimestamp?: number;
// Status flags
isDeletedAtSource?: boolean;
deletedAtSourceTimestamp?: number;
isDeleted?: boolean;
isArchived?: boolean;
deletedByUserId?: string;
// Indexing information
lastIndexTimestamp?: number;
lastExtractionTimestamp?: number;
indexingStatus?: IndexingStatus; // 'NOT_STARTED' | 'IN_PROGRESS' | 'FAILED' | 'COMPLETED'
// Versioning
version?: number;
isLatestVersion?: boolean;
isDirty?: boolean;
// File-specific fields (for FILE records)
webUrl?: string;
mimeType?: string;
// Optional connector information
connectorName?: ConnectorName; // 'ONEDRIVE' | 'GOOGLE_DRIVE' | 'CONFLUENCE' | 'SLACK'
}
```
```typescript theme={null}
interface IFileRecordDocument {
// Identifiers
_key?: string;
orgId: string;
// Core metadata
name: string;
isFile?: boolean;
extension?: string | null;
mimeType?: string | null;
sizeInBytes?: number;
webUrl?: string;
path?: string;
// Hash information for integrity
etag?: string | null;
ctag?: string | null;
quickXorHash?: string | null;
crc32Hash?: string | null;
sha1Hash?: string | null;
sha256Hash?: string | null;
// External identifiers
externalFileId?: string;
}
```
```typescript theme={null}
interface IKnowledgeBase {
// Identifiers
_key: string;
_id?: string;
orgId: string;
// Metadata
name: string;
createdAtTimestamp: number;
updatedAtTimestamp: number;
// Status flags
isDeleted: boolean;
isArchived: boolean;
}
```
```typescript theme={null}
interface UploadRecordsRequest {
// File upload arrays (must have same length)
files: Express.Multer.File[];
file_paths: string[];
last_modified: number[];
// Optional parameters
isVersioned?: boolean;
recordType?: string;
origin?: string;
}
interface UploadRecordsResponse {
message: string;
data: {
total_created: number;
folders_created: number;
records_created: number;
knowledgeBase: {
id: string;
name: string;
};
createdRecords: Array<{
id: string;
name: string;
type: string;
folderId?: string;
}>;
createdFolders?: Array<{
id: string;
name: string;
path: string;
}>;
};
meta: {
requestId: string;
timestamp: string;
};
}
```
## Error Handling
All endpoints return structured error responses with specific HTTP status codes:
```json theme={null}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"details": {
"field": "kbName",
"issue": "Knowledge base name is required"
}
},
"meta": {
"requestId": "req-error-123",
"timestamp": "2025-04-27T13:20:00.000Z"
}
}
```
**Common Error Codes:**
* `400 Bad Request` - Invalid request parameters, file validation errors
* `401 Unauthorized` - Missing or invalid authentication
* `403 Forbidden` - Insufficient permissions
* `404 Not Found` - Resource not found
* `413 Payload Too Large` - File size exceeds limit
* `422 Unprocessable Entity` - Validation errors
* `500 Internal Server Error` - Server errors, backend service failures
**File Upload Specific Errors:**
* File extension mismatch for versioned updates
* Unsupported MIME types
* File size exceeds 30MB limit
* Invalid file path characters
* Duplicate file paths in upload
## Integration with AI Indexing
When a record is created or updated, the Knowledge Base Service:
1. Stores the file metadata in ArangoDB
2. Uploads the file content to the Storage Service
3. Publishes a Kafka event with the file metadata and download URL
4. The AI Backend consumes these events and:
* Downloads the file content
* Extracts text and structured data
* Processes the content for search indexing
* Updates the indexing status in the Knowledge Base
This integration enables Enterprise Search to provide intelligent search capabilities across the entire knowledge base.
## Security and Permissions
* All endpoints require valid JWT authentication
* Admin endpoints require additional role verification
* File uploads are validated for MIME type and size
* Access control is enforced at the organization level
* File content is streamed securely through signed URLs
* Upload paths are sanitized to prevent directory traversal
## Rate Limits and Constraints
* **File Upload**: Maximum 30MB per file, 1000 files per upload
* **Pagination**: Maximum 100 items per page
* **Search Terms**: Maximum 100 characters
* **Knowledge Base Names**: 1-255 characters
* **File Paths**: Must not contain invalid characters or be duplicated