Skip to main content
The Knowledge module manages the RAG knowledge bases that power all AI features. Each knowledge base stores raw documents, processed content, and a vector index.
File processing runs as a background task. Use the progress endpoint or WebSocket to track initialization status.

​
Endpoints

MethodPathDescription
GET/api/v1/knowledge/healthHealth check
GET/api/v1/knowledge/listList all knowledge bases
POST/api/v1/knowledge/createCreate a new knowledge base
GET/api/v1/knowledge/defaultGet the default knowledge base
PUT/api/v1/knowledge/default/{kb_name}Set the default knowledge base
GET/api/v1/knowledge/rag-providersList available RAG providers
GET/api/v1/knowledge/configsGet all KB configurations
POST/api/v1/knowledge/configs/syncSync configs from metadata files
GET/api/v1/knowledge/{kb_name}Get knowledge base details
DELETE/api/v1/knowledge/{kb_name}Delete a knowledge base
GET/api/v1/knowledge/{kb_name}/configGet KB-specific config
PUT/api/v1/knowledge/{kb_name}/configUpdate KB-specific config
POST/api/v1/knowledge/{kb_name}/uploadUpload documents to a KB
GET/api/v1/knowledge/{kb_name}/progressGet initialization progress
POST/api/v1/knowledge/{kb_name}/progress/clearClear a stuck progress state
WS/api/v1/knowledge/{kb_name}/progress/wsStream progress updates
POST/api/v1/knowledge/{kb_name}/link-folderLink a local folder
GET/api/v1/knowledge/{kb_name}/linked-foldersList linked folders
DELETE/api/v1/knowledge/{kb_name}/linked-folders/{folder_id}Unlink a folder
POST/api/v1/knowledge/{kb_name}/sync-folder/{folder_id}Sync files from a linked folder

​
GET /api/v1/knowledge/health

Returns the health status of the knowledge base manager. 
curl http://localhost:8001/api/v1/knowledge/health

{
  "status": "ok",
  "config_file": "/path/to/kb_config.json",
  "config_exists": true,
  "base_dir": "/path/to/knowledge_bases",
  "base_dir_exists": true,
  "knowledge_bases_count": 2
}

​
GET /api/v1/knowledge/list

List all available knowledge bases with summary statistics. 
curl http://localhost:8001/api/v1/knowledge/list

[
  {
    "name": "ai_textbook",
    "is_default": true,
    "statistics": {
      "raw_documents": 12,
      "images": 4,
      "content_lists": 8,
      "rag_initialized": true
    }
  }
]

​
POST /api/v1/knowledge/create

Create a new knowledge base and initialize it with uploaded files. Processing runs in the background.

​
Request body (multipart/form-data)

​
name
string
required
Name for the new knowledge base. Must be unique.
​
files
file[]
required
One or more documents to include.
​
rag_provider
string
default:"raganything"
RAG provider to use for indexing.

​
Response

​
message
string
Confirmation message.
​
name
string
Name of the created knowledge base.
​
files
string[]
List of uploaded file names.
curl -X POST http://localhost:8001/api/v1/knowledge/create \
  -F "name=my_kb" \
  -F "rag_provider=raganything" \
  -F "[email protected]" \
  -F "[email protected]"

{
  "message": "Knowledge base 'my_kb' created. Processing 2 files in background.",
  "name": "my_kb",
  "files": ["chapter1.pdf", "chapter2.pdf"]
}

​
GET /api/v1/knowledge/default

Get the name of the default knowledge base. 
curl http://localhost:8001/api/v1/knowledge/default

{ "default_kb": "ai_textbook" }

​
PUT /api/v1/knowledge/default/{kb_name}

Set a knowledge base as the default.
​
kb_name
string
required
Knowledge base name.
curl -X PUT http://localhost:8001/api/v1/knowledge/default/my_kb

{ "status": "success", "default_kb": "my_kb" }

​
GET /api/v1/knowledge/{kb_name}

Get detailed information about a specific knowledge base.
​
kb_name
string
required
Knowledge base name.
curl http://localhost:8001/api/v1/knowledge/ai_textbook
Returns 404 if the knowledge base is not found.

​
DELETE /api/v1/knowledge/{kb_name}

