Upload Knowledge Base

Overview

Upload document files to create a knowledge base entry. The system automatically extracts text content and performs asynchronous vectorization using embeddings, enabling semantic search and RAG (Retrieval-Augmented Generation) capabilities. Endpoint: POST /api/knowledgebase/upload Rate Limit: 3 requests per time window (Global + IP-based)

Vectorization Workflow

The upload process involves asynchronous vectorization:

Upload & Storage - File is validated and stored with metadata
Status: PENDING - Knowledge base entry is created with initial status
Status: PROCESSING - Background job extracts text and generates embeddings
Status: COMPLETED - Vectors are stored and ready for querying
Status: FAILED - If vectorization fails, use the revectorize endpoint to retry

Vectorization happens asynchronously. After upload, poll the status using GET /api/knowledgebase/ or list endpoint to check when vectorStatus becomes COMPLETED.

Request

Headers

Content-Type

string

required

Must be multipart/form-data

Body Parameters

file

required

The document file to upload. Supported formats include PDF, DOCX, DOC, TXT, and other text-extractable formats.Max file size: Check your server configuration (typically 10-50 MB)

name

string

Custom display name for the knowledge base entry. If not provided, the original filename will be used.Example: "Technical Documentation v2.1"

Response

code

integer

Response status code. 200 indicates success.

message

string

Response message. "success" on successful upload.

data

object

Upload result containing knowledge base metadata.

Show properties

integer

Unique identifier for the knowledge base entry.

name

string

Display name of the knowledge base.

originalFilename

string

Original filename of the uploaded document.

fileSize

integer

File size in bytes.

contentType

string

MIME type of the uploaded file.

Examples

cURL
cURL (no metadata)
JavaScript (Fetch)
Python

curl -X POST 'http://localhost:8080/api/knowledgebase/upload' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/path/to/document.pdf' \
  -F 'name=Technical Documentation' \
  -F 'category=Engineering'

# Upload with only the file (uses original filename)
curl -X POST 'http://localhost:8080/api/knowledgebase/upload' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@/path/to/document.pdf'

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('name', 'Technical Documentation');
formData.append('category', 'Engineering');

const response = await fetch('http://localhost:8080/api/knowledgebase/upload', {
  method: 'POST',
  body: formData
});

const result = await response.json();
console.log('Knowledge Base ID:', result.data.id);
console.log('Vector Status:', result.data.vectorStatus);

import requests

files = {'file': open('/path/to/document.pdf', 'rb')}
data = {
    'name': 'Technical Documentation',
    'category': 'Engineering'
}

response = requests.post(
    'http://localhost:8080/api/knowledgebase/upload',
    files=files,
    data=data
)

result = response.json()
print(f"Knowledge Base ID: {result['data']['id']}")
print(f"Vector Status: {result['data']['vectorStatus']}")

Response Example

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 42,
    "name": "Technical Documentation",
    "originalFilename": "document.pdf",
    "fileSize": 2457600,
    "contentType": "application/pdf",
    "category": "Engineering",
    "vectorStatus": "PENDING",
    "uploadedAt": "2026-03-10T14:30:00"
  }
}

Error Responses

code

integer

Error code (non-200 value)

message

string

Error description

Common Errors

400 Bad Request - Missing required file parameter or invalid file format
413 Payload Too Large - File exceeds maximum allowed size
429 Too Many Requests - Rate limit exceeded (3 requests per window)
500 Internal Server Error - File storage or processing failure

{
  "code": 400,
  "message": "文件不能为空"
}

Post-Upload: Check Vectorization Status

After uploading, monitor the vectorization status:

# Get detailed status
curl 'http://localhost:8080/api/knowledgebase/{id}'

Once vectorStatus is COMPLETED, the knowledge base is ready for querying. If status is FAILED, check the vectorError field and use the revectorize endpoint to retry.

Revectorize Endpoint

If vectorization fails, manually retry the process: Endpoint: POST /api/knowledgebase/{id}/revectorize Rate Limit: 2 requests per time window

Request

curl -X POST 'http://localhost:8080/api/knowledgebase/42/revectorize'

Response

{
  "code": 200,
  "message": "success",
  "data": null
}

The vectorization process will restart asynchronously. Check the status again to monitor progress.

Resume API

Interview API

Knowledge Base API

RAG Chat API

Overview

Vectorization Workflow

Request

Headers

Body Parameters

Response

Examples

Response Example

Error Responses

Common Errors

Post-Upload: Check Vectorization Status

Revectorize Endpoint

Request

Response

See Also

Build docs developers (and LLMs) love

Resume API

Interview API

Knowledge Base API

RAG Chat API

​Overview

​Vectorization Workflow

​Request

​Headers

​Body Parameters

​Response

​Examples

​Response Example

​Error Responses

​Common Errors

​Post-Upload: Check Vectorization Status

​Revectorize Endpoint

​Request

​Response

​See Also

Build docs developers (and LLMs) love

Overview

Vectorization Workflow

Request

Headers

Body Parameters

Response

Examples

Response Example

Error Responses

Common Errors

Post-Upload: Check Vectorization Status

Revectorize Endpoint

Request

Response

See Also