Knowledge Base File Upload

File Document Integration

It is recommended to read the previous chapter "File Upload" first

File Upload

Endpoint

POST https://api.maiagent.ai/api/knowledge-bases/{knowledgeBasePk}/files/

Description

After upload is complete, submit file-related information to the knowledge base for recording and processing.

How to get knowledgeBasePk?

knowledgeBasePk is the unique identifier (UUID format) for the knowledge base. If you're unsure which knowledge base ID to use, you can first call the knowledge base list API to view all available knowledge bases in the organization:

curl --location 'https://api.maiagent.ai/api/knowledge-bases/' \
--header 'Authorization: Api-Key YOUR_API_KEY'

Response example:

{
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Customer Service Knowledge Base",
      "filesCount": 15
    },
    {
      "id": "8b2f1234-abcd-4567-89ef-123456789abc", 
      "name": "Product Database",
      "filesCount": 8
    }
  ]
}

Get the required knowledgeBasePk from the results[].id field, for example: 550e8400-e29b-41d4-a716-446655440000

Path Parameters

Parameter Name	Type	Required	Description
knowledgeBasePk	string	Yes	Knowledge Base ID (UUID format)

Request Parameters

Parameter Name	Type	Required	Description
files	array	Yes	Array containing file information
files[].file	string	Yes	File path in cloud storage
files[].filename	string	Yes	Desired filename for saving
files[].knowledgeBase	string	No	Knowledge Base ID (UUID format) Main purpose: This parameter is mainly used for API backward compatibility and validation (can be omitted)
files[].parser	string	No	Parser ID (UUID format)
files[].labels	array	No	Label array
files[].labels[].id	string	No	Label ID (UUID format)
files[].labels[].name	string	No	Label name
files[].rawUserDefineMetadata	object	No	User-defined metadata

Example Request

curl --location 'https://api.maiagent.ai/api/knowledge-bases/550e8400-e29b-41d4-a716-446655440000/files/' \
--header 'Authorization: Api-Key YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "files": [
        {
            "filename": "Products_example.xlsx",
            "file": "media/chatbots/chatbot-file/d83c88aa-3874-49a6-b01e-1948ae48b747.xlsx",
            "knowledgeBase": "550e8400-e29b-41d4-a716-446655440000",
            "parser": "550e8400-e29b-41d4-a716-446655440000",
            "labels": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000",
                    "name": "Product Data"
                }
            ],
            "rawUserDefineMetadata": {
                "department": "sales",
                "category": "product_catalog"
            }
        }
    ]
}'

Example Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "19ed09f0-a791-42a5-841f-c44faad2ef8b",
      "filename": "Products_example.xlsx",
      "file": "https://whizchat-media-prod-django.playma.app/media/chatbots/chatbot-file/d83c88aa-3874-49a6-b01e-1948ae48b747.xlsx",
      "fileType": "xlsx",
      "knowledgeBase": "550e8400-e29b-41d4-a716-446655440000",
      "size": 582,
      "status": {
        "code": "initial",
        "message": "File uploaded, waiting for processing"
      },
      "parser": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Excel Parser",
        "provider": {
          "name": "default",
          "version": "1.0"
        },
        "order": 1
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Product Data"
        }
      ],
      "rawUserDefineMetadata": {
        "department": "sales",
        "category": "product_catalog"
      },
      "createdAt": "1728375369000"
    }
  ]
}

Error Handling

The API may return the following error status codes and messages:

400 - Bad Request

Missing Required Fields

{
  "files": ["This field is required."],
  "filename": ["This field is required."],
  "file": ["This field is required."]
}

Fix Suggestion: Check the request JSON structure to ensure it includes the required files array and that each file item has filename and file fields.

Invalid File Format

{
  "files": [
    {
      "file": ["Invalid file path format."]
    }
  ]
}

Fix Suggestion: Verify that the file field contains the correct file path format. The path should be a complete cloud storage path, e.g., media/chatbots/chatbot-file/xxx.xlsx.

Invalid UUID Format

{
  "detail": "Invalid UUID format for knowledgeBasePk"
}

Fix Suggestion: Ensure the knowledgeBasePk in the path is a valid UUID format (e.g., 550e8400-e29b-41d4-a716-446655440000). You can first call the knowledge base list API to get the correct ID.

Duplicate File Upload

{
  "detail": "This file has already been uploaded to the knowledge base, please do not upload it again."
}

