Ctrlk
註冊/登入
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Using Knowledge Base—Creation and Interaction

This guide explains how to use the public REST API to manage knowledge base files, along with integration examples.

Overview

MaiAgent provides developers with the ability to manage knowledge base files through the API. Developers can perform the following operations on knowledge bases within their workspace:

  • Upload new files to a knowledge base

  • Query all files in a knowledge base

  • Update existing file information

  • Delete individual or batch files

Important Reminder

When using the API, all operations require a valid API Key for authentication. Make sure your API Key has the appropriate permissions.

Knowledge Base Operations

Creating a Knowledge Base

Before using a knowledge base, you must first create at least one knowledge base. When creating a knowledge base, you must specify the Embedding Model, Reranker Model, knowledge base name, and the AI assistants that can use this knowledge base.

You can specify the above configuration via scripts. Here is an example request for creating a knowledge base:

{
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000", // Embedding Model ID
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000", // Reranker Model ID
  "name": "Internal Training Manual",
  "description": "This knowledge base is for internal training use, containing user manuals, product manuals, and troubleshooting guides, for new employee onboarding only",
  "numberOfRetrievedChunks": 12, //  Number of retrieved chunks
  "enableRerank": true,
  "chatbots": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

After submitting and receiving an HTTPS response, the creation is successful and you can begin operating on this knowledge base.

Using an ID to Operate on a Single Knowledge Base

Before you start managing files in a single knowledge base, you need to obtain the knowledge base's unique identifier (id).

How to obtain the knowledge base id?

  1. Get the id of a newly created knowledge base

For a knowledge base just created via script, the HTTPS response returned after creation will contain the id among other fields. The id in the response represents the knowledge base's id value.

  1. Get the id of an existing knowledge base

You can obtain the corresponding knowledge base id from the response of the "list all knowledge bases" endpoint. See the API documentation: Knowledge Bases (New)

Querying Knowledge Base Files

The Query Files endpoint can be used to list all files in a knowledge base. You can use query parameters to filter by specific type, status, or search for specific keywords. Place the knowledge base id you want to query into the {knowledgeBasePK} position in the endpoint to query a specific knowledge base.

Endpoint

File Status Values (key: Status)

You can check the processing status of each file from the endpoint response. The possible statuses are listed below. A status of done indicates the file has been processed and is available for LLM retrieval:

  • initial - Initialized

  • processing - Processing

  • done - Complete

  • deleting - Deleting

  • deleted - Deleted

  • failed - Failed

This endpoint allows filtering by file type using the fileType parameter, such as pdf, docx, txt, xlsx, etc.

Example: Query All PDF Files

File Operations

Uploading Files to a Knowledge Base

Endpoint

You can use this endpoint to upload files directly to a knowledge base. During upload, you can specify file information through parameters such as:

  • rawUserDefineMetadata: Document metadata

  • labels: Document classification labels

Example: Upload a Single Document -- Product Manual

Request structure example

You can specify the file content and target knowledge base.

The response will contain the newly created file object, including the system-generated file ID.

You can also upload multiple files to different knowledge bases.

Example: Upload Multiple Documents to Different Knowledge Bases

Please note: Individual files must not exceed 100MB, otherwise they cannot be processed correctly and the HTTP response will return an error message.

Updating Existing File Information

You can use the Update File Information endpoint to modify information for an uploaded file, such as the filename, labels, or custom metadata. If a file has been updated, you do not need to re-upload it -- you can modify the information directly via script.

Endpoint

Request example

Deleting Files

Deleting a Single File

Endpoint

Use this endpoint to remove a single file from a knowledge base. Specify the file id to delete in the {id} position of the endpoint.

Example

After successful deletion, the API will return a 204 status code. The file will no longer be available for LLM reference in responses.

Batch Deleting Files

To delete multiple files at once, use the Batch Delete Files endpoint for improved management efficiency.

Endpoint

Request example

You can pass in multiple file id values to have the system delete multiple files at once.

This endpoint can only batch delete files within a single knowledge base. Cross-knowledge-base batch deletion is not supported.

Use Cases

The Knowledge Base File Management API has many practical use cases, such as:

1. Automated Document Updates

When your product documentation is updated in a Git repository, you can use a CI/CD pipeline to automatically upload the latest version to the knowledge base. This ensures the AI assistant always has access to the most current product information.

Example Workflow

1

Detect a document update commit

2

Check if the file already exists

Use the MaiAgent API to query whether a matching file exists in the knowledge base.

3

Update/Upload file

If the file exists, use the partial update endpoint to update it; if it does not exist, use the upload file endpoint to upload the new file.

2. Content Management System Integration

If you use MaiAgent as a Content Management System (CMS), you can build a management interface that allows content editors to:

  • Upload new content files

  • Organize content using labels

  • Search and filter specific types of content

  • Batch delete expired content

Summary

MaiAgent's public REST API enables you to manage knowledge base files more efficiently, including:

  • Creating knowledge bases

  • Querying and filtering files

  • Uploading new files

  • Updating file information

  • Deleting individual or batch files

Next Steps

PreviousPresigned File Upload Mode
NextWeb Chat Embed & SDK

Last updated

Was this helpful?