Permanently delete a knowledge base and all its data.
​
kb_name
string
required
Knowledge base name.
This action is irreversible. All documents and vector indexes in the knowledge base will be deleted.
curl -X DELETE http://localhost:8001/api/v1/knowledge/my_kb

{ "message": "Knowledge base 'my_kb' deleted successfully" }

​
POST /api/v1/knowledge/{kb_name}/upload

Upload additional documents to an existing knowledge base. Processing runs in the background.
​
kb_name
string
required
Knowledge base name.

​
Request body (multipart/form-data)

​
files
file[]
required
One or more documents to add.
​
rag_provider
string
Override the RAG provider for this upload. Defaults to the KB’s configured provider.
curl -X POST http://localhost:8001/api/v1/knowledge/my_kb/upload \
  -F "files=@new_chapter.pdf"

{
  "message": "Uploaded 1 files. Processing in background.",
  "files": ["new_chapter.pdf"]
}

​
GET /api/v1/knowledge/{kb_name}/progress

Poll the current initialization or upload progress for a knowledge base.
​
kb_name
string
required
Knowledge base name.
curl http://localhost:8001/api/v1/knowledge/my_kb/progress

{
  "stage": "processing_documents",
  "message": "Processing 2 files...",
  "percent": 50,
  "current": 1,
  "total": 2,
  "timestamp": "2025-01-01T12:00:00"
}
Returns { "status": "not_started" } if initialization has not begun.

​
WS /api/v1/knowledge/{kb_name}/progress/ws

Stream real-time progress updates for knowledge base initialization. Connect after calling the create or upload endpoint.
​
kb_name
string
required
Knowledge base name.
Messages use type: "progress" with a data object, or type: "error". 
const ws = new WebSocket('ws://localhost:8001/api/v1/knowledge/my_kb/progress/ws');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'progress') {
    console.log(msg.data.stage, msg.data.percent + '%');
  }
};
The connection closes automatically when the stage reaches completed or error.

​
POST /api/v1/knowledge/{kb_name}/progress/clear

Clear a stuck progress state. Useful if a previous initialization failed and left stale progress data.
​
kb_name
string
required
Knowledge base name.
curl -X POST http://localhost:8001/api/v1/knowledge/my_kb/progress/clear

{ "status": "success", "message": "Progress cleared for my_kb" }

​
GET /api/v1/knowledge/rag-providers

List available RAG providers. 
curl http://localhost:8001/api/v1/knowledge/rag-providers

{ "providers": ["raganything", "lightrag"] }

​
Folder linking

You can link a local folder (e.g. a folder synced from SharePoint or Google Drive) to a knowledge base. DeepTutor will detect new and modified files in the folder and process them.

​
POST /api/v1/knowledge/{kb_name}/link-folder

​
kb_name
string
required
Knowledge base name.
​
folder_path
string
required
Absolute path to the local folder. Supports ~ expansion and relative paths resolved from the server working directory.
curl -X POST http://localhost:8001/api/v1/knowledge/my_kb/link-folder \
  -H "Content-Type: application/json" \
  -d '{ "folder_path": "/Users/name/Documents/lecture_notes" }'

{
  "id": "folder_abc123",
  "path": "/Users/name/Documents/lecture_notes",
  "added_at": "2025-01-01T12:00:00",
  "file_count": 5
}

​
GET /api/v1/knowledge/{kb_name}/linked-folders

List all folders linked to a knowledge base. 
curl http://localhost:8001/api/v1/knowledge/my_kb/linked-folders

​
DELETE /api/v1/knowledge/{kb_name}/linked-folders/{folder_id}

Remove a folder link (does not delete the actual folder or already-processed documents).
​
folder_id
string
required
Folder link identifier returned by the link-folder endpoint.

​
POST /api/v1/knowledge/{kb_name}/sync-folder/{folder_id}

Scan the linked folder for new or modified files and process them into the knowledge base.
​
folder_id
string
required
Folder link identifier.
curl -X POST http://localhost:8001/api/v1/knowledge/my_kb/sync-folder/folder_abc123

{
  "message": "Syncing 3 files from linked folder",
  "folder_path": "/Users/name/Documents/lecture_notes",
  "new_files": 2,
  "modified_files": 1,
  "file_count": 3
}
If no changes are detected, returns { "message": "No new or modified files to sync", "files": [], "file_count": 0 }.

Build docs developers (and LLMs) love

Get started for freeTalk to us