Overview The Knowledge Base API provides comprehensive endpoints for listing, filtering, searching, and managing knowledge base entries, including category management and statistical insights.
List All Knowledge Bases Endpoint: GET /api/knowledgebase/listRetrieve all knowledge base entries with optional filtering by vectorization status and custom sorting.
Query Parameters Sort order for the results. Values:
uploadedAt - Sort by upload date (newest first)lastAccessedAt - Sort by last access timeaccessCount - Sort by usage frequencyquestionCount - Sort by number of questions askedname - Sort alphabetically by name Default: uploadedAt (descending)Filter by vectorization status. Values: PENDING, PROCESSING, COMPLETED, FAILEDExample: ?vectorStatus=COMPLETED returns only ready-to-query knowledge bases
Response Response status code. 200 indicates success.
Array of knowledge base entries. Unique identifier for the knowledge base.
Display name of the knowledge base.
Category for organization (may be null).
Original filename of the uploaded document.
ISO 8601 timestamp of upload time.
ISO 8601 timestamp of last query/access (may be null).
Number of times this knowledge base has been accessed.
Number of questions asked against this knowledge base.
Current vectorization status. Values: PENDING, PROCESSING, COMPLETED, FAILED
Error message if vectorStatus is FAILED (null otherwise).
Number of text chunks/vectors generated (null if not vectorized).
Examples cURL - All
cURL - Filtered
JavaScript
Python
# Get all knowledge bases curl 'http://localhost:8080/api/knowledgebase/list'
# Get only completed knowledge bases, sorted by access count curl 'http://localhost:8080/api/knowledgebase/list?vectorStatus=COMPLETED&sortBy=accessCount'
// Fetch completed knowledge bases sorted by usage const response = await fetch ( 'http://localhost:8080/api/knowledgebase/list?vectorStatus=COMPLETED&sortBy=questionCount' ); const result = await response . json (); result . data . forEach ( kb => { console . log ( ` ${ kb . name } - ${ kb . questionCount } questions, ${ kb . chunkCount } chunks` ); });
import requests # Get failed vectorizations for troubleshooting response = requests.get( 'http://localhost:8080/api/knowledgebase/list' , params = { 'vectorStatus' : 'FAILED' } ) for kb in response.json()[ 'data' ]: print ( f " { kb[ 'name' ] } : { kb[ 'vectorError' ] } " )
Response Example { "code" : 200 , "message" : "success" , "data" : [ { "id" : 1 , "name" : "Technical Documentation" , "category" : "Engineering" , "originalFilename" : "tech-docs-v2.pdf" , "fileSize" : 2457600 , "contentType" : "application/pdf" , "uploadedAt" : "2026-03-10T14:30:00" , "lastAccessedAt" : "2026-03-10T16:45:30" , "accessCount" : 12 , "questionCount" : 45 , "vectorStatus" : "COMPLETED" , "vectorError" : null , "chunkCount" : 156 }, { "id" : 2 , "name" : "API Reference Guide" , "category" : "Engineering" , "originalFilename" : "api-reference.docx" , "fileSize" : 1048576 , "contentType" : "application/vnd.openxmlformats-officedocument.wordprocessingml.document" , "uploadedAt" : "2026-03-09T09:15:00" , "lastAccessedAt" : "2026-03-10T14:20:10" , "accessCount" : 8 , "questionCount" : 23 , "vectorStatus" : "COMPLETED" , "vectorError" : null , "chunkCount" : 89 }, { "id" : 3 , "name" : "User Manual" , "category" : null , "originalFilename" : "user-manual.pdf" , "fileSize" : 3145728 , "contentType" : "application/pdf" , "uploadedAt" : "2026-03-10T11:00:00" , "lastAccessedAt" : null , "accessCount" : 0 , "questionCount" : 0 , "vectorStatus" : "PROCESSING" , "vectorError" : null , "chunkCount" : null } ] }
Get Knowledge Base by ID Endpoint: GET /api/knowledgebase/{id}Retrieve detailed information about a specific knowledge base.
Path Parameters Knowledge base unique identifier.
Examples curl 'http://localhost:8080/api/knowledgebase/1'
Response { "code" : 200 , "message" : "success" , "data" : { "id" : 1 , "name" : "Technical Documentation" , "category" : "Engineering" , "originalFilename" : "tech-docs-v2.pdf" , "fileSize" : 2457600 , "contentType" : "application/pdf" , "uploadedAt" : "2026-03-10T14:30:00" , "lastAccessedAt" : "2026-03-10T16:45:30" , "accessCount" : 12 , "questionCount" : 45 , "vectorStatus" : "COMPLETED" , "vectorError" : null , "chunkCount" : 156 } }
Error Response { "code" : 404 , "message" : "知识库不存在" }
Search Knowledge Bases Endpoint: GET /api/knowledgebase/searchSearch knowledge bases by name or filename using keyword matching.
Query Parameters Search keyword to match against knowledge base names and filenames. Example: ?keyword=documentation
Examples curl 'http://localhost:8080/api/knowledgebase/search?keyword=documentation'
const keyword = 'api' ; const response = await fetch ( `http://localhost:8080/api/knowledgebase/search?keyword= ${ encodeURIComponent ( keyword ) } ` ); const result = await response . json (); console . log ( `Found ${ result . data . length } matching knowledge bases` );
Response Returns the same structure as the list endpoint, filtered by keyword:
{ "code" : 200 , "message" : "success" , "data" : [ { "id" : 1 , "name" : "Technical Documentation" , "originalFilename" : "tech-docs-v2.pdf" , // ... other fields } ] }
Category Management Organize knowledge bases using categories for better organization and filtering.
Get All Categories Endpoint: GET /api/knowledgebase/categoriesRetrieve a list of all unique categories in use.
curl 'http://localhost:8080/api/knowledgebase/categories'
Response: { "code" : 200 , "message" : "success" , "data" : [ "Engineering" , "Sales" , "HR" , "Legal" ] }
Get Knowledge Bases by Category Endpoint: GET /api/knowledgebase/category/{category}Retrieve all knowledge bases in a specific category.
Category name (case-sensitive).
Example: curl 'http://localhost:8080/api/knowledgebase/category/Engineering'
Response: { "code" : 200 , "message" : "success" , "data" : [ // Array of knowledge bases in the "Engineering" category ] }
Get Uncategorized Knowledge Bases Endpoint: GET /api/knowledgebase/uncategorizedRetrieve all knowledge bases without a category assigned.
curl 'http://localhost:8080/api/knowledgebase/uncategorized'
Update Knowledge Base Category Endpoint: PUT /api/knowledgebase/{id}/categoryAssign or update the category for a knowledge base.
New category name. Pass null or empty string to remove category.
Example: curl -X PUT 'http://localhost:8080/api/knowledgebase/1/category' \ -H 'Content-Type: application/json' \ -d '{"category": "Engineering"}'
await fetch ( 'http://localhost:8080/api/knowledgebase/1/category' , { method: 'PUT' , headers: { 'Content-Type' : 'application/json' }, body: JSON . stringify ({ category: 'Engineering' }) });
Response: { "code" : 200 , "message" : "success" , "data" : null }
Statistics Endpoint: GET /api/knowledgebase/statsGet aggregate statistics about all knowledge bases.
Response Total number of knowledge bases.
Total questions asked across all knowledge bases.
Total access count across all knowledge bases.
Number of knowledge bases with vectorization completed.
Number of knowledge bases currently being processed.
Example curl 'http://localhost:8080/api/knowledgebase/stats'
Response: { "code" : 200 , "message" : "success" , "data" : { "totalCount" : 15 , "totalQuestionCount" : 342 , "totalAccessCount" : 128 , "completedCount" : 12 , "processingCount" : 2 } }
Understanding Vector Status The vectorStatus field indicates the readiness of a knowledge base for querying:
Status Description Can Query? Actions PENDINGQueued for vectorization No Wait for processing to start PROCESSINGCurrently being vectorized No Monitor until completion COMPLETEDReady for queries Yes Query normally FAILEDVectorization error occurred No Check vectorError and revectorize
Only knowledge bases with vectorStatus: COMPLETED can be queried. Use the list endpoint with ?vectorStatus=COMPLETED to get query-ready knowledge bases.
Common Use Cases Building a Knowledge Base Selector // Fetch only completed knowledge bases for a query UI const response = await fetch ( 'http://localhost:8080/api/knowledgebase/list?vectorStatus=COMPLETED&sortBy=name' ); const knowledgeBases = await response . json (); // Populate a dropdown/selector knowledgeBases . data . forEach ( kb => { const option = document . createElement ( 'option' ); option . value = kb . id ; option . text = ` ${ kb . name } ( ${ kb . chunkCount } chunks)` ; selector . appendChild ( option ); });
Monitoring Vectorization Progress import requests import time def wait_for_vectorization ( kb_id , timeout = 300 ): """Poll until knowledge base vectorization completes.""" start = time.time() while time.time() - start < timeout: response = requests.get( f 'http://localhost:8080/api/knowledgebase/ { kb_id } ' ) kb = response.json()[ 'data' ] status = kb[ 'vectorStatus' ] if status == 'COMPLETED' : print ( f "Vectorization complete: { kb[ 'chunkCount' ] } chunks" ) return True elif status == 'FAILED' : print ( f "Vectorization failed: { kb[ 'vectorError' ] } " ) return False print ( f "Status: { status } , waiting..." ) time.sleep( 5 ) print ( "Timeout waiting for vectorization" ) return False
Organizing by Category // Group knowledge bases by category const response = await fetch ( 'http://localhost:8080/api/knowledgebase/list' ); const knowledgeBases = await response . json (); const byCategory = knowledgeBases . data . reduce (( acc , kb ) => { const category = kb . category || 'Uncategorized' ; if ( ! acc [ category ]) acc [ category ] = []; acc [ category ]. push ( kb ); return acc ; }, {}); console . log ( byCategory ); // { "Engineering": [...], "Sales": [...], "Uncategorized": [...] }
See Also 