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:

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

Knowledge Base Management

Manage knowledge base instances including creation, listing, updates, and deletion.

POST / - Create Knowledge Base

Create a new knowledge base for organizing documents.

Request
Response

Endpoint: POST /api/v1/kb/Request Body Parameters:

Parameter	Type	Required	Description
kbName	string	Yes	Name for the knowledge base (1-255 characters)

{
  "kbName": "Company Documents"
}

Status: 201 Created

{
  "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"
}

GET / - List Knowledge Bases

Retrieve all knowledge bases accessible to the user with filtering and pagination.

Request
Response

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)

GET /api/v1/kb/?page=1&limit=10&search=documents&permissions=OWNER,ADMIN&sortBy=name&sortOrder=asc

Status: 200 OK

{
  "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"
  }
}

GET /:kbId - Get Knowledge Base

Retrieve a specific knowledge base by its ID.

Request
Response

Endpoint: GET /api/v1/kb/:kbIdPath Parameters:

Parameter	Type	Required	Description
kbId	string	Yes	Knowledge base UUID

Status: 200 OK

{
  "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"
  }
}

PUT /:kbId - Update Knowledge Base

Update knowledge base properties.

Request
Response

Endpoint: PUT /api/v1/kb/:kbIdPath 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

{
  "name": "Updated Company Documents"
}

Status: 200 OK

{
  "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"
  }
}

DELETE /:kbId - Delete Knowledge Base

Soft-delete a knowledge base and all its contents.

Request
Response

Endpoint: DELETE /api/v1/kb/:kbIdPath Parameters:

Parameter	Type	Required	Description
kbId	string	Yes	Knowledge base UUID

Status: 200 OK

{
  "message": "Knowledge base deleted successfully",
  "meta": {
    "requestId": "req-101112",
    "timestamp": "2025-04-27T12:20:00.000Z"
  }
}

Record Management

Manage individual records within knowledge bases including creation, retrieval, updates, and deletion.

GET /records - Get All Records

Retrieve all records accessible to the user across all knowledge bases.

Request
Response

Endpoint: GET /api/v1/kb/recordsQuery 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)

GET /api/v1/kb/records?page=1&limit=20&recordTypes=FILE&origins=UPLOAD&indexingStatus=COMPLETED&sortBy=createdAtTimestamp&sortOrder=desc

Status: 200 OK

{
  "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"
  }
}

GET /:kbId/records - Get KB Records

Retrieve all records within a specific knowledge base.

Request
Response

Endpoint: GET /api/v1/kb/:kbId/recordsPath Parameters:

Parameter	Type	Required	Description
kbId	string	Yes	Knowledge base UUID

Query Parameters: Same as “Get All Records” endpoint

Status: 200 OKSame response structure as “Get All Records” but filtered to the specific knowledge base.

GET /record/:recordId - Get Record By ID

Retrieve a specific record by its ID with full metadata.

Request
Response

Endpoint: GET /api/v1/kb/record/:recordIdPath Parameters:

Parameter	Type	Required	Description
recordId	string	Yes	Record UUID

Status: 200 OK

{
  "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"
  }
}

PUT /record/:recordId - Update Record

Update a record with new metadata or file content.

Request
Response

Endpoint: PUT /api/v1/kb/record/:recordIdPath 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

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

{
  "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"
  }
}

DELETE /record/:recordId - Delete Record

Soft-delete a record by setting its deleted flag.

Request
Response

Endpoint: DELETE /api/v1/kb/record/:recordIdPath Parameters:

Parameter	Type	Required	Description
recordId	string	Yes	Record UUID

Status: 200 OK

{
  "message": "Record deleted successfully",
  "meta": {
    "requestId": "req-131415",
    "timestamp": "2025-04-27T12:20:00.000Z"
  }
}

GET /stream/record/:recordId - Stream Record Content

Stream the actual file content of a record for download.

Request
Response

Endpoint: GET /api/v1/kb/stream/record/:recordIdPath Parameters:

Parameter	Type	Required	Description
recordId	string	Yes	Record UUID

Status: 200 OKHeaders:

Content-Type: File’s MIME type
Content-Disposition: attachment; filename="filename.ext"
Content-Length: File size in bytes

Body: Raw file content stream

POST /reindex/record/:recordId - Reindex Record

Force reindexing of a record by the AI backend.

Request
Response

Endpoint: POST /api/v1/kb/reindex/record/:recordIdPath Parameters:

Parameter	Type	Required	Description
recordId	string	Yes	Record UUID

Status: 200 OK

{
  "reindexResponse": {
    "success": true,
    "recordId": "rec789012"
  },
  "meta": {
    "requestId": "req-161718",
    "timestamp": "2025-04-27T12:25:00.000Z"
  }
}

Upload Operations

Upload files and folders to knowledge bases with support for bulk operations and folder structures.

POST /:kbId/upload - Upload to Knowledge Base

Upload files directly to a knowledge base, creating records and folder structures as needed.

Request
Response

Endpoint: POST /api/v1/kb/:kbId/uploadPath 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-dataFile 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

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

{
  "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"
  }
}

POST /:kbId/folder/:folderId/upload - Upload to Folder

Upload files to a specific folder within a knowledge base.

Request
Response

