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/knowledgeBase

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 graph-based data persistence in whichever graph database the instance is configured to use (Neo4j by default, ArangoDB as an alternative). 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/knowledgeBase/Request Body Parameters:

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

{
  "kbName": "Company Documents"
}

Status: 200 OK

{
  "id": "kb123456",
  "name": "Company Documents",
  "createdAtTimestamp": 1745755200000,
  "updatedAtTimestamp": 1745755200000,
  "userRole": "OWNER"
}

The timestamps are milliseconds since 1 January 1970 (UTC). You own the knowledge base you create, so userRole is always OWNER here.

GET / - List Knowledge Bases

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

Request
Response

Endpoint: GET /api/v1/knowledgeBase/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 1000 characters)
permissions	string	-	Comma-separated list of your roles to filter by: `OWNER`, `WRITER` or `READER`. Any other value is refused with `400 Bad Request`.
sortBy	string	name	Field to sort by: `name`, `updatedAtTimestamp` or `userRole`. `createdAtTimestamp` is also accepted, but the list then comes back sorted by name.
sortOrder	string	asc	Sort order (asc, desc)

GET /api/v1/knowledgeBase/?page=1&limit=10&search=documents&permissions=OWNER,WRITER&sortBy=updatedAtTimestamp&sortOrder=desc

Status: 200 OK

