# 角色與權限
### 建立角色
POST `/api/organizations/{organizationPk}/groups/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------ |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ---------------------- | -------------- | -- | -- |
| name | string | 是 | |
| organization | string (uuid) | 否 | |
| permissions | array\[string] | 是 | |
| canCreateChatbot | boolean | 否 | |
| canCreateKnowledgeBase | boolean | 否 | |
| canCreateInbox | boolean | 否 | |
| canCreateDatabase | boolean | 否 | |
**請求結構範例**
```typescript
{
"name": string
"organization"?: string (uuid) // 非必填
"permissions": [
string (uuid)
]
"canCreateChatbot"?: boolean // 非必填
"canCreateKnowledgeBase"?: boolean // 非必填
"canCreateInbox"?: boolean // 非必填
"canCreateDatabase"?: boolean // 非必填
}
```
**請求範例值**
```json
{
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
};
axios.post("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"type":
{
}
"permissions": [ // 返回群組的權限列表
處理流程：
1. 將群組權限分為父權限和子權限
2. 將子權限按父權限 ID 分組
3. 若有子權限缺少父權限，自動從資料庫載入缺少的父權限
4. 將父權限和對應的子權限序列化，並按 order 排序
object
]
"membersPreview": [ // 返回前 10 個成員名稱（用於列表顯示前 3 個和 tooltip 顯示 10 個）
string
]
"membersCount": integer // 返回剩餘成員數量（扣除列表顯示的 3 人後），用於前端 +N badge 顯示
與資源 count 不同：
- members_count: 返回 total - 3（用於 +N badge），None 表示總數 <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: 返回總數量
"chatbotsCount": integer // 返回 AI 助理總數量
"chatbotsPreview": [ // 返回前 10 個 AI 助理名稱
string
]
"knowledgeBasesCount": integer // 返回知識庫總數量
"knowledgeBasesPreview": [ // 返回前 10 個知識庫名稱
string
]
"inboxesCount": integer // 返回對話平台總數量
"inboxesPreview": [ // 返回前 10 個對話平台名稱
string
]
"databasesCount": integer // 返回資料庫總數量
"databasesPreview": [ // 返回前 10 個資料庫名稱
string
]
"canCreateChatbot"?: boolean // 非必填
"canCreateKnowledgeBase"?: boolean // 非必填
"canCreateInbox"?: boolean // 非必填
"canCreateDatabase"?: boolean // 非必填
"createdAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"type": {},
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"membersPreview": [
"回應字串"
],
"membersCount": 456,
"chatbotsCount": 456,
"chatbotsPreview": [
"回應字串"
],
"knowledgeBasesCount": 456,
"knowledgeBasesPreview": [
"回應字串"
],
"inboxesCount": 456,
"inboxesPreview": [
"回應字串"
],
"databasesCount": 456,
"databasesPreview": [
"回應字串"
],
"canCreateChatbot": false,
"canCreateKnowledgeBase": false,
"canCreateInbox": false,
"canCreateDatabase": false,
"createdAt": "回應字串"
}
```
***
### 建立角色
POST `/api/v1/organizations/{organizationPk}/groups/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------ |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ---------------------- | -------------- | -- | -- |
| name | string | 是 | |
| organization | string (uuid) | 否 | |
| permissions | array\[string] | 是 | |
| canCreateChatbot | boolean | 否 | |
| canCreateKnowledgeBase | boolean | 否 | |
| canCreateInbox | boolean | 否 | |
| canCreateDatabase | boolean | 否 | |
**請求結構範例**
```typescript
{
"name": string
"organization"?: string (uuid) // 非必填
"permissions": [
string (uuid)
]
"canCreateChatbot"?: boolean // 非必填
"canCreateKnowledgeBase"?: boolean // 非必填
"canCreateInbox"?: boolean // 非必填
"canCreateDatabase"?: boolean // 非必填
}
```
**請求範例值**
```json
{
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
};
axios.post("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"type":
{
}
"permissions": [ // 返回群組的權限列表
處理流程：
1. 將群組權限分為父權限和子權限
2. 將子權限按父權限 ID 分組
3. 若有子權限缺少父權限，自動從資料庫載入缺少的父權限
4. 將父權限和對應的子權限序列化，並按 order 排序
object
]
"membersPreview": [ // 返回前 10 個成員名稱（用於列表顯示前 3 個和 tooltip 顯示 10 個）
string
]
"membersCount": integer // 返回剩餘成員數量（扣除列表顯示的 3 人後），用於前端 +N badge 顯示
與資源 count 不同：
- members_count: 返回 total - 3（用於 +N badge），None 表示總數 <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: 返回總數量
"chatbotsCount": integer // 返回 AI 助理總數量
"chatbotsPreview": [ // 返回前 10 個 AI 助理名稱
string
]
"knowledgeBasesCount": integer // 返回知識庫總數量
"knowledgeBasesPreview": [ // 返回前 10 個知識庫名稱
string
]
"inboxesCount": integer // 返回對話平台總數量
"inboxesPreview": [ // 返回前 10 個對話平台名稱
string
]
"databasesCount": integer // 返回資料庫總數量
"databasesPreview": [ // 返回前 10 個資料庫名稱
string
]
"canCreateChatbot"?: boolean // 非必填
"canCreateKnowledgeBase"?: boolean // 非必填
"canCreateInbox"?: boolean // 非必填
"canCreateDatabase"?: boolean // 非必填
"createdAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"type": {},
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"membersPreview": [
"回應字串"
],
"membersCount": 456,
"chatbotsCount": 456,
"chatbotsPreview": [
"回應字串"
],
"knowledgeBasesCount": 456,
"knowledgeBasesPreview": [
"回應字串"
],
"inboxesCount": 456,
"inboxesPreview": [
"回應字串"
],
"databasesCount": 456,
"databasesPreview": [
"回應字串"
],
"canCreateChatbot": false,
"canCreateKnowledgeBase": false,
"canCreateInbox": false,
"canCreateDatabase": false,
"createdAt": "回應字串"
}
```
***
### 批量新增角色成員
POST `/api/organizations/{organizationPk}/groups/{groupPk}/group-members/bulk-create/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------ |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------- | -------------- | -- | -- |
| members | array\[string] | 是 | |
**請求結構範例**
```typescript
{
"members": [
string (uuid)
]
}
```
**請求範例值**
```json
{
"members": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/bulk-create/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"members": [
"550e8400-e29b-41d4-a716-446655440000"
]
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"members": [
"550e8400-e29b-41d4-a716-446655440000"
]
};
axios.post("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/bulk-create/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/bulk-create/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"members": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/bulk-create/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"members": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
[
{
"id"?: string (uuid) // 角色成員 ID (非必填)
"member"?: { // 非必填
{
"id"?: string (uuid) // 成員 ID (非必填)
"name"?: string // 成員姓名 (非必填)
"email"?: string (email) // 成員電子郵件 (非必填)
"organization"?: { // 非必填
{
"id"?: string (uuid) // 組織 ID (非必填)
"name"?: string // 組織名稱 (非必填)
"createdAt"?: string // 組織建立時間戳 (非必填)
"usageStatistics"?: { // 非必填
{
"chatbotsCount"?: integer // 聊天機器人數量 (非必填)
"canCreateChatbot"?: boolean // 是否可以創建聊天機器人 (非必填)
"hasCreateChatbotLimit"?: boolean // 是否有創建聊天機器人限制 (非必填)
"currentMonthWordsCountTotal"?: integer // 當月總字數限制 (非必填)
"currentMonthUsedWordsCountTotal"?: integer // 當月已使用字數 (非必填)
"currentMonthUsedConversationsCountTotal"?: integer // 當月已使用對話數 (非必填)
"availableUploadFilesSizeTotal"?: integer // 可上傳檔案總大小 (非必填)
"usedUploadFileSizeTotal"?: integer // 已使用上傳檔案大小 (非必填)
}
}
"organizationPlan"?: { // 非必填
{
"id"?: string (uuid) // 方案 ID (非必填)
"planName"?: string // 方案名稱 (非必填)
"expiredAt"?: string // 方案到期時間 (非必填)
}
}
}
}
"isOwner"?: boolean // 是否為組織擁有者 (非必填)
"permissions"?: { // 非必填
{
"hasOrganizationAccessPermission"?: boolean // 是否有組織存取權限 (非必填)
"hasChatAccessPermission"?: boolean // 是否有聊天存取權限 (非必填)
"hasConversationAccessPermission"?: boolean // 是否有對話存取權限 (非必填)
"hasChatbotAccessPermission"?: boolean // 是否有聊天機器人存取權限 (非必填)
}
}
"createdAt"?: string // 成員建立時間戳 (非必填)
}
}
"createdAt"?: string // 角色成員建立時間戳 (非必填)
}
]
```
**回應範例值**
```json
[
{
"id": "c1e54f04-01fc-45e9-b40c-9d8b37bd0ac0",
"member": {
"id": "af4e472d-3f9b-446b-bab8-05de4112d086",
"name": "h",
"email": "h@gmail.com",
"organization": {
"id": "670e3d30-9d24-47b4-b2cc-6bf224b2f3bb",
"name": "Updated Org Name",
"createdAt": "1745288290000",
"usageStatistics": {
"chatbotsCount": 1,
"canCreateChatbot": false,
"hasCreateChatbotLimit": true,
"currentMonthWordsCountTotal": 1000000,
"currentMonthUsedWordsCountTotal": 0,
"currentMonthUsedConversationsCountTotal": 0,
"availableUploadFilesSizeTotal": 104857600,
"usedUploadFileSizeTotal": 0
},
"organizationPlan": {
"id": "16136181-ae0d-4b3f-aaeb-9a6ed251459f",
"planName": "免費方案",
"expiredAt": null
}
},
"isOwner": false,
"permissions": {
"hasMaigptAccessPermission": false,
"hasChatbotAccessPermission": false,
"hasAgentopsAccessPermission": false,
"hasConversationAccessPermission": false,
"hasChatAccessPermission": false,
"hasDeveloperAccessPermission": false,
"hasOrganizationAccessPermission": true
},
"createdAt": "1748335331000"
},
"createdAt": "1748341252000"
}
]
```
***
### 批量新增角色成員
POST `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-members/bulk-create/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------ |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------- | -------------- | -- | -- |
| members | array\[string] | 是 | |
**請求結構範例**
```typescript
{
"members": [
string (uuid)
]
}
```
**請求範例值**
```json
{
"members": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/bulk-create/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"members": [
"550e8400-e29b-41d4-a716-446655440000"
]
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"members": [
"550e8400-e29b-41d4-a716-446655440000"
]
};
axios.post("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/bulk-create/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/bulk-create/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"members": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/bulk-create/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"members": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
[
{
"id"?: string (uuid) // 角色成員 ID (非必填)
"member"?: { // 非必填
{
"id"?: string (uuid) // 成員 ID (非必填)
"name"?: string // 成員姓名 (非必填)
"email"?: string (email) // 成員電子郵件 (非必填)
"organization"?: { // 非必填
{
"id"?: string (uuid) // 組織 ID (非必填)
"name"?: string // 組織名稱 (非必填)
"createdAt"?: string // 組織建立時間戳 (非必填)
"usageStatistics"?: { // 非必填
{
"chatbotsCount"?: integer // 聊天機器人數量 (非必填)
"canCreateChatbot"?: boolean // 是否可以創建聊天機器人 (非必填)
"hasCreateChatbotLimit"?: boolean // 是否有創建聊天機器人限制 (非必填)
"currentMonthWordsCountTotal"?: integer // 當月總字數限制 (非必填)
"currentMonthUsedWordsCountTotal"?: integer // 當月已使用字數 (非必填)
"currentMonthUsedConversationsCountTotal"?: integer // 當月已使用對話數 (非必填)
"availableUploadFilesSizeTotal"?: integer // 可上傳檔案總大小 (非必填)
"usedUploadFileSizeTotal"?: integer // 已使用上傳檔案大小 (非必填)
}
}
"organizationPlan"?: { // 非必填
{
"id"?: string (uuid) // 方案 ID (非必填)
"planName"?: string // 方案名稱 (非必填)
"expiredAt"?: string // 方案到期時間 (非必填)
}
}
}
}
"isOwner"?: boolean // 是否為組織擁有者 (非必填)
"permissions"?: { // 非必填
{
"hasOrganizationAccessPermission"?: boolean // 是否有組織存取權限 (非必填)
"hasChatAccessPermission"?: boolean // 是否有聊天存取權限 (非必填)
"hasConversationAccessPermission"?: boolean // 是否有對話存取權限 (非必填)
"hasChatbotAccessPermission"?: boolean // 是否有聊天機器人存取權限 (非必填)
}
}
"createdAt"?: string // 成員建立時間戳 (非必填)
}
}
"createdAt"?: string // 角色成員建立時間戳 (非必填)
}
]
```
**回應範例值**
```json
[
{
"id": "c1e54f04-01fc-45e9-b40c-9d8b37bd0ac0",
"member": {
"id": "af4e472d-3f9b-446b-bab8-05de4112d086",
"name": "h",
"email": "h@gmail.com",
"organization": {
"id": "670e3d30-9d24-47b4-b2cc-6bf224b2f3bb",
"name": "Updated Org Name",
"createdAt": "1745288290000",
"usageStatistics": {
"chatbotsCount": 1,
"canCreateChatbot": false,
"hasCreateChatbotLimit": true,
"currentMonthWordsCountTotal": 1000000,
"currentMonthUsedWordsCountTotal": 0,
"currentMonthUsedConversationsCountTotal": 0,
"availableUploadFilesSizeTotal": 104857600,
"usedUploadFileSizeTotal": 0
},
"organizationPlan": {
"id": "16136181-ae0d-4b3f-aaeb-9a6ed251459f",
"planName": "免費方案",
"expiredAt": null
}
},
"isOwner": false,
"permissions": {
"hasMaigptAccessPermission": false,
"hasChatbotAccessPermission": false,
"hasAgentopsAccessPermission": false,
"hasConversationAccessPermission": false,
"hasChatAccessPermission": false,
"hasDeveloperAccessPermission": false,
"hasOrganizationAccessPermission": true
},
"createdAt": "1748335331000"
},
"createdAt": "1748341252000"
}
]
```
***
### 批量分配 AI 助理給角色
POST `/api/organizations/{organizationPk}/groups/{groupPk}/group-chatbots/bulk-create/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| -------- | -------------- | -- | -- |
| chatbots | array\[string] | 是 | |
**請求結構範例**
```typescript
{
"chatbots": [
string (uuid)
]
}
```
**請求範例值**
```json
{
"chatbots": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/bulk-create/?page=1&pageSize=1&query=example" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chatbots": [
"550e8400-e29b-41d4-a716-446655440000"
]
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"chatbots": [
"550e8400-e29b-41d4-a716-446655440000"
]
};
axios.post("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/bulk-create/?page=1&pageSize=1&query=example", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/bulk-create/?page=1&pageSize=1&query=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"chatbots": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/bulk-create/?page=1&pageSize=1&query=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"chatbots": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"group": string (uuid)
"chatbot":
{
"id": string (uuid)
"name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
"rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
"largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
"embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
"rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
"instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
"knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
{
"id": string (uuid)
"name": string
}
]
"databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
{
"id": string (uuid)
"name": string
}
]
"updatedAt": string (timestamp)
"organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
"builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
"replyMode"?: // 回覆模式：一般回覆或串流回覆
* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
{
}
"template"?: string // 模板模式、混合模式所使用的模板 (非必填)
"unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
"totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
"outputMode"?: // 輸出模式：文字、表格或自定義格式
* `text` - 文字
* `json_schema` - JSON Schema (非必填)
{
}
"rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
"groups"?: [ // 機器人可存取的群組列表 (非必填)
{
"id": string (uuid)
"name": string
}
]
"tools"?: [ // 機器人可使用的工具列表 (非必填)
{
"id": string (uuid)
"name": string
"description": string
"displayName": string
"toolType": string
}
]
"skills"?: [ // 機器人關聯的技能列表 (非必填)
{
"id": string (uuid)
"name": string
"description": string
}
]
"agentMode"?: // 代理模式：一般、SQL或工作流程模式
* `normal` - 正常
* `canvas` - 畫布 (非必填)
{
}
"numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
"enableEvaluation"?: boolean // 非必填
"enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
"enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
"customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
"voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
"sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
"sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
"ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
"ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
"realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
"realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
"thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
"enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
"isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
}
"canRead"?: boolean // 非必填
"canUpdate"?: boolean // 非必填
"canDelete"?: boolean // 非必填
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"group": "550e8400-e29b-41d4-a716-446655440000",
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "回應字串",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"databases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"updatedAt": "回應字串",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "回應字串",
"unanswerableTemplate": "回應字串",
"totalWordsCount": 456,
"outputMode": {},
"rawOutputFormat": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"displayName": "回應字串",
"toolType": "回應字串"
}
],
"skills": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 456,
"enableEvaluation": false,
"enableInlineCitations": false,
"enableCodeInterpreter": false,
"customMaxLlmOutputTokens": 456,
"voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
"sttProvider": "550e8400-e29b-41d4-a716-446655440000",
"sttConfig": null,
"ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
"ttsConfig": null,
"realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
"realtimeConfig": null,
"thinkingConfig": null,
"enableToolSearching": false,
"isMultimodalLlm": false
},
"canRead": false,
"canUpdate": false,
"canDelete": false,
"createdAt": "回應字串"
}
]
}
```
***
### 批量分配 AI 助理給角色
POST `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-chatbots/bulk-create/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| -------- | -------------- | -- | -- |
| chatbots | array\[string] | 是 | |
**請求結構範例**
```typescript
{
"chatbots": [
string (uuid)
]
}
```
**請求範例值**
```json
{
"chatbots": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/bulk-create/?page=1&pageSize=1&query=example" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chatbots": [
"550e8400-e29b-41d4-a716-446655440000"
]
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"chatbots": [
"550e8400-e29b-41d4-a716-446655440000"
]
};
axios.post("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/bulk-create/?page=1&pageSize=1&query=example", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/bulk-create/?page=1&pageSize=1&query=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"chatbots": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/bulk-create/?page=1&pageSize=1&query=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"chatbots": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"group": string (uuid)
"chatbot":
{
"id": string (uuid)
"name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
"rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
"largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
"embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
"rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
"instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
"knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
{
"id": string (uuid)
"name": string
}
]
"databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
{
"id": string (uuid)
"name": string
}
]
"updatedAt": string (timestamp)
"organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
"builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
"replyMode"?: // 回覆模式：一般回覆或串流回覆
* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
{
}
"template"?: string // 模板模式、混合模式所使用的模板 (非必填)
"unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
"totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
"outputMode"?: // 輸出模式：文字、表格或自定義格式
* `text` - 文字
* `json_schema` - JSON Schema (非必填)
{
}
"rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
"groups"?: [ // 機器人可存取的群組列表 (非必填)
{
"id": string (uuid)
"name": string
}
]
"tools"?: [ // 機器人可使用的工具列表 (非必填)
{
"id": string (uuid)
"name": string
"description": string
"displayName": string
"toolType": string
}
]
"skills"?: [ // 機器人關聯的技能列表 (非必填)
{
"id": string (uuid)
"name": string
"description": string
}
]
"agentMode"?: // 代理模式：一般、SQL或工作流程模式
* `normal` - 正常
* `canvas` - 畫布 (非必填)
{
}
"numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
"enableEvaluation"?: boolean // 非必填
"enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
"enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
"customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
"voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
"sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
"sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
"ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
"ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
"realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
"realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
"thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
"enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
"isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
}
"canRead"?: boolean // 非必填
"canUpdate"?: boolean // 非必填
"canDelete"?: boolean // 非必填
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"group": "550e8400-e29b-41d4-a716-446655440000",
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "回應字串",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"databases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"updatedAt": "回應字串",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "回應字串",
"unanswerableTemplate": "回應字串",
"totalWordsCount": 456,
"outputMode": {},
"rawOutputFormat": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"displayName": "回應字串",
"toolType": "回應字串"
}
],
"skills": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 456,
"enableEvaluation": false,
"enableInlineCitations": false,
"enableCodeInterpreter": false,
"customMaxLlmOutputTokens": 456,
"voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
"sttProvider": "550e8400-e29b-41d4-a716-446655440000",
"sttConfig": null,
"ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
"ttsConfig": null,
"realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
"realtimeConfig": null,
"thinkingConfig": null,
"enableToolSearching": false,
"isMultimodalLlm": false
},
"canRead": false,
"canUpdate": false,
"canDelete": false,
"createdAt": "回應字串"
}
]
}
```
***
### 批量分配收件匣給角色
POST `/api/organizations/{organizationPk}/groups/{groupPk}/group-inboxes/bulk-create/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------ |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/bulk-create/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.post("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/bulk-create/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/bulk-create/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.post(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/bulk-create/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 200 | No response body |
***
### 批量分配收件匣給角色
POST `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-inboxes/bulk-create/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------ |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/bulk-create/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.post("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/bulk-create/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/bulk-create/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.post(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/bulk-create/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 200 | No response body |
***
### 批量分配知識庫給角色
POST `/api/organizations/{organizationPk}/groups/{groupPk}/group-knowledge-bases/bulk-create/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| -------------- | -------------- | -- | -- |
| knowledgeBases | array\[string] | 是 | |
**請求結構範例**
```typescript
{
"knowledgeBases": [
string (uuid)
]
}
```
**請求範例值**
```json
{
"knowledgeBases": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/bulk-create/?page=1&pageSize=1&query=example" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"knowledgeBases": [
"550e8400-e29b-41d4-a716-446655440000"
]
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"knowledgeBases": [
"550e8400-e29b-41d4-a716-446655440000"
]
};
axios.post("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/bulk-create/?page=1&pageSize=1&query=example", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/bulk-create/?page=1&pageSize=1&query=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"knowledgeBases": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/bulk-create/?page=1&pageSize=1&query=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"knowledgeBases": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"group": string (uuid)
"knowledgeBase":
{
"id": string (uuid)
"createdBy"?: string (uuid) // 非必填
"organization"?: string (uuid) // 非必填
"embeddingModel": string (uuid)
"rerankerModel": string (uuid)
"name": string
"description"?: string // 非必填
"numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
"sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
"enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
"similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
"enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
"enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
"vectorDatabaseType"?: // Type of vector database: elasticsearch or opensearch.
* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
{
}
"vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
"vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
"opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
"opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
"oracleUser"?: string // Oracle database username. (非必填)
"oraclePassword"?: string // Oracle database password. (非必填)
"labels": [
{
"id": string (uuid)
"name": string
}
]
"chatbots"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"groups"?: [ // 知識庫可存取的群組列表 (非必填)
{
"id": string (uuid)
"name": string
}
]
"filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
"vectorStorageSize": integer
"chunksCount": integer
"isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
"canUpdate": boolean // Return whether the current user can update this resource.
"canDelete": boolean // Return whether the current user can delete this resource.
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
"canRead"?: boolean // 非必填
"canUpdate"?: boolean // 非必填
"canDelete"?: boolean // 非必填
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"group": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": "550e8400-e29b-41d4-a716-446655440000",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"numberOfRetrievedChunks": 456,
"sentenceWindowSize": 456,
"enableHyde": false,
"similarityCutoff": 456,
"enableRerank": false,
"enableRrf": false,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "回應字串",
"vectorDatabaseApiKey": "回應字串",
"opensearchUsername": "回應字串",
"opensearchPassword": "回應字串",
"oracleUser": "回應字串",
"oraclePassword": "回應字串",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"filesCount": 456,
"vectorStorageSize": 456,
"chunksCount": 456,
"isMultimodal": false,
"canUpdate": false,
"canDelete": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
},
"canRead": false,
"canUpdate": false,
"canDelete": false,
"createdAt": "回應字串"
}
]
}
```
***
### 批量分配知識庫給角色
POST `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-knowledge-bases/bulk-create/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| -------------- | -------------- | -- | -- |
| knowledgeBases | array\[string] | 是 | |
**請求結構範例**
```typescript
{
"knowledgeBases": [
string (uuid)
]
}
```
**請求範例值**
```json
{
"knowledgeBases": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/bulk-create/?page=1&pageSize=1&query=example" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"knowledgeBases": [
"550e8400-e29b-41d4-a716-446655440000"
]
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"knowledgeBases": [
"550e8400-e29b-41d4-a716-446655440000"
]
};
axios.post("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/bulk-create/?page=1&pageSize=1&query=example", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/bulk-create/?page=1&pageSize=1&query=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"knowledgeBases": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/bulk-create/?page=1&pageSize=1&query=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"knowledgeBases": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"group": string (uuid)
"knowledgeBase":
{
"id": string (uuid)
"createdBy"?: string (uuid) // 非必填
"organization"?: string (uuid) // 非必填
"embeddingModel": string (uuid)
"rerankerModel": string (uuid)
"name": string
"description"?: string // 非必填
"numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
"sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
"enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
"similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
"enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
"enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
"vectorDatabaseType"?: // Type of vector database: elasticsearch or opensearch.
* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
{
}
"vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
"vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
"opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
"opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
"oracleUser"?: string // Oracle database username. (非必填)
"oraclePassword"?: string // Oracle database password. (非必填)
"labels": [
{
"id": string (uuid)
"name": string
}
]
"chatbots"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"groups"?: [ // 知識庫可存取的群組列表 (非必填)
{
"id": string (uuid)
"name": string
}
]
"filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
"vectorStorageSize": integer
"chunksCount": integer
"isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
"canUpdate": boolean // Return whether the current user can update this resource.
"canDelete": boolean // Return whether the current user can delete this resource.
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
"canRead"?: boolean // 非必填
"canUpdate"?: boolean // 非必填
"canDelete"?: boolean // 非必填
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"group": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": "550e8400-e29b-41d4-a716-446655440000",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"numberOfRetrievedChunks": 456,
"sentenceWindowSize": 456,
"enableHyde": false,
"similarityCutoff": 456,
"enableRerank": false,
"enableRrf": false,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "回應字串",
"vectorDatabaseApiKey": "回應字串",
"opensearchUsername": "回應字串",
"opensearchPassword": "回應字串",
"oracleUser": "回應字串",
"oraclePassword": "回應字串",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"filesCount": 456,
"vectorStorageSize": 456,
"chunksCount": 456,
"isMultimodal": false,
"canUpdate": false,
"canDelete": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
},
"canRead": false,
"canUpdate": false,
"canDelete": false,
"createdAt": "回應字串"
}
]
}
```
***
### 批量分配資料庫給角色
POST `/api/organizations/{organizationPk}/groups/{groupPk}/group-databases/bulk-create/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| --------- | -------------- | -- | -- |
| databases | array\[string] | 是 | |
**請求結構範例**
```typescript
{
"databases": [
string (uuid)
]
}
```
**請求範例值**
```json
{
"databases": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/bulk-create/?page=1&pageSize=1&query=example" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"databases": [
"550e8400-e29b-41d4-a716-446655440000"
]
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"databases": [
"550e8400-e29b-41d4-a716-446655440000"
]
};
axios.post("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/bulk-create/?page=1&pageSize=1&query=example", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/bulk-create/?page=1&pageSize=1&query=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"databases": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/bulk-create/?page=1&pageSize=1&query=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"databases": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"group": string (uuid)
"database":
{
"id": string (uuid)
"name": string // Display name for this database connection
"description": string // Description of the database and its purpose
"databaseType": // Type of database: PostgreSQL, MySQL, MSSQL, Oracle, or MaiAgent
* `postgresql` - PostgreSQL
* `mysql` - MySQL
* `maiagent` - MaiAgent
* `oracle` - Oracle
* `mssql` - MSSQL
{
}
"databaseUrl": string // Connection string for external databases. Not required for MaiAgent type as it uses the system default.
"includeTables": object // Optional list of tables to include. Format: {"tables": ["table1", "table2"]}. For MaiAgent type, this is auto-populated from uploaded files.
"isActive": boolean // When disabled, this database will not be used in Text-to-SQL queries
"status":
{
}
"deletedAt": string (timestamp)
"tables": [
{
"id": string (uuid)
"tableName": string // Name of the table in the database
"description"?: string // Description of the table and its data for better Text-to-SQL understanding (非必填)
"status":
{
}
"errorMessage": string // Error details if table creation or deletion failed
"sourceFile":
{
"id": string (uuid)
"name": string
"isFromKnowledgeBase": boolean // Determine if the source file originated from a knowledge base upload.
Returns True if the file was uploaded via knowledge base,
False if uploaded directly to the database.
}
"columns": [
{
"id": string (uuid)
"columnName": string
"columnType"?: string // Data type of the column (e.g., VARCHAR, INTEGER, TIMESTAMP) (非必填)
"description"?: string // Description of the column for better Text-to-SQL understanding (非必填)
"isPrimaryKey"?: boolean // 非必填
"isNullable"?: boolean // 非必填
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"chatbots": [
{
"id": string (uuid)
"name": string
}
]
"groups": [
{
"id": string (uuid)
"name": string
}
]
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
"canRead"?: boolean // 非必填
"canUpdate"?: boolean // 非必填
"canDelete"?: boolean // 非必填
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"group": "550e8400-e29b-41d4-a716-446655440000",
"database": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"databaseType": {},
"databaseUrl": "回應字串",
"includeTables": null,
"isActive": false,
"status": {},
"deletedAt": "回應字串",
"tables": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"tableName": "回應字串",
"description": "回應字串",
"status": {},
"errorMessage": "回應字串",
"sourceFile": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"isFromKnowledgeBase": false
},
"columns": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"columnName": "回應字串",
"columnType": "回應字串",
"description": "回應字串",
"isPrimaryKey": false,
"isNullable": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
],
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
],
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"createdAt": "回應字串",
"updatedAt": "回應字串"
},
"canRead": false,
"canUpdate": false,
"canDelete": false,
"createdAt": "回應字串"
}
]
}
```
***
### 批量分配資料庫給角色
POST `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-databases/bulk-create/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| --------- | -------------- | -- | -- |
| databases | array\[string] | 是 | |
**請求結構範例**
```typescript
{
"databases": [
string (uuid)
]
}
```
**請求範例值**
```json
{
"databases": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/bulk-create/?page=1&pageSize=1&query=example" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"databases": [
"550e8400-e29b-41d4-a716-446655440000"
]
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"databases": [
"550e8400-e29b-41d4-a716-446655440000"
]
};
axios.post("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/bulk-create/?page=1&pageSize=1&query=example", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/bulk-create/?page=1&pageSize=1&query=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"databases": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/bulk-create/?page=1&pageSize=1&query=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"databases": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"group": string (uuid)
"database":
{
"id": string (uuid)
"name": string // Display name for this database connection
"description": string // Description of the database and its purpose
"databaseType": // Type of database: PostgreSQL, MySQL, MSSQL, Oracle, or MaiAgent
* `postgresql` - PostgreSQL
* `mysql` - MySQL
* `maiagent` - MaiAgent
* `oracle` - Oracle
* `mssql` - MSSQL
{
}
"databaseUrl": string // Connection string for external databases. Not required for MaiAgent type as it uses the system default.
"includeTables": object // Optional list of tables to include. Format: {"tables": ["table1", "table2"]}. For MaiAgent type, this is auto-populated from uploaded files.
"isActive": boolean // When disabled, this database will not be used in Text-to-SQL queries
"status":
{
}
"deletedAt": string (timestamp)
"tables": [
{
"id": string (uuid)
"tableName": string // Name of the table in the database
"description"?: string // Description of the table and its data for better Text-to-SQL understanding (非必填)
"status":
{
}
"errorMessage": string // Error details if table creation or deletion failed
"sourceFile":
{
"id": string (uuid)
"name": string
"isFromKnowledgeBase": boolean // Determine if the source file originated from a knowledge base upload.
Returns True if the file was uploaded via knowledge base,
False if uploaded directly to the database.
}
"columns": [
{
"id": string (uuid)
"columnName": string
"columnType"?: string // Data type of the column (e.g., VARCHAR, INTEGER, TIMESTAMP) (非必填)
"description"?: string // Description of the column for better Text-to-SQL understanding (非必填)
"isPrimaryKey"?: boolean // 非必填
"isNullable"?: boolean // 非必填
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"chatbots": [
{
"id": string (uuid)
"name": string
}
]
"groups": [
{
"id": string (uuid)
"name": string
}
]
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
"canRead"?: boolean // 非必填
"canUpdate"?: boolean // 非必填
"canDelete"?: boolean // 非必填
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"group": "550e8400-e29b-41d4-a716-446655440000",
"database": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"databaseType": {},
"databaseUrl": "回應字串",
"includeTables": null,
"isActive": false,
"status": {},
"deletedAt": "回應字串",
"tables": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"tableName": "回應字串",
"description": "回應字串",
"status": {},
"errorMessage": "回應字串",
"sourceFile": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"isFromKnowledgeBase": false
},
"columns": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"columnName": "回應字串",
"columnType": "回應字串",
"description": "回應字串",
"isPrimaryKey": false,
"isNullable": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
],
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
],
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"createdAt": "回應字串",
"updatedAt": "回應字串"
},
"canRead": false,
"canUpdate": false,
"canDelete": false,
"createdAt": "回應字串"
}
]
}
```
***
### 列出權限清單
GET `/api/permissions/`
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/permissions/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/permissions/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/permissions/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/permissions/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
[
{
"id": string (uuid)
"name": string
"value": string
"description": string
"children": [
object
]
}
]
```
**回應範例值**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"value": "回應字串",
"description": "回應字串",
"children": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
]
}
]
```
***
### 列出權限清單
GET `/api/v1/permissions/`
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/permissions/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/permissions/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/permissions/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/permissions/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
[
{
"id": string (uuid)
"name": string
"value": string
"description": string
"children": [
object
]
}
]
```
**回應範例值**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"value": "回應字串",
"description": "回應字串",
"children": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
]
}
]
```
***
### 取得角色列表
GET `/api/organizations/{organizationPk}/groups/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/?page=1&pageSize=1&query=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/?page=1&pageSize=1&query=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/?page=1&pageSize=1&query=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/?page=1&pageSize=1&query=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"name": string
"type":
{
}
"permissions": [ // 返回群組的權限列表
處理流程：
1. 將群組權限分為父權限和子權限
2. 將子權限按父權限 ID 分組
3. 若有子權限缺少父權限，自動從資料庫載入缺少的父權限
4. 將父權限和對應的子權限序列化，並按 order 排序
object
]
"membersPreview": [ // 返回前 10 個成員名稱（用於列表顯示前 3 個和 tooltip 顯示 10 個）
string
]
"membersCount": integer // 返回剩餘成員數量（扣除列表顯示的 3 人後），用於前端 +N badge 顯示
與資源 count 不同：
- members_count: 返回 total - 3（用於 +N badge），None 表示總數 <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: 返回總數量
"chatbotsCount": integer // 返回 AI 助理總數量
"chatbotsPreview": [ // 返回前 10 個 AI 助理名稱
string
]
"knowledgeBasesCount": integer // 返回知識庫總數量
"knowledgeBasesPreview": [ // 返回前 10 個知識庫名稱
string
]
"inboxesCount": integer // 返回對話平台總數量
"inboxesPreview": [ // 返回前 10 個對話平台名稱
string
]
"databasesCount": integer // 返回資料庫總數量
"databasesPreview": [ // 返回前 10 個資料庫名稱
string
]
"canCreateChatbot"?: boolean // 非必填
"canCreateKnowledgeBase"?: boolean // 非必填
"canCreateInbox"?: boolean // 非必填
"canCreateDatabase"?: boolean // 非必填
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"type": {},
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"membersPreview": [
"回應字串"
],
"membersCount": 456,
"chatbotsCount": 456,
"chatbotsPreview": [
"回應字串"
],
"knowledgeBasesCount": 456,
"knowledgeBasesPreview": [
"回應字串"
],
"inboxesCount": 456,
"inboxesPreview": [
"回應字串"
],
"databasesCount": 456,
"databasesPreview": [
"回應字串"
],
"canCreateChatbot": false,
"canCreateKnowledgeBase": false,
"canCreateInbox": false,
"canCreateDatabase": false,
"createdAt": "回應字串"
}
]
}
```
***
### 取得角色列表
GET `/api/v1/organizations/{organizationPk}/groups/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/?page=1&pageSize=1&query=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/?page=1&pageSize=1&query=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/?page=1&pageSize=1&query=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/?page=1&pageSize=1&query=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"name": string
"type":
{
}
"permissions": [ // 返回群組的權限列表
處理流程：
1. 將群組權限分為父權限和子權限
2. 將子權限按父權限 ID 分組
3. 若有子權限缺少父權限，自動從資料庫載入缺少的父權限
4. 將父權限和對應的子權限序列化，並按 order 排序
object
]
"membersPreview": [ // 返回前 10 個成員名稱（用於列表顯示前 3 個和 tooltip 顯示 10 個）
string
]
"membersCount": integer // 返回剩餘成員數量（扣除列表顯示的 3 人後），用於前端 +N badge 顯示
與資源 count 不同：
- members_count: 返回 total - 3（用於 +N badge），None 表示總數 <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: 返回總數量
"chatbotsCount": integer // 返回 AI 助理總數量
"chatbotsPreview": [ // 返回前 10 個 AI 助理名稱
string
]
"knowledgeBasesCount": integer // 返回知識庫總數量
"knowledgeBasesPreview": [ // 返回前 10 個知識庫名稱
string
]
"inboxesCount": integer // 返回對話平台總數量
"inboxesPreview": [ // 返回前 10 個對話平台名稱
string
]
"databasesCount": integer // 返回資料庫總數量
"databasesPreview": [ // 返回前 10 個資料庫名稱
string
]
"canCreateChatbot"?: boolean // 非必填
"canCreateKnowledgeBase"?: boolean // 非必填
"canCreateInbox"?: boolean // 非必填
"canCreateDatabase"?: boolean // 非必填
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"type": {},
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"membersPreview": [
"回應字串"
],
"membersCount": 456,
"chatbotsCount": 456,
"chatbotsPreview": [
"回應字串"
],
"knowledgeBasesCount": 456,
"knowledgeBasesPreview": [
"回應字串"
],
"inboxesCount": 456,
"inboxesPreview": [
"回應字串"
],
"databasesCount": 456,
"databasesPreview": [
"回應字串"
],
"canCreateChatbot": false,
"canCreateKnowledgeBase": false,
"canCreateInbox": false,
"canCreateDatabase": false,
"createdAt": "回應字串"
}
]
}
```
***
### 取得角色的詳情
GET `/api/organizations/{organizationPk}/groups/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Group. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"type":
{
}
"permissions": [ // 返回群組的權限列表
處理流程：
1. 將群組權限分為父權限和子權限
2. 將子權限按父權限 ID 分組
3. 若有子權限缺少父權限，自動從資料庫載入缺少的父權限
4. 將父權限和對應的子權限序列化，並按 order 排序
object
]
"membersPreview": [ // 返回前 10 個成員名稱（用於列表顯示前 3 個和 tooltip 顯示 10 個）
string
]
"membersCount": integer // 返回剩餘成員數量（扣除列表顯示的 3 人後），用於前端 +N badge 顯示
與資源 count 不同：
- members_count: 返回 total - 3（用於 +N badge），None 表示總數 <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: 返回總數量
"chatbotsCount": integer // 返回 AI 助理總數量
"chatbotsPreview": [ // 返回前 10 個 AI 助理名稱
string
]
"knowledgeBasesCount": integer // 返回知識庫總數量
"knowledgeBasesPreview": [ // 返回前 10 個知識庫名稱
string
]
"inboxesCount": integer // 返回對話平台總數量
"inboxesPreview": [ // 返回前 10 個對話平台名稱
string
]
"databasesCount": integer // 返回資料庫總數量
"databasesPreview": [ // 返回前 10 個資料庫名稱
string
]
"canCreateChatbot"?: boolean // 非必填
"canCreateKnowledgeBase"?: boolean // 非必填
"canCreateInbox"?: boolean // 非必填
"canCreateDatabase"?: boolean // 非必填
"createdAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"type": {},
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"membersPreview": [
"回應字串"
],
"membersCount": 456,
"chatbotsCount": 456,
"chatbotsPreview": [
"回應字串"
],
"knowledgeBasesCount": 456,
"knowledgeBasesPreview": [
"回應字串"
],
"inboxesCount": 456,
"inboxesPreview": [
"回應字串"
],
"databasesCount": 456,
"databasesPreview": [
"回應字串"
],
"canCreateChatbot": false,
"canCreateKnowledgeBase": false,
"canCreateInbox": false,
"canCreateDatabase": false,
"createdAt": "回應字串"
}
```
***
### 取得角色的詳情
GET `/api/organizations/{organizationPk}/groups/export/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------ |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/export/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/export/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/export/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/export/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
string (binary)
```
**回應範例值**
```json
"回應字串"
```
***
### 取得角色的詳情
GET `/api/organizations/{organizationPk}/groups/export-template/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------ |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/export-template/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/export-template/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/export-template/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/export-template/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
string (binary)
```
**回應範例值**
```json
"回應字串"
```
***
### 取得角色的詳情
GET `/api/v1/organizations/{organizationPk}/groups/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Group. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"type":
{
}
"permissions": [ // 返回群組的權限列表
處理流程：
1. 將群組權限分為父權限和子權限
2. 將子權限按父權限 ID 分組
3. 若有子權限缺少父權限，自動從資料庫載入缺少的父權限
4. 將父權限和對應的子權限序列化，並按 order 排序
object
]
"membersPreview": [ // 返回前 10 個成員名稱（用於列表顯示前 3 個和 tooltip 顯示 10 個）
string
]
"membersCount": integer // 返回剩餘成員數量（扣除列表顯示的 3 人後），用於前端 +N badge 顯示
與資源 count 不同：
- members_count: 返回 total - 3（用於 +N badge），None 表示總數 <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: 返回總數量
"chatbotsCount": integer // 返回 AI 助理總數量
"chatbotsPreview": [ // 返回前 10 個 AI 助理名稱
string
]
"knowledgeBasesCount": integer // 返回知識庫總數量
"knowledgeBasesPreview": [ // 返回前 10 個知識庫名稱
string
]
"inboxesCount": integer // 返回對話平台總數量
"inboxesPreview": [ // 返回前 10 個對話平台名稱
string
]
"databasesCount": integer // 返回資料庫總數量
"databasesPreview": [ // 返回前 10 個資料庫名稱
string
]
"canCreateChatbot"?: boolean // 非必填
"canCreateKnowledgeBase"?: boolean // 非必填
"canCreateInbox"?: boolean // 非必填
"canCreateDatabase"?: boolean // 非必填
"createdAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"type": {},
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"membersPreview": [
"回應字串"
],
"membersCount": 456,
"chatbotsCount": 456,
"chatbotsPreview": [
"回應字串"
],
"knowledgeBasesCount": 456,
"knowledgeBasesPreview": [
"回應字串"
],
"inboxesCount": 456,
"inboxesPreview": [
"回應字串"
],
"databasesCount": 456,
"databasesPreview": [
"回應字串"
],
"canCreateChatbot": false,
"canCreateKnowledgeBase": false,
"canCreateInbox": false,
"canCreateDatabase": false,
"createdAt": "回應字串"
}
```
***
### 取得角色的詳情
GET `/api/v1/organizations/{organizationPk}/groups/export/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------ |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/export/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/export/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/export/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/export/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
string (binary)
```
**回應範例值**
```json
"回應字串"
```
***
### 取得角色的詳情
GET `/api/v1/organizations/{organizationPk}/groups/export-template/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------ |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/export-template/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/export-template/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/export-template/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/export-template/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
string (binary)
```
**回應範例值**
```json
"回應字串"
```
***
### 取得角色成員列表
GET `/api/organizations/{organizationPk}/groups/{groupPk}/group-members/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/?page=1&pageSize=1&query=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/?page=1&pageSize=1&query=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/?page=1&pageSize=1&query=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/?page=1&pageSize=1&query=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"member": {
{
"id": string (uuid)
"name": string
"email": string
"isOwner": boolean // 檢查成員是否為組織擁有者（透過 OWNER Group）
使用快取避免同一 request 內的重複查詢
快取生命週期：在 member instance 存在期間有效
優先使用 annotation 的結果（如果有的話）避免重複查詢
"permissions": [
object
]
"groups": [
object
]
"createdAt": string (timestamp)
}
}
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"member": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"email": "回應字串",
"isOwner": false,
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"createdAt": "回應字串"
},
"createdAt": "回應字串"
}
]
}
```
***
### 取得角色成員列表
GET `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-members/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/?page=1&pageSize=1&query=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/?page=1&pageSize=1&query=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/?page=1&pageSize=1&query=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/?page=1&pageSize=1&query=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"member": {
{
"id": string (uuid)
"name": string
"email": string
"isOwner": boolean // 檢查成員是否為組織擁有者（透過 OWNER Group）
使用快取避免同一 request 內的重複查詢
快取生命週期：在 member instance 存在期間有效
優先使用 annotation 的結果（如果有的話）避免重複查詢
"permissions": [
object
]
"groups": [
object
]
"createdAt": string (timestamp)
}
}
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"member": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"email": "回應字串",
"isOwner": false,
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"createdAt": "回應字串"
},
"createdAt": "回應字串"
}
]
}
```
***
### 查看特定角色成員
GET `/api/organizations/{organizationPk}/groups/{groupPk}/group-members/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | -------------------------------------------- |
| `groupPk` | ✅ | string | |
| `id` | ✅ | string | A UUID string identifying this Group Member. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"member": {
{
"id": string (uuid)
"name": string
"email": string
"isOwner": boolean // 檢查成員是否為組織擁有者（透過 OWNER Group）
使用快取避免同一 request 內的重複查詢
快取生命週期：在 member instance 存在期間有效
優先使用 annotation 的結果（如果有的話）避免重複查詢
"permissions": [
object
]
"groups": [
object
]
"createdAt": string (timestamp)
}
}
"createdAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"member": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"email": "回應字串",
"isOwner": false,
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"createdAt": "回應字串"
},
"createdAt": "回應字串"
}
```
***
### 查看特定角色成員
GET `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-members/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | -------------------------------------------- |
| `groupPk` | ✅ | string | |
| `id` | ✅ | string | A UUID string identifying this Group Member. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"member": {
{
"id": string (uuid)
"name": string
"email": string
"isOwner": boolean // 檢查成員是否為組織擁有者（透過 OWNER Group）
使用快取避免同一 request 內的重複查詢
快取生命週期：在 member instance 存在期間有效
優先使用 annotation 的結果（如果有的話）避免重複查詢
"permissions": [
object
]
"groups": [
object
]
"createdAt": string (timestamp)
}
}
"createdAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"member": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"email": "回應字串",
"isOwner": false,
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"createdAt": "回應字串"
},
"createdAt": "回應字串"
}
```
***
### 取得角色的 AI 助理列表
GET `/api/organizations/{organizationPk}/groups/{groupPk}/group-chatbots/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/?page=1&pageSize=1&query=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/?page=1&pageSize=1&query=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/?page=1&pageSize=1&query=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/?page=1&pageSize=1&query=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"group": string (uuid)
"chatbot":
{
"id": string (uuid)
"name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
"rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
"largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
"embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
"rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
"instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
"knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
{
"id": string (uuid)
"name": string
}
]
"databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
{
"id": string (uuid)
"name": string
}
]
"updatedAt": string (timestamp)
"organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
"builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
"replyMode"?: // 回覆模式：一般回覆或串流回覆
* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
{
}
"template"?: string // 模板模式、混合模式所使用的模板 (非必填)
"unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
"totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
"outputMode"?: // 輸出模式：文字、表格或自定義格式
* `text` - 文字
* `json_schema` - JSON Schema (非必填)
{
}
"rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
"groups"?: [ // 機器人可存取的群組列表 (非必填)
{
"id": string (uuid)
"name": string
}
]
"tools"?: [ // 機器人可使用的工具列表 (非必填)
{
"id": string (uuid)
"name": string
"description": string
"displayName": string
"toolType": string
}
]
"skills"?: [ // 機器人關聯的技能列表 (非必填)
{
"id": string (uuid)
"name": string
"description": string
}
]
"agentMode"?: // 代理模式：一般、SQL或工作流程模式
* `normal` - 正常
* `canvas` - 畫布 (非必填)
{
}
"numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
"enableEvaluation"?: boolean // 非必填
"enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
"enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
"customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
"voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
"sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
"sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
"ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
"ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
"realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
"realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
"thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
"enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
"isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
}
"canRead"?: boolean // 非必填
"canUpdate"?: boolean // 非必填
"canDelete"?: boolean // 非必填
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"group": "550e8400-e29b-41d4-a716-446655440000",
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "回應字串",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"databases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"updatedAt": "回應字串",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "回應字串",
"unanswerableTemplate": "回應字串",
"totalWordsCount": 456,
"outputMode": {},
"rawOutputFormat": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"displayName": "回應字串",
"toolType": "回應字串"
}
],
"skills": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 456,
"enableEvaluation": false,
"enableInlineCitations": false,
"enableCodeInterpreter": false,
"customMaxLlmOutputTokens": 456,
"voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
"sttProvider": "550e8400-e29b-41d4-a716-446655440000",
"sttConfig": null,
"ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
"ttsConfig": null,
"realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
"realtimeConfig": null,
"thinkingConfig": null,
"enableToolSearching": false,
"isMultimodalLlm": false
},
"canRead": false,
"canUpdate": false,
"canDelete": false,
"createdAt": "回應字串"
}
]
}
```
***
### 取得角色的 AI 助理列表
GET `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-chatbots/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/?page=1&pageSize=1&query=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/?page=1&pageSize=1&query=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/?page=1&pageSize=1&query=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/?page=1&pageSize=1&query=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"group": string (uuid)
"chatbot":
{
"id": string (uuid)
"name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
"rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
"largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
"embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
"rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
"instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
"knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
{
"id": string (uuid)
"name": string
}
]
"databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
{
"id": string (uuid)
"name": string
}
]
"updatedAt": string (timestamp)
"organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
"builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
"replyMode"?: // 回覆模式：一般回覆或串流回覆
* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
{
}
"template"?: string // 模板模式、混合模式所使用的模板 (非必填)
"unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
"totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
"outputMode"?: // 輸出模式：文字、表格或自定義格式
* `text` - 文字
* `json_schema` - JSON Schema (非必填)
{
}
"rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
"groups"?: [ // 機器人可存取的群組列表 (非必填)
{
"id": string (uuid)
"name": string
}
]
"tools"?: [ // 機器人可使用的工具列表 (非必填)
{
"id": string (uuid)
"name": string
"description": string
"displayName": string
"toolType": string
}
]
"skills"?: [ // 機器人關聯的技能列表 (非必填)
{
"id": string (uuid)
"name": string
"description": string
}
]
"agentMode"?: // 代理模式：一般、SQL或工作流程模式
* `normal` - 正常
* `canvas` - 畫布 (非必填)
{
}
"numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
"enableEvaluation"?: boolean // 非必填
"enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
"enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
"customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
"voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
"sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
"sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
"ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
"ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
"realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
"realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
"thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
"enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
"isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
}
"canRead"?: boolean // 非必填
"canUpdate"?: boolean // 非必填
"canDelete"?: boolean // 非必填
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"group": "550e8400-e29b-41d4-a716-446655440000",
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"rag": "550e8400-e29b-41d4-a716-446655440000",
"largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"instructions": "回應字串",
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"databases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"updatedAt": "回應字串",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
"replyMode": {},
"template": "回應字串",
"unanswerableTemplate": "回應字串",
"totalWordsCount": 456,
"outputMode": {},
"rawOutputFormat": null,
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"tools": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"displayName": "回應字串",
"toolType": "回應字串"
}
],
"skills": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串"
}
],
"agentMode": {},
"numberOfRetrievedChunks": 456,
"enableEvaluation": false,
"enableInlineCitations": false,
"enableCodeInterpreter": false,
"customMaxLlmOutputTokens": 456,
"voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
"sttProvider": "550e8400-e29b-41d4-a716-446655440000",
"sttConfig": null,
"ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
"ttsConfig": null,
"realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
"realtimeConfig": null,
"thinkingConfig": null,
"enableToolSearching": false,
"isMultimodalLlm": false
},
"canRead": false,
"canUpdate": false,
"canDelete": false,
"createdAt": "回應字串"
}
]
}
```
***
### 取得角色的收件匣列表
GET `/api/organizations/{organizationPk}/groups/{groupPk}/group-inboxes/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `channelType` | ❌ | string | \`line\`: LINE ; \`telegram\`: Telegram ; \`teams\`: Teams ; \`web\`: Web ; \`messenger\`: Messenger ; \`instagram\`: Instagram ; \`email\`: Email ; \`whatsapp\`: WhatsApp; |
| `chatbot` | ❌ | string | |
| `isActive` | ❌ | boolean | |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/?channelType=email&chatbot=550e8400-e29b-41d4-a716-446655440000&isActive=true&page=1&pageSize=1&query=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/?channelType=email&chatbot=550e8400-e29b-41d4-a716-446655440000&isActive=true&page=1&pageSize=1&query=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/?channelType=email&chatbot=550e8400-e29b-41d4-a716-446655440000&isActive=true&page=1&pageSize=1&query=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/?channelType=email&chatbot=550e8400-e29b-41d4-a716-446655440000&isActive=true&page=1&pageSize=1&query=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"group": string (uuid)
"inbox":
{
"id": string (uuid)
"channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
"name": string
"unreadConversationsCount": integer
"accessType": string
}
"canRead"?: boolean // 非必填
"canUpdate"?: boolean // 非必填
"canDelete"?: boolean // 非必填
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"group": "550e8400-e29b-41d4-a716-446655440000",
"inbox": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"channelType": "line",
"name": "回應字串",
"unreadConversationsCount": 456,
"accessType": "回應字串"
},
"canRead": false,
"canUpdate": false,
"canDelete": false,
"createdAt": "回應字串"
}
]
}
```
***
### 取得角色的收件匣列表
GET `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-inboxes/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `channelType` | ❌ | string | \`line\`: LINE ; \`telegram\`: Telegram ; \`teams\`: Teams ; \`web\`: Web ; \`messenger\`: Messenger ; \`instagram\`: Instagram ; \`email\`: Email ; \`whatsapp\`: WhatsApp; |
| `chatbot` | ❌ | string | |
| `isActive` | ❌ | boolean | |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/?channelType=email&chatbot=550e8400-e29b-41d4-a716-446655440000&isActive=true&page=1&pageSize=1&query=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/?channelType=email&chatbot=550e8400-e29b-41d4-a716-446655440000&isActive=true&page=1&pageSize=1&query=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/?channelType=email&chatbot=550e8400-e29b-41d4-a716-446655440000&isActive=true&page=1&pageSize=1&query=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/?channelType=email&chatbot=550e8400-e29b-41d4-a716-446655440000&isActive=true&page=1&pageSize=1&query=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"group": string (uuid)
"inbox":
{
"id": string (uuid)
"channelType": string (enum: line, telegram, teams, web, messenger, instagram, email, whatsapp) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
"name": string
"unreadConversationsCount": integer
"accessType": string
}
"canRead"?: boolean // 非必填
"canUpdate"?: boolean // 非必填
"canDelete"?: boolean // 非必填
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"group": "550e8400-e29b-41d4-a716-446655440000",
"inbox": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"channelType": "line",
"name": "回應字串",
"unreadConversationsCount": 456,
"accessType": "回應字串"
},
"canRead": false,
"canUpdate": false,
"canDelete": false,
"createdAt": "回應字串"
}
]
}
```
***
### 取得角色的知識庫列表
GET `/api/organizations/{organizationPk}/groups/{groupPk}/group-knowledge-bases/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/?page=1&pageSize=1&query=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/?page=1&pageSize=1&query=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/?page=1&pageSize=1&query=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/?page=1&pageSize=1&query=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"group": string (uuid)
"knowledgeBase":
{
"id": string (uuid)
"createdBy"?: string (uuid) // 非必填
"organization"?: string (uuid) // 非必填
"embeddingModel": string (uuid)
"rerankerModel": string (uuid)
"name": string
"description"?: string // 非必填
"numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
"sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
"enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
"similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
"enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
"enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
"vectorDatabaseType"?: // Type of vector database: elasticsearch or opensearch.
* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
{
}
"vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
"vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
"opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
"opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
"oracleUser"?: string // Oracle database username. (非必填)
"oraclePassword"?: string // Oracle database password. (非必填)
"labels": [
{
"id": string (uuid)
"name": string
}
]
"chatbots"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"groups"?: [ // 知識庫可存取的群組列表 (非必填)
{
"id": string (uuid)
"name": string
}
]
"filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
"vectorStorageSize": integer
"chunksCount": integer
"isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
"canUpdate": boolean // Return whether the current user can update this resource.
"canDelete": boolean // Return whether the current user can delete this resource.
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
"canRead"?: boolean // 非必填
"canUpdate"?: boolean // 非必填
"canDelete"?: boolean // 非必填
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"group": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": "550e8400-e29b-41d4-a716-446655440000",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"numberOfRetrievedChunks": 456,
"sentenceWindowSize": 456,
"enableHyde": false,
"similarityCutoff": 456,
"enableRerank": false,
"enableRrf": false,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "回應字串",
"vectorDatabaseApiKey": "回應字串",
"opensearchUsername": "回應字串",
"opensearchPassword": "回應字串",
"oracleUser": "回應字串",
"oraclePassword": "回應字串",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"filesCount": 456,
"vectorStorageSize": 456,
"chunksCount": 456,
"isMultimodal": false,
"canUpdate": false,
"canDelete": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
},
"canRead": false,
"canUpdate": false,
"canDelete": false,
"createdAt": "回應字串"
}
]
}
```
***
### 取得角色的知識庫列表
GET `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-knowledge-bases/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/?page=1&pageSize=1&query=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/?page=1&pageSize=1&query=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/?page=1&pageSize=1&query=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/?page=1&pageSize=1&query=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"group": string (uuid)
"knowledgeBase":
{
"id": string (uuid)
"createdBy"?: string (uuid) // 非必填
"organization"?: string (uuid) // 非必填
"embeddingModel": string (uuid)
"rerankerModel": string (uuid)
"name": string
"description"?: string // 非必填
"numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
"sentenceWindowSize"?: integer // RAG 擴增句子視窗大小，預設為 2，最小值為 0 (非必填)
"enableHyde"?: boolean // 啟用 HyDE，預設為 False (非必填)
"similarityCutoff"?: number (double) // 相似度門檻，預設為 0.0，範圍為 0.0-1.0 (非必填)
"enableRerank"?: boolean // 是否啟用重新排序，預設為 True (非必填)
"enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (非必填)
"vectorDatabaseType"?: // Type of vector database: elasticsearch or opensearch.
* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai (非必填)
{
}
"vectorDatabaseUrl"?: string // Custom vector database endpoint URL or Oracle DSN. For Elasticsearch/OpenSearch: URL format (e.g., "https://host:9200"). For Oracle: DSN format (e.g., "host:1521/service_name"). (非必填)
"vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (非必填)
"opensearchUsername"?: string // Username for OpenSearch Basic Auth. (非必填)
"opensearchPassword"?: string // Password for OpenSearch Basic Auth. (非必填)
"oracleUser"?: string // Oracle database username. (非必填)
"oraclePassword"?: string // Oracle database password. (非必填)
"labels": [
{
"id": string (uuid)
"name": string
}
]
"chatbots"?: [ // 非必填
{
"id": string (uuid)
"name": string
}
]
"groups"?: [ // 知識庫可存取的群組列表 (非必填)
{
"id": string (uuid)
"name": string
}
]
"filesCount": integer // Return count of KnowledgeBaseFile excluding processed files, conversation attachments, and soft-deleted.
"vectorStorageSize": integer
"chunksCount": integer
"isMultimodal"?: boolean // Whether this knowledge base supports multimodal embeddings (text + images). (非必填)
"canUpdate": boolean // Return whether the current user can update this resource.
"canDelete": boolean // Return whether the current user can delete this resource.
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
"canRead"?: boolean // 非必填
"canUpdate"?: boolean // 非必填
"canDelete"?: boolean // 非必填
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"group": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"createdBy": "550e8400-e29b-41d4-a716-446655440000",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
"rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"numberOfRetrievedChunks": 456,
"sentenceWindowSize": 456,
"enableHyde": false,
"similarityCutoff": 456,
"enableRerank": false,
"enableRrf": false,
"vectorDatabaseType": {},
"vectorDatabaseUrl": "回應字串",
"vectorDatabaseApiKey": "回應字串",
"opensearchUsername": "回應字串",
"opensearchPassword": "回應字串",
"oracleUser": "回應字串",
"oraclePassword": "回應字串",
"labels": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"filesCount": 456,
"vectorStorageSize": 456,
"chunksCount": 456,
"isMultimodal": false,
"canUpdate": false,
"canDelete": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
},
"canRead": false,
"canUpdate": false,
"canDelete": false,
"createdAt": "回應字串"
}
]
}
```
***
### 取得角色的資料庫列表
GET `/api/organizations/{organizationPk}/groups/{groupPk}/group-databases/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/?page=1&pageSize=1&query=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/?page=1&pageSize=1&query=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/?page=1&pageSize=1&query=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/?page=1&pageSize=1&query=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"group": string (uuid)
"database":
{
"id": string (uuid)
"name": string // Display name for this database connection
"description": string // Description of the database and its purpose
"databaseType": // Type of database: PostgreSQL, MySQL, MSSQL, Oracle, or MaiAgent
* `postgresql` - PostgreSQL
* `mysql` - MySQL
* `maiagent` - MaiAgent
* `oracle` - Oracle
* `mssql` - MSSQL
{
}
"databaseUrl": string // Connection string for external databases. Not required for MaiAgent type as it uses the system default.
"includeTables": object // Optional list of tables to include. Format: {"tables": ["table1", "table2"]}. For MaiAgent type, this is auto-populated from uploaded files.
"isActive": boolean // When disabled, this database will not be used in Text-to-SQL queries
"status":
{
}
"deletedAt": string (timestamp)
"tables": [
{
"id": string (uuid)
"tableName": string // Name of the table in the database
"description"?: string // Description of the table and its data for better Text-to-SQL understanding (非必填)
"status":
{
}
"errorMessage": string // Error details if table creation or deletion failed
"sourceFile":
{
"id": string (uuid)
"name": string
"isFromKnowledgeBase": boolean // Determine if the source file originated from a knowledge base upload.
Returns True if the file was uploaded via knowledge base,
False if uploaded directly to the database.
}
"columns": [
{
"id": string (uuid)
"columnName": string
"columnType"?: string // Data type of the column (e.g., VARCHAR, INTEGER, TIMESTAMP) (非必填)
"description"?: string // Description of the column for better Text-to-SQL understanding (非必填)
"isPrimaryKey"?: boolean // 非必填
"isNullable"?: boolean // 非必填
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"chatbots": [
{
"id": string (uuid)
"name": string
}
]
"groups": [
{
"id": string (uuid)
"name": string
}
]
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
"canRead"?: boolean // 非必填
"canUpdate"?: boolean // 非必填
"canDelete"?: boolean // 非必填
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"group": "550e8400-e29b-41d4-a716-446655440000",
"database": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"databaseType": {},
"databaseUrl": "回應字串",
"includeTables": null,
"isActive": false,
"status": {},
"deletedAt": "回應字串",
"tables": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"tableName": "回應字串",
"description": "回應字串",
"status": {},
"errorMessage": "回應字串",
"sourceFile": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"isFromKnowledgeBase": false
},
"columns": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"columnName": "回應字串",
"columnType": "回應字串",
"description": "回應字串",
"isPrimaryKey": false,
"isNullable": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
],
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
],
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"createdAt": "回應字串",
"updatedAt": "回應字串"
},
"canRead": false,
"canUpdate": false,
"canDelete": false,
"createdAt": "回應字串"
}
]
}
```
***
### 取得角色的資料庫列表
GET `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-databases/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ---------------------------------------------- |
| `groupPk` | ✅ | string | |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
| `page` | ❌ | integer | A page number within the paginated result set. |
| `pageSize` | ❌ | integer | Number of results to return per page. |
| `query` | ❌ | string | |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/?page=1&pageSize=1&query=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/?page=1&pageSize=1&query=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/?page=1&pageSize=1&query=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/?page=1&pageSize=1&query=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"group": string (uuid)
"database":
{
"id": string (uuid)
"name": string // Display name for this database connection
"description": string // Description of the database and its purpose
"databaseType": // Type of database: PostgreSQL, MySQL, MSSQL, Oracle, or MaiAgent
* `postgresql` - PostgreSQL
* `mysql` - MySQL
* `maiagent` - MaiAgent
* `oracle` - Oracle
* `mssql` - MSSQL
{
}
"databaseUrl": string // Connection string for external databases. Not required for MaiAgent type as it uses the system default.
"includeTables": object // Optional list of tables to include. Format: {"tables": ["table1", "table2"]}. For MaiAgent type, this is auto-populated from uploaded files.
"isActive": boolean // When disabled, this database will not be used in Text-to-SQL queries
"status":
{
}
"deletedAt": string (timestamp)
"tables": [
{
"id": string (uuid)
"tableName": string // Name of the table in the database
"description"?: string // Description of the table and its data for better Text-to-SQL understanding (非必填)
"status":
{
}
"errorMessage": string // Error details if table creation or deletion failed
"sourceFile":
{
"id": string (uuid)
"name": string
"isFromKnowledgeBase": boolean // Determine if the source file originated from a knowledge base upload.
Returns True if the file was uploaded via knowledge base,
False if uploaded directly to the database.
}
"columns": [
{
"id": string (uuid)
"columnName": string
"columnType"?: string // Data type of the column (e.g., VARCHAR, INTEGER, TIMESTAMP) (非必填)
"description"?: string // Description of the column for better Text-to-SQL understanding (非必填)
"isPrimaryKey"?: boolean // 非必填
"isNullable"?: boolean // 非必填
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
"chatbots": [
{
"id": string (uuid)
"name": string
}
]
"groups": [
{
"id": string (uuid)
"name": string
}
]
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
"canRead"?: boolean // 非必填
"canUpdate"?: boolean // 非必填
"canDelete"?: boolean // 非必填
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"group": "550e8400-e29b-41d4-a716-446655440000",
"database": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"databaseType": {},
"databaseUrl": "回應字串",
"includeTables": null,
"isActive": false,
"status": {},
"deletedAt": "回應字串",
"tables": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"tableName": "回應字串",
"description": "回應字串",
"status": {},
"errorMessage": "回應字串",
"sourceFile": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"isFromKnowledgeBase": false
},
"columns": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"columnName": "回應字串",
"columnType": "回應字串",
"description": "回應字串",
"isPrimaryKey": false,
"isNullable": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
],
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
],
"chatbots": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"groups": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
],
"createdAt": "回應字串",
"updatedAt": "回應字串"
},
"canRead": false,
"canUpdate": false,
"canDelete": false,
"createdAt": "回應字串"
}
]
}
```
***
### 更新角色權限
PUT `/api/organizations/{organizationPk}/groups/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Group. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ---------------------- | -------------- | -- | -- |
| name | string | 是 | |
| organization | string (uuid) | 否 | |
| permissions | array\[string] | 是 | |
| canCreateChatbot | boolean | 否 | |
| canCreateKnowledgeBase | boolean | 否 | |
| canCreateInbox | boolean | 否 | |
| canCreateDatabase | boolean | 否 | |
**請求結構範例**
```typescript
{
"name": string
"organization"?: string (uuid) // 非必填
"permissions": [
string (uuid)
]
"canCreateChatbot"?: boolean // 非必填
"canCreateKnowledgeBase"?: boolean // 非必填
"canCreateInbox"?: boolean // 非必填
"canCreateDatabase"?: boolean // 非必填
}
```
**請求範例值**
```json
{
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
};
axios.put("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}
response = requests.put(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"type":
{
}
"permissions": [ // 返回群組的權限列表
處理流程：
1. 將群組權限分為父權限和子權限
2. 將子權限按父權限 ID 分組
3. 若有子權限缺少父權限，自動從資料庫載入缺少的父權限
4. 將父權限和對應的子權限序列化，並按 order 排序
object
]
"membersPreview": [ // 返回前 10 個成員名稱（用於列表顯示前 3 個和 tooltip 顯示 10 個）
string
]
"membersCount": integer // 返回剩餘成員數量（扣除列表顯示的 3 人後），用於前端 +N badge 顯示
與資源 count 不同：
- members_count: 返回 total - 3（用於 +N badge），None 表示總數 <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: 返回總數量
"chatbotsCount": integer // 返回 AI 助理總數量
"chatbotsPreview": [ // 返回前 10 個 AI 助理名稱
string
]
"knowledgeBasesCount": integer // 返回知識庫總數量
"knowledgeBasesPreview": [ // 返回前 10 個知識庫名稱
string
]
"inboxesCount": integer // 返回對話平台總數量
"inboxesPreview": [ // 返回前 10 個對話平台名稱
string
]
"databasesCount": integer // 返回資料庫總數量
"databasesPreview": [ // 返回前 10 個資料庫名稱
string
]
"canCreateChatbot"?: boolean // 非必填
"canCreateKnowledgeBase"?: boolean // 非必填
"canCreateInbox"?: boolean // 非必填
"canCreateDatabase"?: boolean // 非必填
"createdAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"type": {},
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"membersPreview": [
"回應字串"
],
"membersCount": 456,
"chatbotsCount": 456,
"chatbotsPreview": [
"回應字串"
],
"knowledgeBasesCount": 456,
"knowledgeBasesPreview": [
"回應字串"
],
"inboxesCount": 456,
"inboxesPreview": [
"回應字串"
],
"databasesCount": 456,
"databasesPreview": [
"回應字串"
],
"canCreateChatbot": false,
"canCreateKnowledgeBase": false,
"canCreateInbox": false,
"canCreateDatabase": false,
"createdAt": "回應字串"
}
```
***
### 更新角色權限
PUT `/api/v1/organizations/{organizationPk}/groups/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Group. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ---------------------- | -------------- | -- | -- |
| name | string | 是 | |
| organization | string (uuid) | 否 | |
| permissions | array\[string] | 是 | |
| canCreateChatbot | boolean | 否 | |
| canCreateKnowledgeBase | boolean | 否 | |
| canCreateInbox | boolean | 否 | |
| canCreateDatabase | boolean | 否 | |
**請求結構範例**
```typescript
{
"name": string
"organization"?: string (uuid) // 非必填
"permissions": [
string (uuid)
]
"canCreateChatbot"?: boolean // 非必填
"canCreateKnowledgeBase"?: boolean // 非必填
"canCreateInbox"?: boolean // 非必填
"canCreateDatabase"?: boolean // 非必填
}
```
**請求範例值**
```json
{
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
};
axios.put("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}
response = requests.put(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"type":
{
}
"permissions": [ // 返回群組的權限列表
處理流程：
1. 將群組權限分為父權限和子權限
2. 將子權限按父權限 ID 分組
3. 若有子權限缺少父權限，自動從資料庫載入缺少的父權限
4. 將父權限和對應的子權限序列化，並按 order 排序
object
]
"membersPreview": [ // 返回前 10 個成員名稱（用於列表顯示前 3 個和 tooltip 顯示 10 個）
string
]
"membersCount": integer // 返回剩餘成員數量（扣除列表顯示的 3 人後），用於前端 +N badge 顯示
與資源 count 不同：
- members_count: 返回 total - 3（用於 +N badge），None 表示總數 <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: 返回總數量
"chatbotsCount": integer // 返回 AI 助理總數量
"chatbotsPreview": [ // 返回前 10 個 AI 助理名稱
string
]
"knowledgeBasesCount": integer // 返回知識庫總數量
"knowledgeBasesPreview": [ // 返回前 10 個知識庫名稱
string
]
"inboxesCount": integer // 返回對話平台總數量
"inboxesPreview": [ // 返回前 10 個對話平台名稱
string
]
"databasesCount": integer // 返回資料庫總數量
"databasesPreview": [ // 返回前 10 個資料庫名稱
string
]
"canCreateChatbot"?: boolean // 非必填
"canCreateKnowledgeBase"?: boolean // 非必填
"canCreateInbox"?: boolean // 非必填
"canCreateDatabase"?: boolean // 非必填
"createdAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"type": {},
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"membersPreview": [
"回應字串"
],
"membersCount": 456,
"chatbotsCount": 456,
"chatbotsPreview": [
"回應字串"
],
"knowledgeBasesCount": 456,
"knowledgeBasesPreview": [
"回應字串"
],
"inboxesCount": 456,
"inboxesPreview": [
"回應字串"
],
"databasesCount": 456,
"databasesPreview": [
"回應字串"
],
"canCreateChatbot": false,
"canCreateKnowledgeBase": false,
"canCreateInbox": false,
"canCreateDatabase": false,
"createdAt": "回應字串"
}
```
***
### 部分更新角色權限
PATCH `/api/organizations/{organizationPk}/groups/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Group. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ---------------------- | -------------- | -- | -- |
| name | string | 否 | |
| organization | string (uuid) | 否 | |
| permissions | array\[string] | 否 | |
| canCreateChatbot | boolean | 否 | |
| canCreateKnowledgeBase | boolean | 否 | |
| canCreateInbox | boolean | 否 | |
| canCreateDatabase | boolean | 否 | |
**請求結構範例**
```typescript
{
"name"?: string // 非必填
"organization"?: string (uuid) // 非必填
"permissions"?: [ // 非必填
string (uuid)
]
"canCreateChatbot"?: boolean // 非必填
"canCreateKnowledgeBase"?: boolean // 非必填
"canCreateInbox"?: boolean // 非必填
"canCreateDatabase"?: boolean // 非必填
}
```
**請求範例值**
```json
{
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
};
axios.patch("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}
response = requests.patch(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"type":
{
}
"permissions": [ // 返回群組的權限列表
處理流程：
1. 將群組權限分為父權限和子權限
2. 將子權限按父權限 ID 分組
3. 若有子權限缺少父權限，自動從資料庫載入缺少的父權限
4. 將父權限和對應的子權限序列化，並按 order 排序
object
]
"membersPreview": [ // 返回前 10 個成員名稱（用於列表顯示前 3 個和 tooltip 顯示 10 個）
string
]
"membersCount": integer // 返回剩餘成員數量（扣除列表顯示的 3 人後），用於前端 +N badge 顯示
與資源 count 不同：
- members_count: 返回 total - 3（用於 +N badge），None 表示總數 <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: 返回總數量
"chatbotsCount": integer // 返回 AI 助理總數量
"chatbotsPreview": [ // 返回前 10 個 AI 助理名稱
string
]
"knowledgeBasesCount": integer // 返回知識庫總數量
"knowledgeBasesPreview": [ // 返回前 10 個知識庫名稱
string
]
"inboxesCount": integer // 返回對話平台總數量
"inboxesPreview": [ // 返回前 10 個對話平台名稱
string
]
"databasesCount": integer // 返回資料庫總數量
"databasesPreview": [ // 返回前 10 個資料庫名稱
string
]
"canCreateChatbot"?: boolean // 非必填
"canCreateKnowledgeBase"?: boolean // 非必填
"canCreateInbox"?: boolean // 非必填
"canCreateDatabase"?: boolean // 非必填
"createdAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"type": {},
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"membersPreview": [
"回應字串"
],
"membersCount": 456,
"chatbotsCount": 456,
"chatbotsPreview": [
"回應字串"
],
"knowledgeBasesCount": 456,
"knowledgeBasesPreview": [
"回應字串"
],
"inboxesCount": 456,
"inboxesPreview": [
"回應字串"
],
"databasesCount": 456,
"databasesPreview": [
"回應字串"
],
"canCreateChatbot": false,
"canCreateKnowledgeBase": false,
"canCreateInbox": false,
"canCreateDatabase": false,
"createdAt": "回應字串"
}
```
***
### 部分更新角色權限
PATCH `/api/v1/organizations/{organizationPk}/groups/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Group. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ---------------------- | -------------- | -- | -- |
| name | string | 否 | |
| organization | string (uuid) | 否 | |
| permissions | array\[string] | 否 | |
| canCreateChatbot | boolean | 否 | |
| canCreateKnowledgeBase | boolean | 否 | |
| canCreateInbox | boolean | 否 | |
| canCreateDatabase | boolean | 否 | |
**請求結構範例**
```typescript
{
"name"?: string // 非必填
"organization"?: string (uuid) // 非必填
"permissions"?: [ // 非必填
string (uuid)
]
"canCreateChatbot"?: boolean // 非必填
"canCreateKnowledgeBase"?: boolean // 非必填
"canCreateInbox"?: boolean // 非必填
"canCreateDatabase"?: boolean // 非必填
}
```
**請求範例值**
```json
{
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
};
axios.patch("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}
response = requests.patch(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => {
"name": "範例名稱",
"organization": "550e8400-e29b-41d4-a716-446655440000",
"permissions": [
"550e8400-e29b-41d4-a716-446655440000"
],
"canCreateChatbot": true,
"canCreateKnowledgeBase": true,
"canCreateInbox": true,
"canCreateDatabase": true
}
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"type":
{
}
"permissions": [ // 返回群組的權限列表
處理流程：
1. 將群組權限分為父權限和子權限
2. 將子權限按父權限 ID 分組
3. 若有子權限缺少父權限，自動從資料庫載入缺少的父權限
4. 將父權限和對應的子權限序列化，並按 order 排序
object
]
"membersPreview": [ // 返回前 10 個成員名稱（用於列表顯示前 3 個和 tooltip 顯示 10 個）
string
]
"membersCount": integer // 返回剩餘成員數量（扣除列表顯示的 3 人後），用於前端 +N badge 顯示
與資源 count 不同：
- members_count: 返回 total - 3（用於 +N badge），None 表示總數 <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: 返回總數量
"chatbotsCount": integer // 返回 AI 助理總數量
"chatbotsPreview": [ // 返回前 10 個 AI 助理名稱
string
]
"knowledgeBasesCount": integer // 返回知識庫總數量
"knowledgeBasesPreview": [ // 返回前 10 個知識庫名稱
string
]
"inboxesCount": integer // 返回對話平台總數量
"inboxesPreview": [ // 返回前 10 個對話平台名稱
string
]
"databasesCount": integer // 返回資料庫總數量
"databasesPreview": [ // 返回前 10 個資料庫名稱
string
]
"canCreateChatbot"?: boolean // 非必填
"canCreateKnowledgeBase"?: boolean // 非必填
"canCreateInbox"?: boolean // 非必填
"canCreateDatabase"?: boolean // 非必填
"createdAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"type": {},
"permissions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"membersPreview": [
"回應字串"
],
"membersCount": 456,
"chatbotsCount": 456,
"chatbotsPreview": [
"回應字串"
],
"knowledgeBasesCount": 456,
"knowledgeBasesPreview": [
"回應字串"
],
"inboxesCount": 456,
"inboxesPreview": [
"回應字串"
],
"databasesCount": 456,
"databasesPreview": [
"回應字串"
],
"canCreateChatbot": false,
"canCreateKnowledgeBase": false,
"canCreateInbox": false,
"canCreateDatabase": false,
"createdAt": "回應字串"
}
```
***
### 刪除角色
DELETE `/api/organizations/{organizationPk}/groups/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Group. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 刪除角色
DELETE `/api/v1/organizations/{organizationPk}/groups/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------- |
| `id` | ✅ | string | A UUID string identifying this Group. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 移除角色成員
DELETE `/api/organizations/{organizationPk}/groups/{groupPk}/group-members/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | -------------------------------------------- |
| `groupPk` | ✅ | string | |
| `id` | ✅ | string | A UUID string identifying this Group Member. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 移除角色成員
DELETE `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-members/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | -------------------------------------------- |
| `groupPk` | ✅ | string | |
| `id` | ✅ | string | A UUID string identifying this Group Member. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-members/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 移除角色裡的 AI 助理
DELETE `/api/organizations/{organizationPk}/groups/{groupPk}/group-chatbots/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | --------------------------------------------- |
| `groupPk` | ✅ | string | |
| `id` | ✅ | string | A UUID string identifying this Group Chatbot. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 移除角色裡的 AI 助理
DELETE `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-chatbots/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | --------------------------------------------- |
| `groupPk` | ✅ | string | |
| `id` | ✅ | string | A UUID string identifying this Group Chatbot. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-chatbots/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 移除角色裡的收件匣
DELETE `/api/organizations/{organizationPk}/groups/{groupPk}/group-inboxes/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------------- |
| `groupPk` | ✅ | string | |
| `id` | ✅ | string | A UUID string identifying this Group Inbox. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 移除角色裡的收件匣
DELETE `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-inboxes/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ------------------------------------------- |
| `groupPk` | ✅ | string | |
| `id` | ✅ | string | A UUID string identifying this Group Inbox. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-inboxes/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 移除角色裡的知識庫
DELETE `/api/organizations/{organizationPk}/groups/{groupPk}/group-knowledge-bases/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | --------------------------------------------------- |
| `groupPk` | ✅ | string | |
| `id` | ✅ | string | A UUID string identifying this Group KnowledgeBase. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 移除角色裡的知識庫
DELETE `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-knowledge-bases/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | --------------------------------------------------- |
| `groupPk` | ✅ | string | |
| `id` | ✅ | string | A UUID string identifying this Group KnowledgeBase. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-knowledge-bases/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 移除角色裡的資料庫
DELETE `/api/organizations/{organizationPk}/groups/{groupPk}/group-databases/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ---------------------------------------------- |
| `groupPk` | ✅ | string | |
| `id` | ✅ | string | A UUID string identifying this Group Database. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 移除角色裡的資料庫
DELETE `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-databases/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------ | ---------------------------------------------- |
| `groupPk` | ✅ | string | |
| `id` | ✅ | string | A UUID string identifying this Group Database. |
| `organizationPk` | ✅ | string | A UUID string identifying this 組織 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/550e8400-e29b-41d4-a716-446655440000/group-databases/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
---
# Agent Instructions: 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:
```
GET https://docs.maiagent.ai/api/api-reference/jue-se-he-quan-xian.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.