Endpoint: POST /api/v1/kb/:kbId/folder/:folderId/uploadPath 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”

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

{
  "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"
  }
}

Folder Operations

Manage folder structures within knowledge bases including content retrieval, updates, and deletion.

GET /:kbId/folder/:folderId/records - Get Folder Contents

Retrieve all records and subfolders within a specific folder.

Request
Response

Endpoint: GET /api/v1/kb/:kbId/folder/:folderId/recordsPath 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

{
  "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"
  }
}

PUT /:kbId/folder/:folderId - Update Folder

Update folder properties such as name.

Request
Response

Endpoint: PUT /api/v1/kb/:kbId/folder/:folderIdPath 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

{
  "folderName": "Updated Folder Name"
}

Status: 200 OK

{
  "message": "Folder updated successfully",
  "meta": {
    "requestId": "req-282930",
    "timestamp": "2025-04-27T12:45:00.000Z"
  }
}

DELETE /:kbId/folder/:folderId - Delete Folder

Delete a folder and all its contents.

Request
Response

Endpoint: DELETE /api/v1/kb/:kbId/folder/:folderIdPath Parameters:

Parameter	Type	Required	Description
kbId	string	Yes	Knowledge base UUID
folderId	string	Yes	Folder UUID

Status: 200 OK

{
  "message": "Folder deleted successfully",
  "meta": {
    "requestId": "req-313233",
    "timestamp": "2025-04-27T12:50:00.000Z"
  }
}

Administrative Operations

Administrative endpoints for managing connectors, bulk operations, and system maintenance.

GET /stats/:connector - Get Connector Stats

Retrieve statistics for a specific connector.Access Control: Admin users only

Request
Response

Endpoint: GET /api/v1/kb/stats/:connectorPath Parameters:

Parameter	Type	Required	Description
connector	string	Yes	Connector name (onedrive, google_drive, confluence, slack, etc.)

Status: 200 OK

{
  "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"
  }
}

POST /reindex-all/connector - Reindex All Failed Records

Force reindexing of all failed records for a specific connector.Access Control: Admin users only

Request
Response

Endpoint: POST /api/v1/kb/reindex-all/connectorRequest Body Parameters:

Parameter	Type	Required	Description
connector	string	Yes	Connector name to reindex
orgId	string	No	Organization ID (defaults to user’s org)

{
  "connector": "google_drive",
  "orgId": "org123456"
}

Status: 200 OK

{
  "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"
  }
}

POST /resync/connector - Resync Connector Records

Force resynchronization of all records for a specific connector.Access Control: Admin users only

Request
Response

Endpoint: POST /api/v1/kb/resync/connectorRequest 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)

{
  "connector": "google_drive",
  "orgId": "org123456",
  "fullResync": true
}

Status: 200 OK

{
  "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

New Record Event

{
  "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"
}

Update Record Event

{
  "orgId": "org123456",
  "recordId": "rec789012",
  "version": 2,
  "signedUrlRoute": "https://storage.example.com/api/v1/document/internal/doc123456/download",
  "updatedAtTimestamp": "1714294800000",
  "sourceLastModifiedTimestamp": "1714294800000"
}

Deleted Record Event

{
  "orgId": "org123456",
  "recordId": "rec789012",
  "version": 2,
  "extension": "pdf",
  "mimeType": "application/pdf"
}

Schema Definitions

Record Schema

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'
}

File Record Schema

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;
}

Knowledge Base Schema

interface IKnowledgeBase {
  // Identifiers
  _key: string;
  _id?: string;
  orgId: string;
  
  // Metadata
  name: string;
  createdAtTimestamp: number;
  updatedAtTimestamp: number;
  
  // Status flags
  isDeleted: boolean;
  isArchived: boolean;
}

Upload Schema

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:

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

Stores the file metadata in ArangoDB
Uploads the file content to the Storage Service
Publishes a Kafka event with the file metadata and download URL
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

Welcome To PipesHub

System Overview

Authentication

Mail Configuration

AI Providers

Connectors

Integrations

Agents

Toolsets

User Management

Deployment

Developer

Additional Resources

Knowledge base

Knowledge Base API

Base URL

Authentication

Architecture Overview

Data Models

Records

File Records

Knowledge Base

API Endpoints

Event System

Event Types

Event Payload Structure

Schema Definitions

Error Handling

Integration with AI Indexing

Security and Permissions

Rate Limits and Constraints

Welcome To PipesHub

System Overview

Authentication

Mail Configuration

AI Providers

Connectors

Integrations

Agents

Toolsets

User Management

Deployment

Developer

Additional Resources

Documentation Index

​Knowledge Base API

​Base URL

​Authentication

​Architecture Overview

​Data Models

​Records

​File Records

​Knowledge Base

​API Endpoints

​Event System

​Event Types

​Event Payload Structure

​Schema Definitions

​Error Handling

​Integration with AI Indexing

​Security and Permissions

​Rate Limits and Constraints

Knowledge Base API

Base URL

Authentication

Architecture Overview

Data Models

Records

File Records

Knowledge Base

API Endpoints

Event System

Event Types

Event Payload Structure

Schema Definitions

Error Handling

Integration with AI Indexing

Security and Permissions

Rate Limits and Constraints