{
  "knowledgeBases": [
    {
      "id": "kb123456",
      "name": "Company Documents",
      "connectorId": null,
      "createdAtTimestamp": 1745755200000,
      "updatedAtTimestamp": 1745756100000,
      "createdBy": "user123456",
      "userRole": "OWNER",
      "folders": [
        {
          "id": "folder123",
          "name": "Policies",
          "createdAtTimestamp": 1745755500000
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "totalCount": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  },
  "filters": {
    "applied": {
      "search": "documents",
      "permissions": ["OWNER", "WRITER"],
      "sort_by": "updatedAtTimestamp",
      "sort_order": "desc"
    },
    "available": {
      "permissions": ["OWNER", "WRITER"],
      "sortFields": ["name", "createdAtTimestamp", "updatedAtTimestamp", "userRole"],
      "sortOrders": ["asc", "desc"]
    }
  }
}

folders lists the folders in each knowledge base. filters.applied repeats the search, roles and sort you asked for, leaving out the default sort (name, asc). filters.available lists the roles you hold across your knowledge bases, and the sort options.

GET /:kbId - Get Knowledge Base

Retrieve a specific knowledge base by its ID.

Request
Response

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

Parameter	Type	Required	Description
kbId	string	Yes	Knowledge base UUID

Status: 200 OK

{
  "id": "kb123456",
  "name": "Company Documents",
  "connectorId": null,
  "createdAtTimestamp": 1745755200000,
  "updatedAtTimestamp": 1745756100000,
  "createdBy": "user123456",
  "userRole": "OWNER",
  "folders": [
    {
      "id": "folder123",
      "name": "Policies",
      "createdAtTimestamp": 1745755500000
    }
  ]
}

The knowledge base comes back as a plain object, the same shape as one item in the list above.

PUT /:kbId - Update Knowledge Base

Update knowledge base properties.

Request
Response

Endpoint: PUT /api/v1/knowledgeBase/:kbIdPath Parameters:

Parameter	Type	Required	Description
kbId	string	Yes	Knowledge base UUID

Request Body Parameters:

Parameter	Type	Required	Description
kbName	string	No	New name for the knowledge base (1-255 characters)

{
  "kbName": "Updated Company Documents"
}

Status: 200 OK

{
  "success": true,
  "message": "Knowledge base updated successfully"
}

The response does not include the knowledge base. Call GET /:kbId to read the new name.

DELETE /:kbId - Delete Knowledge Base

Delete a knowledge base, with all its folders and records. Only the knowledge base’s owner can delete it, and it can’t be undone.

First, PipesHub lists the knowledge base’s uploaded files and schedules their removal. If either step fails, nothing is deleted and the request returns 503; try again.
A 200 means the folders and records are gone from the graph. The indexing service then removes their search index (embeddings) and stored files.
Retries. If storage can’t remove a file, or the file’s record can’t be checked, the removal is retried until it succeeds, with no time limit. If a record still lists the file, the removal is retried for up to one day, then the file is kept, because that record was never deleted (see the Deletion note on the Storage page).
Shared content. If a record in another knowledge base or connector has identical content, that record’s uploaded file and the shared search index stay. If the processed copy of that content was filed under the deleted knowledge base, it is moved to the surviving record’s storage location and keeps its document ID, so the surviving record isn’t re-indexed. If that handover fails, nothing is deleted from the knowledge base’s storage, and the release is retried until it succeeds.

Request
Response

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

Parameter	Type	Required	Description
kbId	string	Yes	Knowledge base UUID

Status: 200 OK

{
  "success": true,
  "message": "Knowledge base deleted successfully"
}

Record Management

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

GET /record/:recordId - Get Record By ID

Retrieve a specific record by its ID with full metadata.

Request
Response

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

Parameter	Type	Required	Description
recordId	string	Yes	Record UUID

Status: 200 OK

{
  "record": {
    "id": "rec789012",
    "orgId": "org123456",
    "recordName": "Company Policy.pdf",
    "externalRecordId": "doc123456",
    "recordType": "FILE",
    "origin": "UPLOAD",
    "connectorName": "KB",
    "connectorId": "kb123456",
    "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"
    },
    "mailRecord": null,
    "ticketRecord": null
  },
  "knowledgeBase": {
    "id": "kb123456",
    "name": "Company Documents",
    "orgId": "org123456"
  },
  "folder": null,
  "metadata": {
    "departments": [],
    "categories": [],
    "subcategories1": [],
    "subcategories2": [],
    "subcategories3": [],
    "topics": [],
    "languages": []
  },
  "permissions": [
    {
      "id": "rec789012",
      "name": "Company Policy.pdf",
      "type": "FILE",
      "relationship": "OWNER",
      "accessType": "KNOWLEDGE_BASE"
    }
  ]
}

permissions holds one entry describing your access to the record: relationship is your role, and accessType is how you have it (here, through the knowledge base). metadata lists the departments, categories, topics and languages found for the record. folder is often null, even for a file that is inside a folder.Some fields appear on record only in certain states:

Field	When it appears
`retryNotBefore`	The record is `QUEUED` because its source is limiting how often PipesHub can read from it. The value is the earliest time, in epoch milliseconds, that indexing tries the record again, and `reason` says when indexing resumes. Ignore it when `indexingStatus` is anything other than `QUEUED`.
`restoredAtTimestamp`	A file was brought back from the trash and queued to be indexed again. The value is when that last happened, in epoch milliseconds.

PUT /record/:recordId - Update Record

Update a record with new metadata or file content.

Request
Response

Endpoint: PUT /api/v1/knowledgeBase/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. Ignored when you attach a file (see below).
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

Duplicate names: a rename is refused with 409 Conflict, and the file keeps its old name, when another file of the same type in the same folder (or the knowledge base root) already has the new name. Names are compared ignoring case, so Report.pdf and report.pdf count as the same. A file of a different type may use the same name.

curl -X PUT \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@updated_policy.pdf" \
  /api/v1/knowledgeBase/record/rec789012

When you attach a file, the record is renamed after that file, without its extension: uploading updated_policy.pdf names the record updated_policy, and any recordName you send with the file is ignored. To rename a record, send recordName on its own, without a file.

Status: 200 OK

{
  "message": "Record updated with new file version",
  "record": {
    "id": "rec789012",
    "recordName": "updated_policy",
    "externalRecordId": "doc123456",
    "updatedAtTimestamp": 1714294800000
  },
  "fileUploaded": true,
  "meta": {
    "requestId": "anon-9d4e2b7c1a8f4c3e9b6d0a5f2e7c1b8d",
    "timestamp": "2025-04-27T12:15:00.000Z"
  }
}

record is the stored record after the update, shortened here. When you only rename the record, message is Record updated successfully and fileUploaded is false.

PUT /:kbId/record/:recordId/move - Move Record

Move a file or folder to another folder in the same knowledge base, or to the knowledge base root.

Request
Response

Endpoint: PUT /api/v1/knowledgeBase/:kbId/record/:recordId/movePath Parameters:

Parameter	Type	Required	Description
kbId	string	Yes	Knowledge base UUID
recordId	string	Yes	Record ID of the file or folder to move

Request Body Parameters:

Parameter	Type	Required	Description
newParentId	string \| null	Yes	Target folder ID, or `null` to move to the knowledge base root

{
  "newParentId": "folder456"
}

Duplicate names: a move is refused with 409 Conflict, and the record stays where it was, when the destination folder (or the knowledge base root) already holds:

for a file, a file with the same name (ignoring case) and the same type. A file of a different type may share the name.
for a folder, a folder with the same name (ignoring case).

Status: 200 OK

{
  "success": true,
  "message": "Record moved successfully"
}

DELETE /record/:recordId - Delete Record

Delete a file from a knowledge base. Only files uploaded to a knowledge base can be deleted here: a record synced from a connector is refused with 403 Forbidden, and is removed by deleting the item in the source app.The result depends on the Labs setting Move Deleted Records to the Trash:

Off (the default): the record is removed from the graph database and can’t be restored.
- First, PipesHub schedules the removal of the record’s uploaded file. If that fails, nothing is deleted and the request returns 503; try again.
- A 200 means the record is gone from the graph. The indexing service then removes its search index (embeddings) and uploaded file.
- Retries. If storage can’t remove a file, or the file’s record can’t be checked, the removal is retried until it succeeds, with no time limit. If a record still lists the file, the removal is retried for up to one day, then the file is kept, because that record was never deleted (see the Deletion note on the Storage page).
- Shared content. If another record has identical content, the shared search index and processed content stay until the last copy is deleted.
On: the record goes to the trash. It disappears from search, chat and listings at once, and its uploaded file is kept until the scheduled cleanup. Until then, it can be restored with POST /record/:recordId/restore or from the collection’s Recently deleted page; see How long items stay. The response has softDeleted: true and the delete’s batchId.

Request
Response

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

Parameter	Type	Required	Description
recordId	string	Yes	Record UUID

Status: 200 OK

{
  "success": true,
  "message": "Record rec789012 deleted successfully",
  "recordId": "rec789012",
  "connector": null,
  "timestamp": null
}

connector and timestamp are often null, so don’t rely on them. If the search index couldn’t be told about the deletion, the response also has vectorCleanupPending: true and vectorCleanupFailedRecordIds, the records whose search entries are still waiting to be removed.

GET /:kbId/trash - List Recently Deleted Items

List one page of a collection’s deleted items that can still be restored, newest first. Each item is one delete, which a restore brings back whole: a folder deleted with its contents is one item, and so is a multi-select delete. itemCount is the number of records an item holds. For a multi-select delete, rootCount is how many items were selected, and otherRootNames names up to three of them besides name. To restore an item, pass its id to POST /record/:recordId/restore.Needs Move Deleted Records to the Trash on in Labs. The list holds only what the caller may restore: owners and writers see every item, file organizers see single files only, and other roles get 403 Forbidden. OAuth apps need the kb:delete scope.

Request
Response

Endpoint: GET /api/v1/knowledgeBase/:kbId/trashPath Parameters:

Parameter	Type	Required	Description
kbId	string	Yes	Knowledge base (collection) UUID

Query Parameters:

Parameter	Type	Required	Description
page	integer	No	Page number, from 1 (default 1)
limit	integer	No	Items per page, 1 to 100 (default 25)

Status: 200 OK

{
  "success": true,
  "items": [
    {
      "id": "rec789012",
      "name": "Specs",
      "recordType": "FILE",
      "isFolder": true,
      "mimeType": null,
      "sizeInBytes": null,
      "parentId": null,
      "parentName": null,
      "parentInTrash": false,
      "itemCount": 4,
      "rootCount": 1,
      "otherRootNames": [],
      "deletedAtTimestamp": 1790000000000,
      "deletedBy": { "name": "Ada Admin", "email": "ada@example.com" },
      "removableAfterTimestamp": 1791209600000
    }
  ],
  "pagination": { "page": 1, "limit": 25, "totalCount": 1, "totalPages": 1 },
  "retention": { "minAgeMs": 1209600000 }
}

parentInTrash: true means the item’s folder is in the trash too; restore that folder first.
removableAfterTimestamp is the earliest time the scheduled cleanup may remove the item for good. removableAfterTimestamp and retention are null when the retention settings can’t be read. For the defaults and the settings that change them, see How long items stay.

POST /record/:recordId/restore - Restore Deleted Record

Restore a record from the trash, with everything deleted in the same action: a folder with its contents, a file with its attachments, a multi-select delete with every item it removed. Pass the id of any item from that delete.Needs Move Deleted Records to the Trash on in Labs, and the role the delete needed: OWNER, WRITER or FILEORGANIZER for a single file, OWNER or WRITER for a folder or several items. OAuth apps need the kb:delete scope.

Request
Response

Endpoint: POST /api/v1/knowledgeBase/record/:recordId/restorePath Parameters:

Parameter	Type	Required	Description
recordId	string	Yes	Record UUID of any item in the delete

Status: 200 OK

{
  "success": true,
  "message": "Restored 2 item(s).",
  "batchId": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
  "restoredRecords": [
    { "recordId": "rec789012", "name": "report (restored).pdf", "renamedFrom": "report.pdf" },
    { "recordId": "rec789013", "name": "notes.txt" }
  ]
}

If another item in the same place now has its name, the restored item comes back as name (restored), and renamedFrom gives its old name.
Restored files are indexed again and return to search once indexing finishes. If some couldn’t be queued for indexing, the response has reindexPending: true and lists them in reindexPendingRecordIds. PipesHub queues them again on its own within about an hour; to do it sooner, choose Start indexing in each file’s menu.
A record that isn’t in the trash answers 200 with nothing restored.

Errors say in plain words what to do. On any error, nothing is restored.

403: the trash is off, the caller lacks edit access, or the record comes from a connected app. Restore a connected app’s item in that app; it returns at the next sync.
404: the record doesn’t exist in this workspace, or was removed for good.
409, the item’s folder is also in the trash: restore the folder first.
409, another item has taken its place: the same item was added again after this one was deleted, and the new item now holds its source id. The message reads “‘report.pdf’ can’t be restored because ‘report (1).pdf’ has taken its place. … To restore this one, delete ‘report (1).pdf’ first, then try again.” Refreshing doesn’t help; the other item has to go first.
409, the item changed during the restore, for example because a second restore or the cleanup ran at the same time: refresh and try again.

POST /records/restore - Restore Several Deleted Records

Restore up to 100 records, each the way POST /record/:recordId/restore does. If several ids belong to one delete, that delete is restored once. Each id gets its own outcome in results, so one refusal doesn’t block the others, and the response is 200 whatever the outcomes.

Request
Response

Endpoint: POST /api/v1/knowledgeBase/records/restoreRequest Body:

{
  "recordIds": ["rec789012", "rec789014"]
}

Status: 200 OK

{
  "success": false,
  "restoredCount": 2,
  "failedCount": 1,
  "results": [
    { "recordId": "rec789012", "success": true, "code": 200, "message": "Restored 2 item(s).", "restoredRecords": [{ "recordId": "rec789012" }, { "recordId": "rec789013" }] },
    { "recordId": "rec789014", "success": false, "code": 409, "reason": "'a.pdf' was in 'Docs', which is also in the trash. Restore 'Docs' first, then restore 'a.pdf'." }
  ]
}

400 Bad Request when recordIds is missing, empty, or longer than 100.

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

Stream the actual file content of a record for download.

Request
Response

Endpoint: GET /api/v1/knowledgeBase/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/knowledgeBase/reindex/record/:recordIdPath Parameters:

Parameter	Type	Required	Description
recordId	string	Yes	Record UUID

Status: 200 OK

{
  "success": true,
  "message": "Reindex initiated for record rec789012",
  "recordId": "rec789012",
  "recordName": "Company Policy.pdf",
  "connector": "KB",
  "eventPublished": true,
  "userRole": "OWNER",
  "depth": 0
}

Upload Operations

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

POST /:kbId/upload - Upload to Knowledge Base or Folder

Upload files to the root of a knowledge base, or into one of its folders, creating records and folder structures as needed.

Request
Response

Endpoint: POST /api/v1/knowledgeBase/:kbId/uploadPath Parameters:

Parameter	Type	Required	Description
kbId	string	Yes	Knowledge base UUID

Query Parameters:

Parameter	Type	Required	Description
folderId	string	No	Folder to upload into. Leave it out to upload to the knowledge base root.

Request Body Parameters:

Parameter	Type	Required	Description
files	file[]	Yes	Files to upload (max 1000 files, 30MB per file by default)
files_metadata	string	No	A JSON array with one `{ "file_path": string, "last_modified": number }` entry per file, in the same order as `files`. `file_path` places the file in folders (for example `folder/report.pdf`), and `last_modified` is in milliseconds. Without it, each file is placed directly in the target under its own name.
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
A file is skipped when its name (ignoring case) and type match a file already in its destination folder, or another file in the same upload going to that folder. Files with the same name going to different folders, such as docs/Report.pdf and archive/Report.pdf, are both created. In the upload’s event stream (text/event-stream), a skipped file gets a file:failed event with reason: "DUPLICATE_NAME", stage: "index" and errors: ["A file named \"<name>\" already exists in this location; it was skipped."]. The rest of the upload goes ahead, each file with its own event (file:succeeded when added), and the stream ends with done.

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "files=@document1.pdf" \
  -F "files=@folder/document2.docx" \
  -F 'files_metadata=[{"file_path":"document1.pdf","last_modified":1714208400000},{"file_path":"folder/document2.docx","last_modified":1714208500000}]' \
  -F "isVersioned=true" \
  /api/v1/knowledgeBase/kb123456/upload

To upload into a folder instead, add its ID as a query parameter: /api/v1/knowledgeBase/kb123456/upload?folderId=folder456.

Status: 200 OKContent-Type: text/event-streamThe response is a stream of Server-Sent Events. The server sends one file:succeeded or file:failed event for each file as soon as that file is settled, then a final done event with a summary, and then closes the stream.

Event	When it’s sent	Fields in `data`
`file:succeeded`	The file was stored and its record was created. Indexing carries on in the background.	`recordId`, `fileName`, `filePath`, `extension`
`file:failed`	The file wasn’t added. The other files in the upload still go ahead.	`fileName`, `filePath`, `extension`, `errors` (a list of messages), `stage` (`upload` or `index`), plus `recordId` once one was assigned and `reason` when there is one (`EXCEEDS_SIZE_LIMIT`, `UNSUPPORTED_TYPE` or `DUPLICATE_NAME`)
`done`	The last event, once every file has its own event.	`summary` with `total`, `succeeded` and `failed` counts
`error`	Something went wrong after the stream had started. The stream closes right after it, so treat any file that didn’t get its own event as failed.	`message`

event: file:succeeded
data: {"recordId":"rec789012","fileName":"document1.pdf","filePath":"document1.pdf","extension":"pdf"}

event: file:failed
data: {"fileName":"document2.docx","filePath":"folder/document2.docx","extension":"docx","errors":["This file is larger than the 30 MB limit. Make it smaller or split it, then upload it again."],"reason":"EXCEEDS_SIZE_LIMIT","stage":"upload"}

event: done
data: {"summary":{"total":2,"succeeded":1,"failed":1}}

Lines that start with a colon, such as : keepalive (sent about once a second while work is in progress), only keep the connection open and can be ignored. Problems found before the stream starts, such as a missing token, no permission to write to the knowledge base, or a knowledge base or folder that doesn’t exist, come back as an ordinary JSON error with a 4xx status instead of a stream.

Folder Operations

Manage folder structures within knowledge bases including updates and deletion.

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

Update folder properties such as name.

Request
Response

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

{
  "success": true,
  "message": "Folder updated successfully"
}

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

Delete a folder and all its contents, including sub-folders. Nothing outside the folder is touched.

With Move Deleted Records to the Trash off (the default): PipesHub first schedules the removal of every uploaded file in the folder; if that fails, nothing is deleted and the request returns 503. A 200 means the folder and its contents are gone from the graph for good. Their embeddings and stored files are removed afterwards, with the same retries as DELETE /record/:recordId.
With Move Deleted Records to the Trash on in Labs: the folder and its contents go to the trash as one item, which can be restored from the collection’s Recently deleted page. Their uploaded files are kept until the scheduled cleanup.

Request
Response

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

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

Status: 200 OK

{
  "success": true,
  "message": "Folder deleted successfully"
}

Administrative Operations

Connector statistics, reindexing and resync are not part of the Knowledge Base API. They are in the Connectors API, under /api/v1/connectors, and take a connector instance ID:

GET /api/v1/connectors/:connectorId/stats - Indexing statistics for a connector. Needs only the ID.
POST /api/v1/connectors/:connectorId/reindex - Reindex a connector’s records. The body is optional: send { "statusFilters": [...] } to reindex only the records with those indexing statuses.
POST /api/v1/connectors/:connectorId/resync - Resync a connector’s records. The body must include connectorName (the connector’s name), and may include fullSync: true for a full resync. A request without connectorName is refused.

The Knowledge Base API’s old stats/:connector, reindex-all/connector and resync/connector endpoints no longer exist.

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",
  "summaryDocumentId": null,
  "virtualRecordId": "vr-3f2a9c1b",
  "connectorId": "kb345678"
}

This event removes the record’s search index and processed content. If the event is lost, the indexing service’s periodic orphan sweep removes them. The uploaded file is removed by a separate event, scheduled before the record is deleted.

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 {
  // Multipart form fields
  files: Express.Multer.File[];
  // JSON array, one entry per file, in the same order as files
  files_metadata?: string; // [{ "file_path": string, "last_modified": number }]

  // Optional parameters
  isVersioned?: boolean;
  recordType?: string;
  origin?: string;
}

// Each event in the text/event-stream response
type UploadStreamEvent =
  | {
      event: 'file:succeeded';
      data: {
        recordId: string;
        fileName: string;
        filePath: string;
        extension?: string;
      };
    }
  | {
      event: 'file:failed';
      data: {
        recordId?: string;
        fileName: string;
        filePath: string;
        extension?: string;
        errors: string[];
        stage: 'upload' | 'index';
        reason?: 'EXCEEDS_SIZE_LIMIT' | 'UNSUPPORTED_TYPE' | 'DUPLICATE_NAME';
      };
    }
  | {
      event: 'done';
      data: { summary: { total: number; succeeded: number; failed: number } };
    }
  | { event: 'error'; data: { message: string } };

Error Handling

All endpoints return structured error responses with specific HTTP status codes:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Kb name is required.",
    "requestId": "anon-3f2c9a7e1b6d4e0f8a5c2d9b7e4f1a6c"
  }
}

requestId identifies the request in the server’s logs, so include it when you report a problem. 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
409 Conflict - Name already in use: a file of the same type, or a folder, already has that name in that location
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 name: a file whose name and type match a file in its destination folder, or another file in the same upload going there, is skipped with a file:failed stream event, reason DUPLICATE_NAME. The rest of the upload goes ahead.

Integration with AI Indexing

When a record is created or updated, the Knowledge Base Service:

Stores the file metadata in the graph database
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 by default (set in platform settings), 1000 files per upload
Pagination: Maximum 100 items per page
Search Terms: Maximum 1000 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

Web Search

AI Providers

Connectors

Integrations

Agents

Toolsets

MCP Server

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

​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