File upload knowledge base

File document integration

It is recommended to first read the previous chapter “File Upload”

File upload

Endpoint

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

Description

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

How to obtain knowledgeBasePk?

knowledgeBasePk Is the unique identifier of the knowledge base (UUID format). If you are not sure which knowledge base ID to use, you can call the knowledge bases list API first to see 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
    }
  ]
}

From results[].id field obtain the required knowledgeBasePk, 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	Path of the file stored in cloud storage
files[].filename	string	Yes	Filename the user wants to save
files[].knowledgeBase	string	No	Knowledge base ID (UUID format) Primary purpose: This parameter is mainly used for API backward compatibility and validation purposes (this parameter can be omitted)
files[].parser	string	No	Parser ID (UUID format)
files[].labels	array	No	Array of labels
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"
            }
        }
    ]
}'

Response example

{
  "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 status codes and error messages:

400 - Bad request

Required fields missing

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

Fix suggestion: Check the request JSON structure and 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: Make sure the file field contains the correct file path format. The path should be a full cloud storage path, for example: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 (for example: 550e8400-e29b-41d4-a716-446655440000). You can call the knowledge bases list API first to get the correct ID.

File already uploaded

{
  "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 file, delete the old file record first; if you are updating the file content, re-upload the file to cloud storage to obtain a new files[].file path.

Unsupported file type

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

Fix suggestion: Check whether the file extension is in the supported list (e.g., .pdf, .docx, .xlsx, .txt, .mp3, etc.). If the file format is not supported, convert it to a supported format and re-upload.

File size exceeds limit

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

Fix suggestion: The file size exceeds the 100MB limit. Please compress the file, split it into multiple smaller files, or remove unnecessary content from the file and re-upload.

Invalid file content type

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

Fix suggestion: The actual file format does not match the extension, or the extension is not supported by the system. Please verify the file format is correct and use the correct file extension.

File not provided

{
  "detail": "No file provided"
}

Fix suggestion: The request is missing file content. Verify the file field contains a valid file path and that the file has been correctly uploaded to cloud storage.

401 - Authentication failed

API Key invalid or missing

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

Fix suggestion: Check whether the request header includes the correct Authorization field. The format should be:Authorization: Api-Key YOUR_API_KEY.

API Key format error

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

Fix suggestion: Ensure the API Key format is correct. Check whether the correct prefix Api-Key is used instead of Bearer, and ensure the API Key itself has no extra spaces or characters.

403 - Forbidden

Organization file upload limit

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

Fix suggestion: The organization has reached its file upload capacity limit. Delete unnecessary files to free up space, or contact an administrator to upgrade the organization plan for more capacity.

No permission to access the knowledge base

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

Fix suggestion: Ensure the user or organization associated with the current API Key has permission to access the knowledge base. Contact an administrator to check permission settings or use an API Key that has permission.

404 - Resource not found

Knowledge base not found

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

Fix suggestion: Make sure the knowledgeBasePk Parameters are correct. You can call the knowledge bases list API first to confirm whether the knowledge base exists, or check whether it has been deleted.

Parser not found

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

Fix suggestion: Check whether 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 call the knowledge base labels list API to get valid label IDs, or remove label IDs that do not exist.

413 - Request entity too large

File size exceeds server limit

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

Fix suggestion: The file size exceeds the server's allowable limit. Split the file into multiple smaller files or use file compression tools to reduce the file size and re-upload.

422 - Unprocessable entity

File parsing failed (e.g., corrupted Excel file)

{
  "detail": "Unable to read Excel document, attempts with the following engines all failed:\n- default engine error message\n- calamine engine error message\n- xlrd engine error message\n- openpyxl engine error message"
}

Fix suggestion: The file may be corrupted or have an abnormal format. Try opening the file with Excel or other software and re-saving it, or copy the contents into a new file and re-upload.

File encoding issues

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

Fix suggestion: The file encoding is abnormal or the file is corrupted. For text files, ensure they are saved using 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 issue persists, contact technical support and provide the time the error occurred and file information.

Database connection failed

{
  "detail": "Database connection failed"
}

Fix suggestion: Server database connection issue, usually temporary. Please try again later. If the issue persists, contact technical support.