> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/api-doc-en/preparation/readme.md).

# Overview

## Document Overview

Documentation of API endpoints of MaiAgent

## API Categories and Endpoint List

### AI Assistant

* `POST` [api/chatbots](https://docs.maiagent.ai/api/ai-zhu-li#-ai-): Create a new AI assistant
* `GET` [api/chatbot-settings](https://docs.maiagent.ai/api/ai-zhu-li#-ai-): List available settings for AI assistants
* `GET` [api/embedding-models](https://docs.maiagent.ai/api/ai-zhu-li#-embedding-model): List Embedding Models
* `GET` [api/reranker-models](https://docs.maiagent.ai/api/ai-zhu-li#-reranker-model): List Reranker Models
* `GET` [api/chatbots](https://docs.maiagent.ai/api/ai-zhu-li#-ai-): Get a list of AI assistants
* `GET` [api/chatbots/{id}](https://docs.maiagent.ai/api/ai-zhu-li#-ai-): Get a specific AI assistant
* `PUT` [api/chatbots/{id}](https://docs.maiagent.ai/api/ai-zhu-li#-ai-): Update an AI assistant
* `PATCH` [api/chatbots/{id}](https://docs.maiagent.ai/api/ai-zhu-li#-ai-): Partially update an AI assistant
* `DELETE` [api/chatbots/{id}](https://docs.maiagent.ai/api/ai-zhu-li#-ai-): Delete an AI assistant

### Attachments and Files

* `POST` [api/attachments-upload](https://docs.maiagent.ai/api/fu-jian-yu-dang-an#-): Create a new attachment (integrated)
* `POST` [api/upload-presigned-url](https://docs.maiagent.ai/api/fu-jian-yu-dang-an#-url-): Get a presigned URL for file upload (create/get)
* `POST` [api/attachments](https://docs.maiagent.ai/api/fu-jian-yu-dang-an#presigned-): Upload attachment via Presigned URL
* `POST` [api/conversations/{conversationPk}/attachments](https://docs.maiagent.ai/api/fu-jian-yu-dang-an#): Create a conversation attachment

### Knowledge Base (New)

* `POST` [api/knowledge-bases](https://docs.maiagent.ai/api/知識庫（新版）#): Create a knowledge base
* `GET` [api/knowledge-bases](https://docs.maiagent.ai/api/知識庫（新版）#): List all knowledge bases
* `GET` [api/knowledge-bases/{id}](https://docs.maiagent.ai/api/知識庫（新版）#): Get details of a specific knowledge base
* `GET` [api/knowledge-bases/{id}/search](https://docs.maiagent.ai/api/知識庫（新版）#): Search the content of a specific knowledge base
* `PUT` [api/knowledge-bases/{id}](https://docs.maiagent.ai/api/知識庫（新版）#): Update a knowledge base
* `PATCH` [api/knowledge-bases/{id}](https://docs.maiagent.ai/api/知識庫（新版）#): Partially update a knowledge base
* `DELETE` [api/knowledge-bases/{id}](https://docs.maiagent.ai/api/知識庫（新版）#): Delete a knowledge base
* `POST` [api/knowledge-bases/{knowledgeBasePk}/labels](https://docs.maiagent.ai/api/知識庫（新版）#): Create a new label
* `GET` [api/knowledge-bases/{knowledgeBasePk}/labels](https://docs.maiagent.ai/api/知識庫（新版）#): List labels in a knowledge base
* `GET` [api/knowledge-bases/{knowledgeBasePk}/labels/{id}](https://docs.maiagent.ai/api/知識庫（新版）#): Get details of a specific label
* `PUT` [api/knowledge-bases/{knowledgeBasePk}/labels/{id}](https://docs.maiagent.ai/api/知識庫（新版）#): Update a label
* `PATCH` [api/knowledge-bases/{knowledgeBasePk}/labels/{id}](https://docs.maiagent.ai/api/知識庫（新版）#): Partially update a label
* `DELETE` [api/knowledge-bases/{knowledgeBasePk}/labels/{id}](https://docs.maiagent.ai/api/知識庫（新版）#): Delete a label
* `POST` [api/knowledge-bases/{knowledgeBasePk}/files](https://docs.maiagent.ai/api/知識庫（新版）#): Upload a file to the knowledge base
* `POST` [api/knowledge-bases/{knowledgeBasePk}/files/{id}/update-metadata](https://docs.maiagent.ai/api/知識庫（新版）#): Update file metadata
* `POST` [api/knowledge-bases/{knowledgeBasePk}/files/batch-delete](https://docs.maiagent.ai/api/知識庫（新版）#): Batch delete files
* `GET` [api/knowledge-bases/{knowledgeBasePk}/files](https://docs.maiagent.ai/api/知識庫（新版）#): List files in the knowledge base
* `GET` [api/knowledge-bases/{knowledgeBasePk}/files/{id}](https://docs.maiagent.ai/api/知識庫（新版）#): Get details of a specific file
* `GET` [api/knowledge-bases/{knowledgeBasePk}/text-nodes](https://docs.maiagent.ai/api/知識庫（新版）#): List text nodes of a specific file in the knowledge base
* `GET` [api/knowledge-bases/{knowledgeBasePk}/text-nodes/{id}](https://docs.maiagent.ai/api/知識庫（新版）#): Get details of a specific text node
* `PUT` [api/knowledge-bases/{knowledgeBasePk}/files/{id}](https://docs.maiagent.ai/api/知識庫（新版）#): Update file information
* `PATCH` [api/knowledge-bases/{knowledgeBasePk}/files/{id}](https://docs.maiagent.ai/api/知識庫（新版）#): Partially update a file
* `DELETE` [api/knowledge-bases/{knowledgeBasePk}/files/{id}](https://docs.maiagent.ai/api/知識庫（新版）#): Delete a file
* `POST` [api/knowledge-bases/{knowledgeBasePk}/faqs](https://docs.maiagent.ai/api/知識庫（新版）#-faq): Create a new FAQ
* `POST` [api/knowledge-bases/{knowledgeBasePk}/faqs/{id}/update-metadata](https://docs.maiagent.ai/api/知識庫（新版）#-faq-): Update FAQ metadata
* `POST` [api/knowledge-bases/{knowledgeBasePk}/faqs/batch-delete](https://docs.maiagent.ai/api/知識庫（新版）#-faq): Batch delete FAQs
* `GET` [api/knowledge-bases/{knowledgeBasePk}/faqs](https://docs.maiagent.ai/api/知識庫（新版）#-faq): List all FAQs for a specific knowledge base
* `GET` [api/knowledge-bases/{knowledgeBasePk}/faqs/{id}](https://docs.maiagent.ai/api/知識庫（新版）#-faq-): Get details of a specific FAQ
* `PUT` [api/knowledge-bases/{knowledgeBasePk}/faqs/{id}](https://docs.maiagent.ai/api/知識庫（新版）#-faq): Update an FAQ
* `PATCH` [api/knowledge-bases/{knowledgeBasePk}/faqs/{id}](https://docs.maiagent.ai/api/知識庫（新版）#-faq): Partially update an FAQ
* `DELETE` [api/knowledge-bases/{knowledgeBasePk}/faqs/{id}](https://docs.maiagent.ai/api/知識庫（新版）#-faq): Delete an FAQ

### Knowledge Base (Legacy)

* `POST` [api/chatbots/{chatbotPk}/files](https://docs.maiagent.ai/api/知識庫（舊版）#): Upload a new knowledge base file
* `GET` [api/chatbots/{chatbotPk}/files](https://docs.maiagent.ai/api/知識庫（舊版）#): Get a list of knowledge base files
* `GET` [api/chatbots/{chatbotPk}/files/{id}](https://docs.maiagent.ai/api/知識庫（舊版）#): Get a specific knowledge base file
* `PUT` [api/chatbots/{chatbotPk}/files/{id}](https://docs.maiagent.ai/api/知識庫（舊版）#): Update a knowledge base file
* `DELETE` [api/chatbots/{chatbotPk}/files/{id}](https://docs.maiagent.ai/api/知識庫（舊版）#): Delete a knowledge base file
* `POST` [api/chatbots/{chatbotPk}/files/batch-delete](https://docs.maiagent.ai/api/知識庫（舊版）#): Batch delete knowledge base files
* `POST` [api/chatbots/{chatbotPk}/faqs](https://docs.maiagent.ai/api/知識庫（舊版）#-faq): Create a new FAQ
* `GET` [api/chatbots/{chatbotPk}/faqs](https://docs.maiagent.ai/api/知識庫（舊版）#-faq-): Get a list of FAQs
* `GET` [api/chatbots/{chatbotPk}/faqs/{id}](https://docs.maiagent.ai/api/知識庫（舊版）#-faq): Get a specific FAQ
* `PUT` [api/chatbots/{chatbotPk}/faqs/{id}](https://docs.maiagent.ai/api/知識庫（舊版）#-faq): Update an FAQ
* `DELETE` [api/chatbots/{chatbotPk}/faqs/{id}](https://docs.maiagent.ai/api/知識庫（舊版）#-faq): Delete an FAQ
* `POST` [api/chatbots/{chatbotPk}/faqs/batch-delete](https://docs.maiagent.ai/api/知識庫（舊版）#-faq): Batch delete FAQs
* `GET` [api/chatbot-text-nodes](https://docs.maiagent.ai/api/知識庫（舊版）#-ai-): Get text nodes for all files of an AI assistant
* `GET` [api/chatbot-text-nodes/{id}](https://docs.maiagent.ai/api/知識庫（舊版）#-ai-): Get text nodes for a specific file of an AI assistant
* `POST` [api/chatbots/{id}/search](https://docs.maiagent.ai/api/知識庫（舊版）#): Search test
* `GET` [api/parsers/supported-file-types](https://docs.maiagent.ai/api/知識庫（舊版）#): List supported parsers for file types

### Conversations and Messages

* `POST` [api/chatbots/{chatbotId}/completions](https://docs.maiagent.ai/api/dui-hua-yu-xun-xi#-): Send a message (stream)
* `POST` [api/messages](https://docs.maiagent.ai/api/dui-hua-yu-xun-xi#-): Send a message (create)
* `POST` [api/conversations](https://docs.maiagent.ai/api/dui-hua-yu-xun-xi#): Create a new conversation
* `GET` [api/messages](https://docs.maiagent.ai/api/dui-hua-yu-xun-xi#): Get a list of messages
* `GET` [api/messages/{id}](https://docs.maiagent.ai/api/dui-hua-yu-xun-xi#): Get a specific message
* `GET` [api/conversations](https://docs.maiagent.ai/api/dui-hua-yu-xun-xi#): Get a list of conversations
* `GET` [api/conversations/{id}](https://docs.maiagent.ai/api/dui-hua-yu-xun-xi#): Get a specific conversation
* `GET` [api/chatbots/{chatbotPk}/records](https://docs.maiagent.ai/api/dui-hua-yu-xun-xi#-ai-): Get AI assistant conversation records
* `GET` [api/chatbots/{chatbotPk}/records/export-excel](https://docs.maiagent.ai/api/dui-hua-yu-xun-xi#-excel-): Export conversation records as an Excel file

### Conversation Widget

* `GET` [api/web-chats/{id}](https://docs.maiagent.ai/api/dui-hua-widget#-web-chat): Get a specific Web Chat
* `GET` [api/chatbots/{chatbotPk}/llm-usage-statistics](https://docs.maiagent.ai/api/dui-hua-widget#-llm-): Get LLM usage statistics
* `GET` [api/chatbots/{chatbotPk}/statistics](https://docs.maiagent.ai/api/dui-hua-widget#-ai-): Get AI assistant statistics
* `PATCH` [api/chatbots/{chatbot\_id}/enable-evaluation](https://docs.maiagent.ai/api/dui-hua-widget#-ai-): Enable or disable the evaluation feature for a specific AI assistant

### Organizations and Members

* `POST` [api/auth/registration](https://docs.maiagent.ai/api/zu-zhi-yu-cheng-yuan#): Account registration
* `POST` [api/auth/password/change](https://docs.maiagent.ai/api/zu-zhi-yu-cheng-yuan#): Change password
* `POST` [api/organizations](https://docs.maiagent.ai/api/zu-zhi-yu-cheng-yuan#): Create a new organization
* `POST` [api/organizations/{organizationPk}/members](https://docs.maiagent.ai/api/zu-zhi-yu-cheng-yuan#): Add a member to a specified organization
* `GET` [api/organizations](https://docs.maiagent.ai/api/zu-zhi-yu-cheng-yuan#): Get a list of organizations
* `GET` [api/organizations/{id}](https://docs.maiagent.ai/api/zu-zhi-yu-cheng-yuan#): Get information for a specific organization
* `GET` [api/users/current](https://docs.maiagent.ai/api/zu-zhi-yu-cheng-yuan#): Get current user details
* `GET` [api/permissions](https://docs.maiagent.ai/api/zu-zhi-yu-cheng-yuan#): Get current user permissions
* `GET` [api/organizations/{organizationPk}/members](https://docs.maiagent.ai/api/zu-zhi-yu-cheng-yuan#): Get the member list of a specified organization
* `GET` [api/organizations/{organizationPk}/members/{id}](https://docs.maiagent.ai/api/zu-zhi-yu-cheng-yuan#): Get details of a specific member
* `PUT` [api/organizations/{id}](https://docs.maiagent.ai/api/zu-zhi-yu-cheng-yuan#): Update organization information
* `PUT` [api/users/current](https://docs.maiagent.ai/api/zu-zhi-yu-cheng-yuan#): Update current user details
* `PUT` [api/organizations/{organizationPk}/members/{id}](https://docs.maiagent.ai/api/zu-zhi-yu-cheng-yuan#): Update member information in a specified organization
* `DELETE` [api/organizations/{id}](https://docs.maiagent.ai/api/zu-zhi-yu-cheng-yuan#): Delete an organization
* `DELETE` [api/organizations/{organizationPk}/members/{id}](https://docs.maiagent.ai/api/zu-zhi-yu-cheng-yuan#): Delete a specified member

### Roles and Permissions

* `POST` [api/organizations/{organizationPk}/groups](https://docs.maiagent.ai/api/jiao-se-yu-quan-xian#): Create a role
* `POST` [api/organizations/{organizationPk}/groups/{groupPk}/group-members/bulk-create](https://docs.maiagent.ai/api/jiao-se-yu-quan-xian#): Bulk add role members
* `POST` [api/organizations/{organizationPk}/groups/{groupPk}/group-chatbots/bulk-create](https://docs.maiagent.ai/api/jiao-se-yu-quan-xian#-ai-): Bulk assign AI assistants to a role
* `GET` [api/permissions](https://docs.maiagent.ai/api/jiao-se-yu-quan-xian#): List permissions
* `GET` [api/organizations/{organizationPk}/groups](https://docs.maiagent.ai/api/jiao-se-yu-quan-xian#): Get a list of roles
* `GET` [api/organizations/{organizationPk}/groups/{id}](https://docs.maiagent.ai/api/jiao-se-yu-quan-xian#): Get details of a role
* `GET` [api/organizations/{organizationPk}/groups/{groupPk}/group-members](https://docs.maiagent.ai/api/jiao-se-yu-quan-xian#): Get a list of role members
* `GET` [api/organizations/{organizationPk}/groups/{groupPk}/group-members/{id}](https://docs.maiagent.ai/api/jiao-se-yu-quan-xian#): View a specific role member
* `GET` [api/organizations/{organizationPk}/groups/{groupPk}/group-chatbots](https://docs.maiagent.ai/api/jiao-se-yu-quan-xian#-ai-): Get the list of AI assistants for a role
* `PUT` [api/organizations/{organizationPk}/groups/{id}](https://docs.maiagent.ai/api/jiao-se-yu-quan-xian#): Update role permissions
* `PATCH` [api/organizations/{organizationPk}/groups/{id}](https://docs.maiagent.ai/api/jiao-se-yu-quan-xian#): Partially update role permissions
* `DELETE` [api/organizations/{organizationPk}/groups/{id}](https://docs.maiagent.ai/api/jiao-se-yu-quan-xian#): Delete a role
* `DELETE` [api/organizations/{organizationPk}/groups/{groupPk}/group-members/{id}](https://docs.maiagent.ai/api/jiao-se-yu-quan-xian#): Remove a role member
* `DELETE` [api/organizations/{organizationPk}/groups/{groupPk}/group-chatbots/{id}](https://docs.maiagent.ai/api/jiao-se-yu-quan-xian#-ai-): Remove an AI assistant from a role

### Contacts

* `GET` [api/contacts](https://docs.maiagent.ai/api/聯絡人#): List contacts
* `POST` [api/contacts](https://docs.maiagent.ai/api/聯絡人#): Create a contact
* `GET` [api/contacts/{id}](https://docs.maiagent.ai/api/聯絡人#): Get contact details
* `PUT` [api/contacts/{id}](https://docs.maiagent.ai/api/聯絡人#): Update a contact
* `PATCH` [api/contacts/{id}](https://docs.maiagent.ai/api/聯絡人#): Update a contact
* `DELETE` [api/contacts/{id}](https://docs.maiagent.ai/api/聯絡人#): Delete a contact

## Authentication Requirements

All API requests must include an API Key in the HTTP Header, in the following format:

```
Authorization: Api-Key YOUR_API_KEY
```

## Usage Instructions

* Please read the detailed documentation for each endpoint carefully
* Detailed request and response formats can be found on each category page
* All example code is provided in multiple programming languages

## Status Code Descriptions

| Status Code | Description                   |
| ----------- | ----------------------------- |
| 200         | Request successful            |
| 201         | Resource created successfully |
| 400         | Bad request format            |
| 401         | Authentication failed         |
| 403         | Insufficient permissions      |
| 404         | Resource not found            |
| 500         | Server error                  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/api/api-doc-en/preparation/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.