Fix Suggestion: The file (based on files[].file path) already exists in the knowledge base. If you need to re-upload the same content, please delete the old file record first; if updating file content, you need to re-upload the file to cloud storage to get a new files[].file path.

Unsupported File Type

{
  "detail": "Unsupported file type for parsing: .xyz"
}

Fix Suggestion: Check if the file extension is in the supported list (.pdf, .docx, .xlsx, .txt, .mp3, etc.). If the file format is not supported, please convert it to a supported format before uploading.

File Size Exceeds Limit

{
  "detail": "File size must be less than or equal to 104857600 bytes"
}

Fix Suggestion: File size exceeds 100MB limit. Please compress the file, split it into smaller files, or remove unnecessary content before re-uploading.

Invalid Content Type

{
  "detail": "Invalid content type for .exe, allowed: {'.pdf': 'application/pdf', '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'}"
}

Fix Suggestion: The actual format of the file doesn't match its extension, or the extension is not supported by the system. Please verify the file format is correct and use the correct extension.

File Not Provided

{
  "detail": "No file provided"
}

Fix Suggestion: File content is missing in the request. Ensure the file field contains a valid file path and the file has been properly uploaded to cloud storage.

401 - Authentication Failed

Invalid or Missing API Key

{
  "detail": "Authentication credentials were not provided."
}

Fix Suggestion: Check if the request header includes the correct Authorization field. Format should be: Authorization: Api-Key YOUR_API_KEY.

Invalid API Key Format

{
  "detail": "Invalid API key format."
}

Fix Suggestion: Verify the API Key format is correct. Check if you're using the correct prefix Api-Key instead of Bearer, and ensure the API Key itself has no extra spaces or characters.

403 - Permission Denied

Organization File Upload Limit

{
  "detail": "The organization has reached the file upload limit"
}

Fix Suggestion: Organization has reached its file upload capacity limit. Please delete unnecessary files to free up space, or contact administrator to upgrade the organization plan for more capacity.

No Permission to Access Knowledge Base

{
  "detail": "You do not have permission to access this knowledge base."
}

Fix Suggestion: Verify that the current API Key's user or organization has permission to access the knowledge base. Contact administrator to check permission settings, or use an API Key with proper permissions.

404 - Resource Not Found

Knowledge Base Not Found

{
  "detail": "Knowledge base not found."
}

Fix Suggestion: Verify the knowledgeBasePk parameter is correct. You can first call the knowledge base list API to confirm if the knowledge base exists, or check if it has been deleted.

Parser Not Found

{
  "parser": ["Invalid pk \"invalid-uuid\" - object does not exist."]
}

Fix Suggestion: Check if the provided parser ID is correct. You can omit this field to use the system default parser, or call the parser list API to get a valid parser ID.

Label Not Found

{
  "labels": ["Some label IDs do not exist in this knowledge base."]
}

Fix Suggestion: Verify that the provided label IDs exist in the specified knowledge base. You can first call the knowledge base labels list API to get valid label IDs, or remove non-existent label IDs.

413 - Request Entity Too Large

File Size Exceeds Server Limit

{
  "detail": "Request entity too large"
}

Fix Suggestion: File size exceeds server processing limit. Split the file into multiple smaller files, or use file compression tools to reduce file size before re-uploading.

422 - Unprocessable Entity

File Parsing Failed (e.g., Corrupted Excel File)

{
  "detail": "Unable to read Excel document, all following engines failed:\n- Default engine error message\n- Calamine engine error message\n- xlrd engine error message\n- openpyxl engine error message"
}

Fix Suggestion: File may be corrupted or in an abnormal format. Try opening the file with Excel or other software and re-save it, or copy the content to a new file before re-uploading.

File Encoding Issues

{
  "detail": "Unable to detect file encoding or file is corrupted"
}

Fix Suggestion: File encoding is abnormal or file is corrupted. For text files, ensure they are saved with UTF-8 encoding; for other files, check file integrity and regenerate the file.

500 - Server Error

File Processing Failed

{
  "detail": "File processing failed due to internal server error."
}

Fix Suggestion: Internal server error, usually temporary. Please try again later, if the problem persists, contact technical support and provide the time of error occurrence and file information.

Database Connection Failed

{
  "detail": "Database connection failed"
}

Fix Suggestion: Server database connection issue, usually temporary. Please try again later, if the problem persists, contact technical support.