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

# 角色與權限

### 建立角色 <a href="#organizations-groups-create" id="organizations-groups-create"></a>

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        | 否  |                                                                                                                                                                                                             |
| canCreateTool            | boolean        | 否  |                                                                                                                                                                                                             |
| canCreateAgentUiTool     | boolean        | 否  |                                                                                                                                                                                                             |
| canCreateSkill           | boolean        | 否  |                                                                                                                                                                                                             |
| canCreateTeam            | boolean        | 否  | Whether members of this role may create Agent Teams; the Team permission is still required.                                                                                                                 |
| canCreatePersonalSkill   | boolean        | 否  | Whether members of this role may create personal skills (skills only they can see and use). A member in several roles may if any of them allows it. Turning it off keeps existing personal skills but no... |
| canCreateVoiceAgent      | boolean        | 否  | Whether members of this role may create voice agents; the Voice Agent permission is still required.                                                                                                         |
| maigptCanCodeInterpreter | boolean        | 否  | Whether members of this role may use the code interpreter built-in tool in MaiGPT.                                                                                                                          |
| maigptCanRag             | boolean        | 否  | Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT.                                                                                                                        |
| maigptCanDeepResearch    | boolean        | 否  | Whether members of this role may use Deep Research in MaiGPT. Deep Research reaches the public internet through its own built-in search, so a role that revokes the official web-search tools needs this... |
| maigptCanBrowserTool     | boolean        | 否  | Whether members of this role may use the browser built-in tool in MaiGPT.                                                                                                                                   |
| maigptCanCloudDesktop    | boolean        | 否  | Whether members of this role may use the cloud desktop in MaiGPT.                                                                                                                                           |
| maigptCanVoiceInput      | boolean        | 否  | Whether members of this role may use voice input in MaiGPT, billed by the seconds recorded.                                                                                                                 |
| maigptAllLlms            | boolean        | 否  | Whether members of this role may use every organization-available LLM in MaiGPT. Off = only the bound LLMs; an empty binding then means none.                                                               |
| maigptAllTools           | boolean        | 否  | Whether members of this role may call every official (global) tool in MaiGPT. Off = only the bound tools; an empty binding then means none.                                                                 |
| maigptAllConnectors      | boolean        | 否  | Whether members of this role may call every official (global) MCP connector in MaiGPT. Off = only the bound connectors; an empty binding then means none.                                                   |
| maigptAllSkills          | boolean        | 否  | Whether members of this role may use every official (global) skill in MaiGPT. Off = only the bound skills; an empty binding then means none.                                                                |
| usageStatisticsScope     | object         | 否  | What this role's usage statistics permission shows: the whole organization, or only the AI assistants granted to the member's roles. A member with any organization-wide granting role sees the whole or... |
| allowedLlms              | array\[string] | 否  |                                                                                                                                                                                                             |
| allowedTools             | array\[string] | 否  |                                                                                                                                                                                                             |
| allowedConnectors        | array\[string] | 否  |                                                                                                                                                                                                             |
| allowedSkills            | array\[string] | 否  |                                                                                                                                                                                                             |

**請求結構範例**

```typescript
{
  "name": string
  "organization"?: string (uuid) // 非必填
  "permissions": [
    string (uuid)
  ]
  "canCreateChatbot"?: boolean // 非必填
  "canCreateKnowledgeBase"?: boolean // 非必填
  "canCreateInbox"?: boolean // 非必填
  "canCreateDatabase"?: boolean // 非必填
  "canCreateTool"?: boolean // 非必填
  "canCreateAgentUiTool"?: boolean // 非必填
  "canCreateSkill"?: boolean // 非必填
  "canCreateTeam"?: boolean // Whether members of this role may create Agent Teams; the Team permission is still required. (非必填)
  "canCreatePersonalSkill"?: boolean // Whether members of this role may create personal skills (skills only they can see and use). A member in several roles may if any of them allows it. Turning it off keeps existing personal skills but no new ones can be created. (非必填)
  "canCreateVoiceAgent"?: boolean // Whether members of this role may create voice agents; the Voice Agent permission is still required. (非必填)
  "maigptCanCodeInterpreter"?: boolean // Whether members of this role may use the code interpreter built-in tool in MaiGPT. (非必填)
  "maigptCanRag"?: boolean // Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT. (非必填)
  "maigptCanDeepResearch"?: boolean // Whether members of this role may use Deep Research in MaiGPT. Deep Research reaches the public internet through its own built-in search, so a role that revokes the official web-search tools needs this switch too. (非必填)
  "maigptCanBrowserTool"?: boolean // Whether members of this role may use the browser built-in tool in MaiGPT. (非必填)
  "maigptCanCloudDesktop"?: boolean // Whether members of this role may use the cloud desktop in MaiGPT. (非必填)
  "maigptCanVoiceInput"?: boolean // Whether members of this role may use voice input in MaiGPT, billed by the seconds recorded. (非必填)
  "maigptAllLlms"?: boolean // Whether members of this role may use every organization-available LLM in MaiGPT. Off = only the bound LLMs; an empty binding then means none. (非必填)
  "maigptAllTools"?: boolean // Whether members of this role may call every official (global) tool in MaiGPT. Off = only the bound tools; an empty binding then means none. (非必填)
  "maigptAllConnectors"?: boolean // Whether members of this role may call every official (global) MCP connector in MaiGPT. Off = only the bound connectors; an empty binding then means none. (非必填)
  "maigptAllSkills"?: boolean // Whether members of this role may use every official (global) skill in MaiGPT. Off = only the bound skills; an empty binding then means none. (非必填)
  "usageStatisticsScope"?:  // What this role's usage statistics permission shows: the whole organization, or only the AI assistants granted to the member's roles. A member with any organization-wide granting role sees the whole organization.

* `organization` - Organization-wide
* `accessible_chatbots` - Authorized AI assistants only (非必填)
  {
  }
  "allowedLlms"?: [ // 非必填
    string (uuid)
  ]
  "allowedTools"?: [ // 非必填
    string (uuid)
  ]
  "allowedConnectors"?: [ // 非必填
    string (uuid)
  ]
  "allowedSkills"?: [ // 非必填
    string (uuid)
  ]
}
```

**請求範例值**

```json
{
  "name": "範例名稱",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "permissions": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "canCreateChatbot": true,
  "canCreateKnowledgeBase": true,
  "canCreateInbox": true,
  "canCreateDatabase": true,
  "canCreateTool": true,
  "canCreateAgentUiTool": true,
  "canCreateSkill": true,
  "canCreateTeam": true,
  "canCreatePersonalSkill": true,
  "canCreateVoiceAgent": true,
  "maigptCanCodeInterpreter": true,
  "maigptCanRag": true,
  "maigptCanDeepResearch": true,
  "maigptCanBrowserTool": true,
  "maigptCanCloudDesktop": true,
  "maigptCanVoiceInput": true,
  "maigptAllLlms": true,
  "maigptAllTools": true,
  "maigptAllConnectors": true,
  "maigptAllSkills": true,
  "usageStatisticsScope": {},
  "allowedLlms": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "allowedTools": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "allowedConnectors": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "allowedSkills": [
    "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/" \
  -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,
    "canCreateTool": true,
    "canCreateAgentUiTool": true,
    "canCreateSkill": true,
    "canCreateTeam": true,
    "canCreatePersonalSkill": true,
    "canCreateVoiceAgent": true,
    "maigptCanCodeInterpreter": true,
    "maigptCanRag": true,
    "maigptCanDeepResearch": true,
    "maigptCanBrowserTool": true,
    "maigptCanCloudDesktop": true,
    "maigptCanVoiceInput": true,
    "maigptAllLlms": true,
    "maigptAllTools": true,
    "maigptAllConnectors": true,
    "maigptAllSkills": true,
    "usageStatisticsScope": {},
    "allowedLlms": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedTools": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedConnectors": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedSkills": [
      "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 = {
    "name": "範例名稱",
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "permissions": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "canCreateChatbot": true,
    "canCreateKnowledgeBase": true,
    "canCreateInbox": true,
    "canCreateDatabase": true,
    "canCreateTool": true,
    "canCreateAgentUiTool": true,
    "canCreateSkill": true,
    "canCreateTeam": true,
    "canCreatePersonalSkill": true,
    "canCreateVoiceAgent": true,
    "maigptCanCodeInterpreter": true,
    "maigptCanRag": true,
    "maigptCanDeepResearch": true,
    "maigptCanBrowserTool": true,
    "maigptCanCloudDesktop": true,
    "maigptCanVoiceInput": true,
    "maigptAllLlms": true,
    "maigptAllTools": true,
    "maigptAllConnectors": true,
    "maigptAllSkills": true,
    "usageStatisticsScope": {},
    "allowedLlms": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedTools": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedConnectors": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedSkills": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  };

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,
    "canCreateTool": True,
    "canCreateAgentUiTool": True,
    "canCreateSkill": True,
    "canCreateTeam": True,
    "canCreatePersonalSkill": True,
    "canCreateVoiceAgent": True,
    "maigptCanCodeInterpreter": True,
    "maigptCanRag": True,
    "maigptCanDeepResearch": True,
    "maigptCanBrowserTool": True,
    "maigptCanCloudDesktop": True,
    "maigptCanVoiceInput": True,
    "maigptAllLlms": True,
    "maigptAllTools": True,
    "maigptAllConnectors": True,
    "maigptAllSkills": True,
    "usageStatisticsScope": {},
    "allowedLlms": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedTools": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedConnectors": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedSkills": [
        "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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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,
            'canCreateTool' => true,
            'canCreateAgentUiTool' => true,
            'canCreateSkill' => true,
            'canCreateTeam' => true,
            'canCreatePersonalSkill' => true,
            'canCreateVoiceAgent' => true,
            'maigptCanCodeInterpreter' => true,
            'maigptCanRag' => true,
            'maigptCanDeepResearch' => true,
            'maigptCanBrowserTool' => true,
            'maigptCanCloudDesktop' => true,
            'maigptCanVoiceInput' => true,
            'maigptAllLlms' => true,
            'maigptAllTools' => true,
            'maigptAllConnectors' => true,
            'maigptAllSkills' => true,
            'usageStatisticsScope' => new \stdClass(),
            'allowedLlms' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'allowedTools' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'allowedConnectors' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'allowedSkills' => [
                '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)
  "name": string
  "type": 
  {
  }
  "permissions": [
    object
  ]
  "membersPreview": [
    string
  ]
  "membersCount": integer // 返回剩餘成員數量（扣除列表顯示的 3 人後），用於前端 +N badge 顯示

與資源 count 不同：
- members_count: 返回 total - 3（用於 +N badge），None 表示總數 <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: 返回總數量
  "chatbotsCount": integer
  "chatbotsPreview": [
    string
  ]
  "knowledgeBasesCount": integer
  "knowledgeBasesPreview": [
    string
  ]
  "inboxesCount": integer
  "inboxesPreview": [
    string
  ]
  "databasesCount": integer
  "databasesPreview": [
    string
  ]
  "canCreateChatbot"?: boolean // 非必填
  "canCreateKnowledgeBase"?: boolean // 非必填
  "canCreateInbox"?: boolean // 非必填
  "canCreateDatabase"?: boolean // 非必填
  "canCreateTool"?: boolean // 非必填
  "canCreateAgentUiTool"?: boolean // 非必填
  "canCreateSkill"?: boolean // 非必填
  "canCreateTeam"?: boolean // Whether members of this role may create Agent Teams; the Team permission is still required. (非必填)
  "canCreatePersonalSkill"?: boolean // Whether members of this role may create personal skills (skills only they can see and use). A member in several roles may if any of them allows it. Turning it off keeps existing personal skills but no new ones can be created. (非必填)
  "canCreateVoiceAgent"?: boolean // Whether members of this role may create voice agents; the Voice Agent permission is still required. (非必填)
  "maigptCanCodeInterpreter"?: boolean // Whether members of this role may use the code interpreter built-in tool in MaiGPT. (非必填)
  "maigptCanRag"?: boolean // Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT. (非必填)
  "maigptCanDeepResearch"?: boolean // Whether members of this role may use Deep Research in MaiGPT. Deep Research reaches the public internet through its own built-in search, so a role that revokes the official web-search tools needs this switch too. (非必填)
  "maigptCanBrowserTool"?: boolean // Whether members of this role may use the browser built-in tool in MaiGPT. (非必填)
  "maigptCanCloudDesktop"?: boolean // Whether members of this role may use the cloud desktop in MaiGPT. (非必填)
  "maigptCanVoiceInput"?: boolean // Whether members of this role may use voice input in MaiGPT, billed by the seconds recorded. (非必填)
  "maigptAllLlms"?: boolean // Whether members of this role may use every organization-available LLM in MaiGPT. Off = only the bound LLMs; an empty binding then means none. (非必填)
  "maigptAllTools"?: boolean // Whether members of this role may call every official (global) tool in MaiGPT. Off = only the bound tools; an empty binding then means none. (非必填)
  "maigptAllConnectors"?: boolean // Whether members of this role may call every official (global) MCP connector in MaiGPT. Off = only the bound connectors; an empty binding then means none. (非必填)
  "maigptAllSkills"?: boolean // Whether members of this role may use every official (global) skill in MaiGPT. Off = only the bound skills; an empty binding then means none. (非必填)
  "usageStatisticsScope"?:  // What this role's usage statistics permission shows: the whole organization, or only the AI assistants granted to the member's roles. A member with any organization-wide granting role sees the whole organization.

* `organization` - Organization-wide
* `accessible_chatbots` - Authorized AI assistants only (非必填)
  {
  }
  "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,
  "canCreateTool": false,
  "canCreateAgentUiTool": false,
  "canCreateSkill": false,
  "canCreateTeam": false,
  "canCreatePersonalSkill": false,
  "canCreateVoiceAgent": false,
  "maigptCanCodeInterpreter": false,
  "maigptCanRag": false,
  "maigptCanDeepResearch": false,
  "maigptCanBrowserTool": false,
  "maigptCanCloudDesktop": false,
  "maigptCanVoiceInput": false,
  "maigptAllLlms": false,
  "maigptAllTools": false,
  "maigptAllConnectors": false,
  "maigptAllSkills": false,
  "usageStatisticsScope": {},
  "createdAt": "回應字串"
}
```

***

### 批量新增角色成員 <a href="#organizations-groups-group-members-bulk-create-create" id="organizations-groups-group-members-bulk-create-create"></a>

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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 // 聊天機器人數量 (非必填)
          "countableChatbotsCount"?: integer // 佔用建立額度的聊天機器人數量（模式不在方案白名單內的不計入） (非必填)
          "exemptChatbotsByMode"?: object // 不佔額度的聊天機器人數量，依使其不計入的模式分組 (非必填)
          "canCreateChatbot"?: boolean // 是否可以創建聊天機器人 (非必填)
          "createChatbotLimit"?: integer // 可建立的聊天機器人數量上限（-1 表示無上限、0 表示禁止建立） (非必填)
          "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,
          "countableChatbotsCount": 1,
          "exemptChatbotsByMode": {},
          "canCreateChatbot": false,
          "createChatbotLimit": 1,
          "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 助理給角色 <a href="#organizations-groups-group-chatbots-bulk-create-create" id="organizations-groups-group-chatbots-bulk-create-create"></a>

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  |                                                |
| `search`         | ❌  | 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&search=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&search=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&search=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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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&search=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 // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots.
        "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答（含組織自建的 AI Gateway 模型）；建立時只有組織在 AI助理預設值設了預設模型才可省略
        "llm":  // 綁定模型的 id、name 與退役資訊，直接讀取 FK，即使該模型已被組織停用仍會回傳
        {
          "id": string (uuid)
          "name": string
          "retiresAt": string (date) // 供應商退役日；到期後每日排程會把助理換到 replacement 並停用此模型。null 表示未排定退役
          "replacement":  // 退役後接手的模型（id 與 name）；null 表示未指定，到期時不會自動搬移
          {
            "id": string (uuid)
            "name": string
          }
        }
        "organizationEnforcedSettings": [ // 組織 AI助理預設值對這個助理強制的項目代碼（與 AI助理預設值 API 的 key 相同）；這些欄位讀回的就是強制值，更新時帶不同的值會被拒絕（唯讀；官方內建 Agent 與 MaiGPT 為空）
          string
        ]
        "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
        "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
        "instructions"?: string // Role instructions describing the chatbot's role and behavior. (非必填)
        "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "updatedAt": string (timestamp)
        "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
        "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `agent` - Agent (非必填)
        {
        }
        "template"?: string // Template used by Template and Hybrid modes. (非必填)
        "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (非必填)
        "totalWordsCount"?: integer (int64) // Accumulated total word count used. (非必填)
        "outputMode"?:  // 輸出模式：文字或結構化輸出；未帶時，請求帶非空 rawOutputFormat 視為結構化輸出，否則沿用原值（新建為文字）

* `text` - 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
            "source": string
            "isGlobal": boolean
          }
        ]
        "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (非必填)
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - Normal
* `canvas` - Canvas
* `team` - Team (非必填)
        {
        }
        "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
        "defaultLabelRelations"?: object // 助理層級的預設知識庫標籤過濾條件，格式同 query_metadata.label_relations；null 表示不過濾。僅在呼叫端未帶 query_metadata 時作為最低優先序兜底套用。 (非必填)
        "useFullRetrievalRange"?: boolean // 啟用後忽略 LLM 的 top_k 截斷，回傳完整 reranker 結果 (非必填)
        "searchKnowledgeBaseFirst"?: boolean // Agent 回覆模式：每則回覆先用使用者原句查一次知識庫，模型從查到的結果開始回答（仍可再查或用其他工具）。平台對該組織開放此選項時才生效（見組織的 can_use_search_knowledge_base_first） (非必填)
        "enableEvaluation"?: boolean // 非必填
        "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (非必填)
        "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (非必填)
        "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (非必填)
        "browserToolMaxSteps"?: integer // Most browser actions one reply of this assistant may take (1-100); null follows default_browser_tool_max_steps. Leaving it out of an update keeps the stored value. (非必填)
        "enableCloudDesktop"?: boolean // Let the assistant operate a cloud desktop with the computer tool in its test chat. It is offered only when the site-wide cloud desktop scope includes this organization. (非必填)
        "cloudDesktopAllowedDomains"?: [ // Domains the cloud desktop may reach, one per item; empty means no restriction (S19) (非必填)
          string
        ]
        "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (非必填)
        "enableClaudeStreamRetry"?: boolean // When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial output already rendered. Each retry incurs a second billing for the same prompt. (非必填)
        "enableStreamStallRetry"?: boolean // When an OpenAI, Azure, OpenAI-compatible or Vertex streaming call stalls (no first token, or a silence between tokens), abort it and re-issue the call once in non-streaming mode. Bedrock calls follow "Enable Claude stream retry" instead. Each retry incurs a second billing for the same prompt. (非必填)
        "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
        "voiceConfig"?: { // 非必填
        {
          "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (非必填)
          "voiceAgentType"?: string (uuid) // Voice agent mode type. (非必填)
          "sttProvider"?: string (uuid) // Speech-to-Text service provider. (非必填)
          "sttConfig"?: object // STT configuration parameters (JSON). (非必填)
          "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (非必填)
          "ttsConfig"?: object // TTS configuration parameters (JSON). (非必填)
          "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (非必填)
          "realtimeConfig"?: object // Realtime configuration parameters (JSON). (非必填)
          "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (非必填)
          "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (非必填)
          "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (非必填)
        }
        }
        "thinkingConfig"?: object // 思考等級：null（模型預設）或 {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (非必填)
        "enableToolSearching"?: boolean // 舊欄位，請改用 tool_loading_mode。寫入 true 等同 tool_loading_mode=search、false 等同 all；兩者都帶時以 tool_loading_mode 為準。讀取時回傳「工具載入方式不是全部載入」。 (非必填)
        "toolLoadingMode"?:  // 工具載入方式：auto（自動，依當輪可用工具量與模型決定）、all（全部載入）、search（動態搜尋）。新建助理預設 auto；尚未設定過的既有助理回傳依舊開關換算的值（開→search、關→all）。

* `auto` - Auto
* `all` - Load all
* `search` - Dynamic search (非必填)
        {
        }
        "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (非必填)
        "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (非必填)
        "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (非必填)
        "systemErrorMessage"?: string // Custom user-facing message shown instead of the general system error message when a reply fails (max 500 chars). Surrounding whitespace is dropped; empty uses the system default. (非必填)
        "requireTextWithFlexCards"?: boolean // When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a second billing for the same prompt. (非必填)
        "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
        "enableSizeBasedToolResultTruncation"?: boolean // When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversation search results keep their 100-character cut either way. Reduces memory bloat from large tool outputs (code interpreter bash stdout, web search results, etc.). (非必填)
        "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (非必填)
        "enableMemberMemoryWrite"?: boolean // When enabled, what organization members say about themselves in this agent's conversations is saved to their personal AI memory, which every agent with Use Member Memory enabled can refer to. Keep it off for agents members use to test customer-facing replies or to type on behalf of someone else. MaiGPT has it on. (非必填)
        "enableMemberMemoryInjection"?: boolean // When enabled, organization members' personal AI memory is given to this agent as background. When disabled, the agent answers members without it, as it answers customers. MaiGPT has it on. (非必填)
        "enableVectorMemory"?: boolean // When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat history window is used for multi-turn context. (非必填)
        "longTermMemoryTopK"?: integer // 長期記憶每次檢索取回的記憶節點數（向量檢索的 similarity_top_k），預設為 10，範圍 1–50 (非必填)
        "enableCrossConversationSearch"?: boolean // When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. (非必填)
        "crossConversationLookbackDays"?: integer // How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable_cross_conversation_search is True. (非必填)
        "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (非必填)
        "gatewayFallbackGroup"?: string (uuid) // 非必填
        "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (非必填)
        "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (非必填)
        "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (非必填)
        "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (非必填)
        "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (非必填)
        "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (非必填)
        "isLocked": boolean // Locked instance: config follows the official version; only the dedicated KB can be modified
        "sourceBuildInAgent": string (uuid) // Points to the official Build-in Agent blueprint when instantiated by a rental
        "canUpdate": boolean // Return whether the current user can update this resource.
        "canDelete": boolean // Return whether the current user can delete this resource.
        "team": 
        {
          "id": string (uuid)
          "name": string
        }
        "webChatIsActive"?: boolean // Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. (非必填)
        "apiIsActive"?: boolean // Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. The backstage (admin) channel always starts active and cannot be set here. (非必填)
        "fileWorkspaceMode"?:  // File workspace mode in Work internal conversations: none, bound or user_mount.

* `none` - None
* `bound` - Bound workspace
* `user_mount` - User mount (非必填)
        {
        }
        "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (非必填)
        "fileWorkspaceStatus": object // Read-only. {"folder": {"id", "name"} | null, "state": "ok" | "missing" | "builder_lost_edit" | null}
        "fileWorkspaceAvailable": boolean // Read-only. Whether the organization has the file library and this agent can configure a file workspace.
      }
      "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": "回應字串",
        "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
        "llm": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "retiresAt": "回應字串",
          "replacement": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "回應字串"
          }
        },
        "organizationEnforcedSettings": [
          "回應字串"
        ],
        "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",
        "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": "回應字串",
            "source": "回應字串",
            "isGlobal": false
          }
        ],
        "connectors": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "回應字串"
          }
        ],
        "agentMode": {},
        "numberOfRetrievedChunks": 456,
        "defaultLabelRelations": null,
        "useFullRetrievalRange": false,
        "searchKnowledgeBaseFirst": false,
        "enableEvaluation": false,
        "enableInlineCitations": false,
        "enableCodeInterpreter": false,
        "enableBrowserTool": false,
        "browserToolMaxSteps": 456,
        "enableCloudDesktop": false,
        "cloudDesktopAllowedDomains": [
          "回應字串"
        ],
        "enableImageSearch": false,
        "enableClaudeStreamRetry": false,
        "enableStreamStallRetry": false,
        "customMaxLlmOutputTokens": 456,
        "voiceConfig": {
          "enabled": false,
          "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,
          "realtimeInstructions": "回應字串",
          "turnHandling": null,
          "enableVoiceReply": false
        },
        "thinkingConfig": null,
        "enableToolSearching": false,
        "toolLoadingMode": {},
        "maxAgentIterations": 456,
        "agentTimeoutSeconds": 456,
        "agentTimeoutMessage": "回應字串",
        "systemErrorMessage": "回應字串",
        "requireTextWithFlexCards": false,
        "isMultimodalLlm": false,
        "enableSizeBasedToolResultTruncation": false,
        "toolResultMaxChars": 456,
        "enableMemberMemoryWrite": false,
        "enableMemberMemoryInjection": false,
        "enableVectorMemory": false,
        "longTermMemoryTopK": 456,
        "enableCrossConversationSearch": false,
        "crossConversationLookbackDays": 456,
        "useGatewayFallback": false,
        "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000",
        "enableSearchMessagesTool": false,
        "enableGetMessageContextTool": false,
        "enableReadAttachmentFullTextTool": false,
        "enableParseAttachmentContentTool": false,
        "enableListAvailableParsersTool": false,
        "enableGetDownloadLinkTool": false,
        "isLocked": false,
        "sourceBuildInAgent": "550e8400-e29b-41d4-a716-446655440000",
        "canUpdate": false,
        "canDelete": false,
        "team": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        },
        "webChatIsActive": false,
        "apiIsActive": false,
        "fileWorkspaceMode": {},
        "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000",
        "fileWorkspaceStatus": {
          "name": "example.pdf",
          "content": "base64encoded_content",
          "contentType": "application/pdf"
        },
        "fileWorkspaceAvailable": false
      },
      "canRead": false,
      "canUpdate": false,
      "canDelete": false,
      "createdAt": "回應字串"
    }
  ]
}
```

***

### 批量分配收件匣給角色 <a href="#organizations-groups-group-inboxes-bulk-create-create" id="organizations-groups-group-inboxes-bulk-create-create"></a>

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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 |

***

### 批量分配知識庫給角色 <a href="#organizations-groups-group-knowledge-bases-bulk-create-create" id="organizations-groups-group-knowledge-bases-bulk-create-create"></a>

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  |                                                |
| `search`         | ❌  | 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&search=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&search=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&search=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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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&search=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": 
        {
          "id": string (uuid)
          "name": string
        }
        "organization"?: string (uuid) // 非必填
        "embeddingModel": string (uuid)
        "rerankerModel": string (uuid)
        "name": string
        "description"?: string // 非必填
        "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
        "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
* `synxdb` - SynxDB (非必填)
        {
        }
        "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. (非必填)
        "synxdbUser"?: string // SynxDB database username. (非必填)
        "synxdbPassword"?: string // SynxDB 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
        "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": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        },
        "organization": "550e8400-e29b-41d4-a716-446655440000",
        "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
        "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "description": "回應字串",
        "numberOfRetrievedChunks": 456,
        "enableHyde": false,
        "similarityCutoff": 456,
        "enableRerank": false,
        "enableRrf": false,
        "vectorDatabaseType": {},
        "vectorDatabaseUrl": "回應字串",
        "vectorDatabaseApiKey": "回應字串",
        "opensearchUsername": "回應字串",
        "opensearchPassword": "回應字串",
        "oracleUser": "回應字串",
        "oraclePassword": "回應字串",
        "synxdbUser": "回應字串",
        "synxdbPassword": "回應字串",
        "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,
        "canUpdate": false,
        "canDelete": false,
        "createdAt": "回應字串",
        "updatedAt": "回應字串"
      },
      "canRead": false,
      "canUpdate": false,
      "canDelete": false,
      "createdAt": "回應字串"
    }
  ]
}
```

***

### 批量分配資料庫給角色 <a href="#organizations-groups-group-databases-bulk-create-create" id="organizations-groups-group-databases-bulk-create-create"></a>

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  |                                                |
| `search`         | ❌  | 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&search=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&search=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&search=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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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&search=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, SynxDB, or MaiAgent

* `postgresql` - PostgreSQL
* `mysql` - MySQL
* `maiagent` - MaiAgent
* `oracle` - Oracle
* `mssql` - MSSQL
* `synxdb` - SynxDB
        {
        }
        "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
            "sheetName": string // Name of the source worksheet/sheet this table was created from. Empty for tables created before this field was added.
            "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": {},
        "includeTables": null,
        "isActive": false,
        "status": {},
        "deletedAt": "回應字串",
        "tables": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "tableName": "回應字串",
            "sheetName": "回應字串",
            "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": "回應字串"
    }
  ]
}
```

***

### 列出權限清單 <a href="#permissions-list" id="permissions-list"></a>

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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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": "回應範例描述"
      }
    ]
  }
]
```

***

### 取得角色列表 <a href="#organizations-groups-list" id="organizations-groups-list"></a>

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  |                                                                                                                                                                                                                              |
| `search`         | ❌  | string  |                                                                                                                                                                                                                              |
| `type`           | ❌  | string  | \`owner\`: Owner ; \`default\`: Default Role ; \`custom\`: Custom Role ; \`position\`: Position ; \`department\`: Department List ; \`all\_members\`: All Members List ; \`list\`: Custom Group ; \`personal\`: Personal ... |

#### 程式碼範例

{% 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&search=example&type=all_members" \
  -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&search=example&type=all_members", 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&search=example&type=all_members"
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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/organizations/550e8400-e29b-41d4-a716-446655440000/groups/?page=1&pageSize=1&query=example&search=example&type=all_members", [
        '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": [
        object
      ]
      "membersPreview": [
        string
      ]
      "membersCount": integer // 返回剩餘成員數量（扣除列表顯示的 3 人後），用於前端 +N badge 顯示

與資源 count 不同：
- members_count: 返回 total - 3（用於 +N badge），None 表示總數 <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: 返回總數量
      "chatbotsCount": integer
      "chatbotsPreview": [
        string
      ]
      "knowledgeBasesCount": integer
      "knowledgeBasesPreview": [
        string
      ]
      "inboxesCount": integer
      "inboxesPreview": [
        string
      ]
      "databasesCount": integer
      "databasesPreview": [
        string
      ]
      "canCreateChatbot"?: boolean // 非必填
      "canCreateKnowledgeBase"?: boolean // 非必填
      "canCreateInbox"?: boolean // 非必填
      "canCreateDatabase"?: boolean // 非必填
      "canCreateTool"?: boolean // 非必填
      "canCreateAgentUiTool"?: boolean // 非必填
      "canCreateSkill"?: boolean // 非必填
      "canCreateTeam"?: boolean // Whether members of this role may create Agent Teams; the Team permission is still required. (非必填)
      "canCreatePersonalSkill"?: boolean // Whether members of this role may create personal skills (skills only they can see and use). A member in several roles may if any of them allows it. Turning it off keeps existing personal skills but no new ones can be created. (非必填)
      "canCreateVoiceAgent"?: boolean // Whether members of this role may create voice agents; the Voice Agent permission is still required. (非必填)
      "maigptCanCodeInterpreter"?: boolean // Whether members of this role may use the code interpreter built-in tool in MaiGPT. (非必填)
      "maigptCanRag"?: boolean // Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT. (非必填)
      "maigptCanDeepResearch"?: boolean // Whether members of this role may use Deep Research in MaiGPT. Deep Research reaches the public internet through its own built-in search, so a role that revokes the official web-search tools needs this switch too. (非必填)
      "maigptCanBrowserTool"?: boolean // Whether members of this role may use the browser built-in tool in MaiGPT. (非必填)
      "maigptCanCloudDesktop"?: boolean // Whether members of this role may use the cloud desktop in MaiGPT. (非必填)
      "maigptCanVoiceInput"?: boolean // Whether members of this role may use voice input in MaiGPT, billed by the seconds recorded. (非必填)
      "maigptAllLlms"?: boolean // Whether members of this role may use every organization-available LLM in MaiGPT. Off = only the bound LLMs; an empty binding then means none. (非必填)
      "maigptAllTools"?: boolean // Whether members of this role may call every official (global) tool in MaiGPT. Off = only the bound tools; an empty binding then means none. (非必填)
      "maigptAllConnectors"?: boolean // Whether members of this role may call every official (global) MCP connector in MaiGPT. Off = only the bound connectors; an empty binding then means none. (非必填)
      "maigptAllSkills"?: boolean // Whether members of this role may use every official (global) skill in MaiGPT. Off = only the bound skills; an empty binding then means none. (非必填)
      "usageStatisticsScope"?:  // What this role's usage statistics permission shows: the whole organization, or only the AI assistants granted to the member's roles. A member with any organization-wide granting role sees the whole organization.

* `organization` - Organization-wide
* `accessible_chatbots` - Authorized AI assistants only (非必填)
      {
      }
      "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,
      "canCreateTool": false,
      "canCreateAgentUiTool": false,
      "canCreateSkill": false,
      "canCreateTeam": false,
      "canCreatePersonalSkill": false,
      "canCreateVoiceAgent": false,
      "maigptCanCodeInterpreter": false,
      "maigptCanRag": false,
      "maigptCanDeepResearch": false,
      "maigptCanBrowserTool": false,
      "maigptCanCloudDesktop": false,
      "maigptCanVoiceInput": false,
      "maigptAllLlms": false,
      "maigptAllTools": false,
      "maigptAllConnectors": false,
      "maigptAllSkills": false,
      "usageStatisticsScope": {},
      "createdAt": "回應字串"
    }
  ]
}
```

***

### 取得角色的詳情 <a href="#organizations-groups-retrieve" id="organizations-groups-retrieve"></a>

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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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": [
    object
  ]
  "membersPreview": [
    string
  ]
  "membersCount": integer // 返回剩餘成員數量（扣除列表顯示的 3 人後），用於前端 +N badge 顯示

與資源 count 不同：
- members_count: 返回 total - 3（用於 +N badge），None 表示總數 <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: 返回總數量
  "chatbotsCount": integer
  "chatbotsPreview": [
    string
  ]
  "knowledgeBasesCount": integer
  "knowledgeBasesPreview": [
    string
  ]
  "inboxesCount": integer
  "inboxesPreview": [
    string
  ]
  "databasesCount": integer
  "databasesPreview": [
    string
  ]
  "canCreateChatbot"?: boolean // 非必填
  "canCreateKnowledgeBase"?: boolean // 非必填
  "canCreateInbox"?: boolean // 非必填
  "canCreateDatabase"?: boolean // 非必填
  "canCreateTool"?: boolean // 非必填
  "canCreateAgentUiTool"?: boolean // 非必填
  "canCreateSkill"?: boolean // 非必填
  "canCreateTeam"?: boolean // Whether members of this role may create Agent Teams; the Team permission is still required. (非必填)
  "canCreatePersonalSkill"?: boolean // Whether members of this role may create personal skills (skills only they can see and use). A member in several roles may if any of them allows it. Turning it off keeps existing personal skills but no new ones can be created. (非必填)
  "canCreateVoiceAgent"?: boolean // Whether members of this role may create voice agents; the Voice Agent permission is still required. (非必填)
  "maigptCanCodeInterpreter"?: boolean // Whether members of this role may use the code interpreter built-in tool in MaiGPT. (非必填)
  "maigptCanRag"?: boolean // Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT. (非必填)
  "maigptCanDeepResearch"?: boolean // Whether members of this role may use Deep Research in MaiGPT. Deep Research reaches the public internet through its own built-in search, so a role that revokes the official web-search tools needs this switch too. (非必填)
  "maigptCanBrowserTool"?: boolean // Whether members of this role may use the browser built-in tool in MaiGPT. (非必填)
  "maigptCanCloudDesktop"?: boolean // Whether members of this role may use the cloud desktop in MaiGPT. (非必填)
  "maigptCanVoiceInput"?: boolean // Whether members of this role may use voice input in MaiGPT, billed by the seconds recorded. (非必填)
  "maigptAllLlms"?: boolean // Whether members of this role may use every organization-available LLM in MaiGPT. Off = only the bound LLMs; an empty binding then means none. (非必填)
  "maigptAllTools"?: boolean // Whether members of this role may call every official (global) tool in MaiGPT. Off = only the bound tools; an empty binding then means none. (非必填)
  "maigptAllConnectors"?: boolean // Whether members of this role may call every official (global) MCP connector in MaiGPT. Off = only the bound connectors; an empty binding then means none. (非必填)
  "maigptAllSkills"?: boolean // Whether members of this role may use every official (global) skill in MaiGPT. Off = only the bound skills; an empty binding then means none. (非必填)
  "usageStatisticsScope"?:  // What this role's usage statistics permission shows: the whole organization, or only the AI assistants granted to the member's roles. A member with any organization-wide granting role sees the whole organization.

* `organization` - Organization-wide
* `accessible_chatbots` - Authorized AI assistants only (非必填)
  {
  }
  "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,
  "canCreateTool": false,
  "canCreateAgentUiTool": false,
  "canCreateSkill": false,
  "canCreateTeam": false,
  "canCreatePersonalSkill": false,
  "canCreateVoiceAgent": false,
  "maigptCanCodeInterpreter": false,
  "maigptCanRag": false,
  "maigptCanDeepResearch": false,
  "maigptCanBrowserTool": false,
  "maigptCanCloudDesktop": false,
  "maigptCanVoiceInput": false,
  "maigptAllLlms": false,
  "maigptAllTools": false,
  "maigptAllConnectors": false,
  "maigptAllSkills": false,
  "usageStatisticsScope": {},
  "createdAt": "回應字串"
}
```

***

### 取得角色成員列表 <a href="#organizations-groups-group-members-list" id="organizations-groups-group-members-list"></a>

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  |                                                |
| `search`         | ❌  | 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&search=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&search=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&search=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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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&search=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
        "displayName": string // Name set by the organization owner for this organization only; empty string when not set (``name`` then falls back to the account name).
        "accountName": string // Account name of the member (shared across organizations); shown when display name is cleared.
        "isScimManaged": boolean // True when the member is provisioned by SCIM; the identity provider manages the member and the organization name cannot be changed manually.
        "email": string
        "isActive": boolean
        "isOwner": boolean // 檢查成員是否為組織擁有者（透過 OWNER Group）

使用快取避免同一 request 內的重複查詢
快取生命週期：在 member instance 存在期間有效

優先使用 annotation 的結果（如果有的話）避免重複查詢
        "permissions": [ // Compute the permission tree once per (organization, custom-group set) per request.

The tree depends only on the member's organization (default groups, feature
flags, plan whitelist), the member's custom groups, and the global ``Config``,
so members sharing a group set get the same result. A large role's
``pagination=false`` listing otherwise recomputes it per row — one Redis
``Config`` fetch plus the permission walk each time (issue #8436; the largest
prod role has 3,837 members and a single group set). The memo lives in the
serializer context, so it never outlives the request. Rows without the eager
loaded ``_custom_groups_cache`` (single-object paths) keep computing directly.

A 2.0 row's tree follows from being an owner or else from its effective permission
values alone, so 2.0 rows are keyed by (organization, owner, values) in a memo of
their own, after the viewer check.
          object
        ]
        "groups": [
          object
        ]
        "creditQuotaRequired"?: boolean // When True, member must have an active quota to consume credits (非必填)
        "activeQuota": object // Return the most recent quota summary (active first), via prefetch to avoid N+1.
        "metadata": object // Organization-scoped member attributes, injected into LLM system prompt
        "availabilityStatus":  // Self-declared availability for auto-assignment. Paused members are skipped by the dispatch engine but can still be manually assigned or claim conversations. Not touched by SCIM provisioning.

* `available` - Available
* `paused` - Paused
        {
        }
        "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": "回應字串",
        "displayName": "回應字串",
        "accountName": "回應字串",
        "isScimManaged": false,
        "email": "回應字串",
        "isActive": false,
        "isOwner": false,
        "permissions": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "回應範例名稱",
            "description": "回應範例描述"
          }
        ],
        "groups": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "回應範例名稱",
            "description": "回應範例描述"
          }
        ],
        "creditQuotaRequired": false,
        "activeQuota": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應範例名稱",
          "description": "回應範例描述"
        },
        "metadata": null,
        "availabilityStatus": {},
        "createdAt": "回應字串"
      },
      "createdAt": "回應字串"
    }
  ]
}
```

***

### 查看特定角色成員 <a href="#organizations-groups-group-members-retrieve" id="organizations-groups-group-members-retrieve"></a>

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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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
    "displayName": string // Name set by the organization owner for this organization only; empty string when not set (``name`` then falls back to the account name).
    "accountName": string // Account name of the member (shared across organizations); shown when display name is cleared.
    "isScimManaged": boolean // True when the member is provisioned by SCIM; the identity provider manages the member and the organization name cannot be changed manually.
    "email": string
    "isActive": boolean
    "isOwner": boolean // 檢查成員是否為組織擁有者（透過 OWNER Group）

使用快取避免同一 request 內的重複查詢
快取生命週期：在 member instance 存在期間有效

優先使用 annotation 的結果（如果有的話）避免重複查詢
    "permissions": [ // Compute the permission tree once per (organization, custom-group set) per request.

The tree depends only on the member's organization (default groups, feature
flags, plan whitelist), the member's custom groups, and the global ``Config``,
so members sharing a group set get the same result. A large role's
``pagination=false`` listing otherwise recomputes it per row — one Redis
``Config`` fetch plus the permission walk each time (issue #8436; the largest
prod role has 3,837 members and a single group set). The memo lives in the
serializer context, so it never outlives the request. Rows without the eager
loaded ``_custom_groups_cache`` (single-object paths) keep computing directly.

A 2.0 row's tree follows from being an owner or else from its effective permission
values alone, so 2.0 rows are keyed by (organization, owner, values) in a memo of
their own, after the viewer check.
      object
    ]
    "groups": [
      object
    ]
    "creditQuotaRequired"?: boolean // When True, member must have an active quota to consume credits (非必填)
    "activeQuota": object // Return the most recent quota summary (active first), via prefetch to avoid N+1.
    "metadata": object // Organization-scoped member attributes, injected into LLM system prompt
    "availabilityStatus":  // Self-declared availability for auto-assignment. Paused members are skipped by the dispatch engine but can still be manually assigned or claim conversations. Not touched by SCIM provisioning.

* `available` - Available
* `paused` - Paused
    {
    }
    "createdAt": string (timestamp)
  }
  }
  "createdAt": string (timestamp)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "member": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "displayName": "回應字串",
    "accountName": "回應字串",
    "isScimManaged": false,
    "email": "回應字串",
    "isActive": false,
    "isOwner": false,
    "permissions": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應範例名稱",
        "description": "回應範例描述"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應範例名稱",
        "description": "回應範例描述"
      }
    ],
    "creditQuotaRequired": false,
    "activeQuota": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應範例名稱",
      "description": "回應範例描述"
    },
    "metadata": null,
    "availabilityStatus": {},
    "createdAt": "回應字串"
  },
  "createdAt": "回應字串"
}
```

***

### 取得角色的 AI 助理列表 <a href="#organizations-groups-group-chatbots-list" id="organizations-groups-group-chatbots-list"></a>

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  |                                                |
| `search`         | ❌  | 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&search=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&search=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&search=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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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&search=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 // Chatbot name. In Agent mode it carries semantic meaning; in other modes it only distinguishes chatbots.
        "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答（含組織自建的 AI Gateway 模型）；建立時只有組織在 AI助理預設值設了預設模型才可省略
        "llm":  // 綁定模型的 id、name 與退役資訊，直接讀取 FK，即使該模型已被組織停用仍會回傳
        {
          "id": string (uuid)
          "name": string
          "retiresAt": string (date) // 供應商退役日；到期後每日排程會把助理換到 replacement 並停用此模型。null 表示未排定退役
          "replacement":  // 退役後接手的模型（id 與 name）；null 表示未指定，到期時不會自動搬移
          {
            "id": string (uuid)
            "name": string
          }
        }
        "organizationEnforcedSettings": [ // 組織 AI助理預設值對這個助理強制的項目代碼（與 AI助理預設值 API 的 key 相同）；這些欄位讀回的就是強制值，更新時帶不同的值會被拒絕（唯讀；官方內建 Agent 與 MaiGPT 為空）
          string
        ]
        "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
        "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
        "instructions"?: string // Role instructions describing the chatbot's role and behavior. (非必填)
        "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "updatedAt": string (timestamp)
        "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
        "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `agent` - Agent (非必填)
        {
        }
        "template"?: string // Template used by Template and Hybrid modes. (非必填)
        "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (非必填)
        "totalWordsCount"?: integer (int64) // Accumulated total word count used. (非必填)
        "outputMode"?:  // 輸出模式：文字或結構化輸出；未帶時，請求帶非空 rawOutputFormat 視為結構化輸出，否則沿用原值（新建為文字）

* `text` - 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
            "source": string
            "isGlobal": boolean
          }
        ]
        "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (非必填)
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - Normal
* `canvas` - Canvas
* `team` - Team (非必填)
        {
        }
        "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
        "defaultLabelRelations"?: object // 助理層級的預設知識庫標籤過濾條件，格式同 query_metadata.label_relations；null 表示不過濾。僅在呼叫端未帶 query_metadata 時作為最低優先序兜底套用。 (非必填)
        "useFullRetrievalRange"?: boolean // 啟用後忽略 LLM 的 top_k 截斷，回傳完整 reranker 結果 (非必填)
        "searchKnowledgeBaseFirst"?: boolean // Agent 回覆模式：每則回覆先用使用者原句查一次知識庫，模型從查到的結果開始回答（仍可再查或用其他工具）。平台對該組織開放此選項時才生效（見組織的 can_use_search_knowledge_base_first） (非必填)
        "enableEvaluation"?: boolean // 非必填
        "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (非必填)
        "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (非必填)
        "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (非必填)
        "browserToolMaxSteps"?: integer // Most browser actions one reply of this assistant may take (1-100); null follows default_browser_tool_max_steps. Leaving it out of an update keeps the stored value. (非必填)
        "enableCloudDesktop"?: boolean // Let the assistant operate a cloud desktop with the computer tool in its test chat. It is offered only when the site-wide cloud desktop scope includes this organization. (非必填)
        "cloudDesktopAllowedDomains"?: [ // Domains the cloud desktop may reach, one per item; empty means no restriction (S19) (非必填)
          string
        ]
        "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (非必填)
        "enableClaudeStreamRetry"?: boolean // When a Claude streaming call stalls (first-chunk or mid-stream), abort and re-issue the call once in non-streaming mode. Mid-stream retries send a reset signal so the client discards any partial output already rendered. Each retry incurs a second billing for the same prompt. (非必填)
        "enableStreamStallRetry"?: boolean // When an OpenAI, Azure, OpenAI-compatible or Vertex streaming call stalls (no first token, or a silence between tokens), abort it and re-issue the call once in non-streaming mode. Bedrock calls follow "Enable Claude stream retry" instead. Each retry incurs a second billing for the same prompt. (非必填)
        "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
        "voiceConfig"?: { // 非必填
        {
          "enabled"?: boolean // Whether this chatbot can be used as a voice agent. Checked by every conversation platform (WebChat, SIP phone, admin/marketplace voice test) instead of a per-platform toggle. (非必填)
          "voiceAgentType"?: string (uuid) // Voice agent mode type. (非必填)
          "sttProvider"?: string (uuid) // Speech-to-Text service provider. (非必填)
          "sttConfig"?: object // STT configuration parameters (JSON). (非必填)
          "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (非必填)
          "ttsConfig"?: object // TTS configuration parameters (JSON). (非必填)
          "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (非必填)
          "realtimeConfig"?: object // Realtime configuration parameters (JSON). (非必填)
          "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (非必填)
          "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (非必填)
          "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (非必填)
        }
        }
        "thinkingConfig"?: object // 思考等級：null（模型預設）或 {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (非必填)
        "enableToolSearching"?: boolean // 舊欄位，請改用 tool_loading_mode。寫入 true 等同 tool_loading_mode=search、false 等同 all；兩者都帶時以 tool_loading_mode 為準。讀取時回傳「工具載入方式不是全部載入」。 (非必填)
        "toolLoadingMode"?:  // 工具載入方式：auto（自動，依當輪可用工具量與模型決定）、all（全部載入）、search（動態搜尋）。新建助理預設 auto；尚未設定過的既有助理回傳依舊開關換算的值（開→search、關→all）。

* `auto` - Auto
* `all` - Load all
* `search` - Dynamic search (非必填)
        {
        }
        "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (非必填)
        "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (非必填)
        "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (非必填)
        "systemErrorMessage"?: string // Custom user-facing message shown instead of the general system error message when a reply fails (max 500 chars). Surrounding whitespace is dropped; empty uses the system default. (非必填)
        "requireTextWithFlexCards"?: boolean // When enabled, a turn that would end with only Flex Message cards and no text for the user is re-issued to the LLM once, asking it to write the text first and then send the card. Each retry incurs a second billing for the same prompt. (非必填)
        "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
        "enableSizeBasedToolResultTruncation"?: boolean // When enabled, tool results exceeding the character threshold are kept as head+tail (with the identifiers found in the cut part) when written to conversation history; knowledge base, SQL and conversation search results keep their 100-character cut either way. Reduces memory bloat from large tool outputs (code interpreter bash stdout, web search results, etc.). (非必填)
        "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (非必填)
        "enableMemberMemoryWrite"?: boolean // When enabled, what organization members say about themselves in this agent's conversations is saved to their personal AI memory, which every agent with Use Member Memory enabled can refer to. Keep it off for agents members use to test customer-facing replies or to type on behalf of someone else. MaiGPT has it on. (非必填)
        "enableMemberMemoryInjection"?: boolean // When enabled, organization members' personal AI memory is given to this agent as background. When disabled, the agent answers members without it, as it answers customers. MaiGPT has it on. (非必填)
        "enableVectorMemory"?: boolean // When enabled, archived messages are vectorized and processed by fact extraction for semantic retrieval (existing behavior). When disabled, archived messages are discarded and only the active chat history window is used for multi-turn context. (非必填)
        "longTermMemoryTopK"?: integer // 長期記憶每次檢索取回的記憶節點數（向量檢索的 similarity_top_k），預設為 10，範圍 1–50 (非必填)
        "enableCrossConversationSearch"?: boolean // When enabled, the conversation history tools also reach this contact's other conversations in the same inbox, within the lookback window. When disabled, they only reach the current conversation. (非必填)
        "crossConversationLookbackDays"?: integer // How far back cross-conversation search may reach, measured from each conversation's last message (1-365 days). Leave empty to fall back to 90 days. Only effective when enable_cross_conversation_search is True. (非必填)
        "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (非必填)
        "gatewayFallbackGroup"?: string (uuid) // 非必填
        "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (非必填)
        "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (非必填)
        "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (非必填)
        "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (非必填)
        "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (非必填)
        "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (非必填)
        "isLocked": boolean // Locked instance: config follows the official version; only the dedicated KB can be modified
        "sourceBuildInAgent": string (uuid) // Points to the official Build-in Agent blueprint when instantiated by a rental
        "canUpdate": boolean // Return whether the current user can update this resource.
        "canDelete": boolean // Return whether the current user can delete this resource.
        "team": 
        {
          "id": string (uuid)
          "name": string
        }
        "webChatIsActive"?: boolean // Optional, create only. Whether the web widget channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. (非必填)
        "apiIsActive"?: boolean // Optional, create only. Whether the API channel starts active. Omitted or null: follows the organization's default for new chatbot channels (inactive unless a platform admin turned it on). Ignored on update; change an existing channel from its channel settings instead. The backstage (admin) channel always starts active and cannot be set here. (非必填)
        "fileWorkspaceMode"?:  // File workspace mode in Work internal conversations: none, bound or user_mount.

* `none` - None
* `bound` - Bound workspace
* `user_mount` - User mount (非必填)
        {
        }
        "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (非必填)
        "fileWorkspaceStatus": object // Read-only. {"folder": {"id", "name"} | null, "state": "ok" | "missing" | "builder_lost_edit" | null}
        "fileWorkspaceAvailable": boolean // Read-only. Whether the organization has the file library and this agent can configure a file workspace.
      }
      "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": "回應字串",
        "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
        "llm": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "retiresAt": "回應字串",
          "replacement": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "回應字串"
          }
        },
        "organizationEnforcedSettings": [
          "回應字串"
        ],
        "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",
        "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": "回應字串",
            "source": "回應字串",
            "isGlobal": false
          }
        ],
        "connectors": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "回應字串"
          }
        ],
        "agentMode": {},
        "numberOfRetrievedChunks": 456,
        "defaultLabelRelations": null,
        "useFullRetrievalRange": false,
        "searchKnowledgeBaseFirst": false,
        "enableEvaluation": false,
        "enableInlineCitations": false,
        "enableCodeInterpreter": false,
        "enableBrowserTool": false,
        "browserToolMaxSteps": 456,
        "enableCloudDesktop": false,
        "cloudDesktopAllowedDomains": [
          "回應字串"
        ],
        "enableImageSearch": false,
        "enableClaudeStreamRetry": false,
        "enableStreamStallRetry": false,
        "customMaxLlmOutputTokens": 456,
        "voiceConfig": {
          "enabled": false,
          "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,
          "realtimeInstructions": "回應字串",
          "turnHandling": null,
          "enableVoiceReply": false
        },
        "thinkingConfig": null,
        "enableToolSearching": false,
        "toolLoadingMode": {},
        "maxAgentIterations": 456,
        "agentTimeoutSeconds": 456,
        "agentTimeoutMessage": "回應字串",
        "systemErrorMessage": "回應字串",
        "requireTextWithFlexCards": false,
        "isMultimodalLlm": false,
        "enableSizeBasedToolResultTruncation": false,
        "toolResultMaxChars": 456,
        "enableMemberMemoryWrite": false,
        "enableMemberMemoryInjection": false,
        "enableVectorMemory": false,
        "longTermMemoryTopK": 456,
        "enableCrossConversationSearch": false,
        "crossConversationLookbackDays": 456,
        "useGatewayFallback": false,
        "gatewayFallbackGroup": "550e8400-e29b-41d4-a716-446655440000",
        "enableSearchMessagesTool": false,
        "enableGetMessageContextTool": false,
        "enableReadAttachmentFullTextTool": false,
        "enableParseAttachmentContentTool": false,
        "enableListAvailableParsersTool": false,
        "enableGetDownloadLinkTool": false,
        "isLocked": false,
        "sourceBuildInAgent": "550e8400-e29b-41d4-a716-446655440000",
        "canUpdate": false,
        "canDelete": false,
        "team": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        },
        "webChatIsActive": false,
        "apiIsActive": false,
        "fileWorkspaceMode": {},
        "fileWorkspaceFolder": "550e8400-e29b-41d4-a716-446655440000",
        "fileWorkspaceStatus": {
          "name": "example.pdf",
          "content": "base64encoded_content",
          "contentType": "application/pdf"
        },
        "fileWorkspaceAvailable": false
      },
      "canRead": false,
      "canUpdate": false,
      "canDelete": false,
      "createdAt": "回應字串"
    }
  ]
}
```

***

### 取得角色的收件匣列表 <a href="#organizations-groups-group-inboxes-list" id="organizations-groups-group-inboxes-list"></a>

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 ; \`slack\`: Slack ; \`team\_plus\`: Team+ ; \`lin... |
| `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  |                                                                                                                                                                                                                                   |
| `search`         | ❌  | 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&search=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

```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&search=example", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

```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&search=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)
```

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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&search=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();
}
?>
```

#### 回應內容

**狀態碼: 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, slack, team_plus, line_works, viber) // * `line` - LINE
* `telegram` - Telegram
* `teams` - Teams
* `web` - Web
* `messenger` - Messenger
* `instagram` - Instagram
* `email` - Email
* `whatsapp` - WhatsApp
* `slack` - Slack
* `team_plus` - Team+
* `line_works` - LINE WORKS
* `viber` - Viber
        "name": string
        "unreadConversationsCount": integer
        "accessType": string
      }
      "canRead"?: boolean // 非必填
      "canUpdate"?: boolean // 非必填
      "canDelete"?: boolean // 非必填
      "canViewConversations"?: boolean // Whether group members can browse all conversations of this inbox in the conversations page. Independent from can_read, which controls using the inbox for chatting. (非必填)
      "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,
      "canViewConversations": false,
      "createdAt": "回應字串"
    }
  ]
}
```

***

### 取得角色的知識庫列表 <a href="#organizations-groups-group-knowledge-bases-list" id="organizations-groups-group-knowledge-bases-list"></a>

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  |                                                |
| `search`         | ❌  | 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&search=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&search=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&search=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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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&search=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": 
        {
          "id": string (uuid)
          "name": string
        }
        "organization"?: string (uuid) // 非必填
        "embeddingModel": string (uuid)
        "rerankerModel": string (uuid)
        "name": string
        "description"?: string // 非必填
        "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
        "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
* `synxdb` - SynxDB (非必填)
        {
        }
        "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. (非必填)
        "synxdbUser"?: string // SynxDB database username. (非必填)
        "synxdbPassword"?: string // SynxDB 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
        "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": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        },
        "organization": "550e8400-e29b-41d4-a716-446655440000",
        "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
        "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "description": "回應字串",
        "numberOfRetrievedChunks": 456,
        "enableHyde": false,
        "similarityCutoff": 456,
        "enableRerank": false,
        "enableRrf": false,
        "vectorDatabaseType": {},
        "vectorDatabaseUrl": "回應字串",
        "vectorDatabaseApiKey": "回應字串",
        "opensearchUsername": "回應字串",
        "opensearchPassword": "回應字串",
        "oracleUser": "回應字串",
        "oraclePassword": "回應字串",
        "synxdbUser": "回應字串",
        "synxdbPassword": "回應字串",
        "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,
        "canUpdate": false,
        "canDelete": false,
        "createdAt": "回應字串",
        "updatedAt": "回應字串"
      },
      "canRead": false,
      "canUpdate": false,
      "canDelete": false,
      "createdAt": "回應字串"
    }
  ]
}
```

***

### 取得角色的資料庫列表 <a href="#organizations-groups-group-databases-list" id="organizations-groups-group-databases-list"></a>

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  |                                                |
| `search`         | ❌  | 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&search=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&search=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&search=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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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&search=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, SynxDB, or MaiAgent

* `postgresql` - PostgreSQL
* `mysql` - MySQL
* `maiagent` - MaiAgent
* `oracle` - Oracle
* `mssql` - MSSQL
* `synxdb` - SynxDB
        {
        }
        "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
            "sheetName": string // Name of the source worksheet/sheet this table was created from. Empty for tables created before this field was added.
            "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": {},
        "includeTables": null,
        "isActive": false,
        "status": {},
        "deletedAt": "回應字串",
        "tables": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "tableName": "回應字串",
            "sheetName": "回應字串",
            "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": "回應字串"
    }
  ]
}
```

***

### 更新角色權限 <a href="#organizations-groups-update" id="organizations-groups-update"></a>

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        | 否  |                                                                                                                                                                                                             |
| canCreateTool            | boolean        | 否  |                                                                                                                                                                                                             |
| canCreateAgentUiTool     | boolean        | 否  |                                                                                                                                                                                                             |
| canCreateSkill           | boolean        | 否  |                                                                                                                                                                                                             |
| canCreateTeam            | boolean        | 否  | Whether members of this role may create Agent Teams; the Team permission is still required.                                                                                                                 |
| canCreatePersonalSkill   | boolean        | 否  | Whether members of this role may create personal skills (skills only they can see and use). A member in several roles may if any of them allows it. Turning it off keeps existing personal skills but no... |
| canCreateVoiceAgent      | boolean        | 否  | Whether members of this role may create voice agents; the Voice Agent permission is still required.                                                                                                         |
| maigptCanCodeInterpreter | boolean        | 否  | Whether members of this role may use the code interpreter built-in tool in MaiGPT.                                                                                                                          |
| maigptCanRag             | boolean        | 否  | Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT.                                                                                                                        |
| maigptCanDeepResearch    | boolean        | 否  | Whether members of this role may use Deep Research in MaiGPT. Deep Research reaches the public internet through its own built-in search, so a role that revokes the official web-search tools needs this... |
| maigptCanBrowserTool     | boolean        | 否  | Whether members of this role may use the browser built-in tool in MaiGPT.                                                                                                                                   |
| maigptCanCloudDesktop    | boolean        | 否  | Whether members of this role may use the cloud desktop in MaiGPT.                                                                                                                                           |
| maigptCanVoiceInput      | boolean        | 否  | Whether members of this role may use voice input in MaiGPT, billed by the seconds recorded.                                                                                                                 |
| maigptAllLlms            | boolean        | 否  | Whether members of this role may use every organization-available LLM in MaiGPT. Off = only the bound LLMs; an empty binding then means none.                                                               |
| maigptAllTools           | boolean        | 否  | Whether members of this role may call every official (global) tool in MaiGPT. Off = only the bound tools; an empty binding then means none.                                                                 |
| maigptAllConnectors      | boolean        | 否  | Whether members of this role may call every official (global) MCP connector in MaiGPT. Off = only the bound connectors; an empty binding then means none.                                                   |
| maigptAllSkills          | boolean        | 否  | Whether members of this role may use every official (global) skill in MaiGPT. Off = only the bound skills; an empty binding then means none.                                                                |
| usageStatisticsScope     | object         | 否  | What this role's usage statistics permission shows: the whole organization, or only the AI assistants granted to the member's roles. A member with any organization-wide granting role sees the whole or... |
| allowedLlms              | array\[string] | 否  |                                                                                                                                                                                                             |
| allowedTools             | array\[string] | 否  |                                                                                                                                                                                                             |
| allowedConnectors        | array\[string] | 否  |                                                                                                                                                                                                             |
| allowedSkills            | array\[string] | 否  |                                                                                                                                                                                                             |

**請求結構範例**

```typescript
{
  "name": string
  "organization"?: string (uuid) // 非必填
  "permissions": [
    string (uuid)
  ]
  "canCreateChatbot"?: boolean // 非必填
  "canCreateKnowledgeBase"?: boolean // 非必填
  "canCreateInbox"?: boolean // 非必填
  "canCreateDatabase"?: boolean // 非必填
  "canCreateTool"?: boolean // 非必填
  "canCreateAgentUiTool"?: boolean // 非必填
  "canCreateSkill"?: boolean // 非必填
  "canCreateTeam"?: boolean // Whether members of this role may create Agent Teams; the Team permission is still required. (非必填)
  "canCreatePersonalSkill"?: boolean // Whether members of this role may create personal skills (skills only they can see and use). A member in several roles may if any of them allows it. Turning it off keeps existing personal skills but no new ones can be created. (非必填)
  "canCreateVoiceAgent"?: boolean // Whether members of this role may create voice agents; the Voice Agent permission is still required. (非必填)
  "maigptCanCodeInterpreter"?: boolean // Whether members of this role may use the code interpreter built-in tool in MaiGPT. (非必填)
  "maigptCanRag"?: boolean // Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT. (非必填)
  "maigptCanDeepResearch"?: boolean // Whether members of this role may use Deep Research in MaiGPT. Deep Research reaches the public internet through its own built-in search, so a role that revokes the official web-search tools needs this switch too. (非必填)
  "maigptCanBrowserTool"?: boolean // Whether members of this role may use the browser built-in tool in MaiGPT. (非必填)
  "maigptCanCloudDesktop"?: boolean // Whether members of this role may use the cloud desktop in MaiGPT. (非必填)
  "maigptCanVoiceInput"?: boolean // Whether members of this role may use voice input in MaiGPT, billed by the seconds recorded. (非必填)
  "maigptAllLlms"?: boolean // Whether members of this role may use every organization-available LLM in MaiGPT. Off = only the bound LLMs; an empty binding then means none. (非必填)
  "maigptAllTools"?: boolean // Whether members of this role may call every official (global) tool in MaiGPT. Off = only the bound tools; an empty binding then means none. (非必填)
  "maigptAllConnectors"?: boolean // Whether members of this role may call every official (global) MCP connector in MaiGPT. Off = only the bound connectors; an empty binding then means none. (非必填)
  "maigptAllSkills"?: boolean // Whether members of this role may use every official (global) skill in MaiGPT. Off = only the bound skills; an empty binding then means none. (非必填)
  "usageStatisticsScope"?:  // What this role's usage statistics permission shows: the whole organization, or only the AI assistants granted to the member's roles. A member with any organization-wide granting role sees the whole organization.

* `organization` - Organization-wide
* `accessible_chatbots` - Authorized AI assistants only (非必填)
  {
  }
  "allowedLlms"?: [ // 非必填
    string (uuid)
  ]
  "allowedTools"?: [ // 非必填
    string (uuid)
  ]
  "allowedConnectors"?: [ // 非必填
    string (uuid)
  ]
  "allowedSkills"?: [ // 非必填
    string (uuid)
  ]
}
```

**請求範例值**

```json
{
  "name": "範例名稱",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "permissions": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "canCreateChatbot": true,
  "canCreateKnowledgeBase": true,
  "canCreateInbox": true,
  "canCreateDatabase": true,
  "canCreateTool": true,
  "canCreateAgentUiTool": true,
  "canCreateSkill": true,
  "canCreateTeam": true,
  "canCreatePersonalSkill": true,
  "canCreateVoiceAgent": true,
  "maigptCanCodeInterpreter": true,
  "maigptCanRag": true,
  "maigptCanDeepResearch": true,
  "maigptCanBrowserTool": true,
  "maigptCanCloudDesktop": true,
  "maigptCanVoiceInput": true,
  "maigptAllLlms": true,
  "maigptAllTools": true,
  "maigptAllConnectors": true,
  "maigptAllSkills": true,
  "usageStatisticsScope": {},
  "allowedLlms": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "allowedTools": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "allowedConnectors": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "allowedSkills": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}
```

#### 程式碼範例

{% 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,
    "canCreateTool": true,
    "canCreateAgentUiTool": true,
    "canCreateSkill": true,
    "canCreateTeam": true,
    "canCreatePersonalSkill": true,
    "canCreateVoiceAgent": true,
    "maigptCanCodeInterpreter": true,
    "maigptCanRag": true,
    "maigptCanDeepResearch": true,
    "maigptCanBrowserTool": true,
    "maigptCanCloudDesktop": true,
    "maigptCanVoiceInput": true,
    "maigptAllLlms": true,
    "maigptAllTools": true,
    "maigptAllConnectors": true,
    "maigptAllSkills": true,
    "usageStatisticsScope": {},
    "allowedLlms": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedTools": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedConnectors": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedSkills": [
      "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 = {
    "name": "範例名稱",
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "permissions": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "canCreateChatbot": true,
    "canCreateKnowledgeBase": true,
    "canCreateInbox": true,
    "canCreateDatabase": true,
    "canCreateTool": true,
    "canCreateAgentUiTool": true,
    "canCreateSkill": true,
    "canCreateTeam": true,
    "canCreatePersonalSkill": true,
    "canCreateVoiceAgent": true,
    "maigptCanCodeInterpreter": true,
    "maigptCanRag": true,
    "maigptCanDeepResearch": true,
    "maigptCanBrowserTool": true,
    "maigptCanCloudDesktop": true,
    "maigptCanVoiceInput": true,
    "maigptAllLlms": true,
    "maigptAllTools": true,
    "maigptAllConnectors": true,
    "maigptAllSkills": true,
    "usageStatisticsScope": {},
    "allowedLlms": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedTools": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedConnectors": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedSkills": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  };

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,
    "canCreateTool": True,
    "canCreateAgentUiTool": True,
    "canCreateSkill": True,
    "canCreateTeam": True,
    "canCreatePersonalSkill": True,
    "canCreateVoiceAgent": True,
    "maigptCanCodeInterpreter": True,
    "maigptCanRag": True,
    "maigptCanDeepResearch": True,
    "maigptCanBrowserTool": True,
    "maigptCanCloudDesktop": True,
    "maigptCanVoiceInput": True,
    "maigptAllLlms": True,
    "maigptAllTools": True,
    "maigptAllConnectors": True,
    "maigptAllSkills": True,
    "usageStatisticsScope": {},
    "allowedLlms": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedTools": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedConnectors": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedSkills": [
        "550e8400-e29b-41d4-a716-446655440000"
    ]
}

response = requests.put(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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,
            'canCreateTool' => true,
            'canCreateAgentUiTool' => true,
            'canCreateSkill' => true,
            'canCreateTeam' => true,
            'canCreatePersonalSkill' => true,
            'canCreateVoiceAgent' => true,
            'maigptCanCodeInterpreter' => true,
            'maigptCanRag' => true,
            'maigptCanDeepResearch' => true,
            'maigptCanBrowserTool' => true,
            'maigptCanCloudDesktop' => true,
            'maigptCanVoiceInput' => true,
            'maigptAllLlms' => true,
            'maigptAllTools' => true,
            'maigptAllConnectors' => true,
            'maigptAllSkills' => true,
            'usageStatisticsScope' => new \stdClass(),
            'allowedLlms' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'allowedTools' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'allowedConnectors' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'allowedSkills' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ]
        ]
    ]);
    
    $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": [
    object
  ]
  "membersPreview": [
    string
  ]
  "membersCount": integer // 返回剩餘成員數量（扣除列表顯示的 3 人後），用於前端 +N badge 顯示

與資源 count 不同：
- members_count: 返回 total - 3（用於 +N badge），None 表示總數 <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: 返回總數量
  "chatbotsCount": integer
  "chatbotsPreview": [
    string
  ]
  "knowledgeBasesCount": integer
  "knowledgeBasesPreview": [
    string
  ]
  "inboxesCount": integer
  "inboxesPreview": [
    string
  ]
  "databasesCount": integer
  "databasesPreview": [
    string
  ]
  "canCreateChatbot"?: boolean // 非必填
  "canCreateKnowledgeBase"?: boolean // 非必填
  "canCreateInbox"?: boolean // 非必填
  "canCreateDatabase"?: boolean // 非必填
  "canCreateTool"?: boolean // 非必填
  "canCreateAgentUiTool"?: boolean // 非必填
  "canCreateSkill"?: boolean // 非必填
  "canCreateTeam"?: boolean // Whether members of this role may create Agent Teams; the Team permission is still required. (非必填)
  "canCreatePersonalSkill"?: boolean // Whether members of this role may create personal skills (skills only they can see and use). A member in several roles may if any of them allows it. Turning it off keeps existing personal skills but no new ones can be created. (非必填)
  "canCreateVoiceAgent"?: boolean // Whether members of this role may create voice agents; the Voice Agent permission is still required. (非必填)
  "maigptCanCodeInterpreter"?: boolean // Whether members of this role may use the code interpreter built-in tool in MaiGPT. (非必填)
  "maigptCanRag"?: boolean // Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT. (非必填)
  "maigptCanDeepResearch"?: boolean // Whether members of this role may use Deep Research in MaiGPT. Deep Research reaches the public internet through its own built-in search, so a role that revokes the official web-search tools needs this switch too. (非必填)
  "maigptCanBrowserTool"?: boolean // Whether members of this role may use the browser built-in tool in MaiGPT. (非必填)
  "maigptCanCloudDesktop"?: boolean // Whether members of this role may use the cloud desktop in MaiGPT. (非必填)
  "maigptCanVoiceInput"?: boolean // Whether members of this role may use voice input in MaiGPT, billed by the seconds recorded. (非必填)
  "maigptAllLlms"?: boolean // Whether members of this role may use every organization-available LLM in MaiGPT. Off = only the bound LLMs; an empty binding then means none. (非必填)
  "maigptAllTools"?: boolean // Whether members of this role may call every official (global) tool in MaiGPT. Off = only the bound tools; an empty binding then means none. (非必填)
  "maigptAllConnectors"?: boolean // Whether members of this role may call every official (global) MCP connector in MaiGPT. Off = only the bound connectors; an empty binding then means none. (非必填)
  "maigptAllSkills"?: boolean // Whether members of this role may use every official (global) skill in MaiGPT. Off = only the bound skills; an empty binding then means none. (非必填)
  "usageStatisticsScope"?:  // What this role's usage statistics permission shows: the whole organization, or only the AI assistants granted to the member's roles. A member with any organization-wide granting role sees the whole organization.

* `organization` - Organization-wide
* `accessible_chatbots` - Authorized AI assistants only (非必填)
  {
  }
  "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,
  "canCreateTool": false,
  "canCreateAgentUiTool": false,
  "canCreateSkill": false,
  "canCreateTeam": false,
  "canCreatePersonalSkill": false,
  "canCreateVoiceAgent": false,
  "maigptCanCodeInterpreter": false,
  "maigptCanRag": false,
  "maigptCanDeepResearch": false,
  "maigptCanBrowserTool": false,
  "maigptCanCloudDesktop": false,
  "maigptCanVoiceInput": false,
  "maigptAllLlms": false,
  "maigptAllTools": false,
  "maigptAllConnectors": false,
  "maigptAllSkills": false,
  "usageStatisticsScope": {},
  "createdAt": "回應字串"
}
```

***

### 部分更新角色權限 <a href="#organizations-groups-partial-update" id="organizations-groups-partial-update"></a>

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        | 否  |                                                                                                                                                                                                             |
| canCreateTool            | boolean        | 否  |                                                                                                                                                                                                             |
| canCreateAgentUiTool     | boolean        | 否  |                                                                                                                                                                                                             |
| canCreateSkill           | boolean        | 否  |                                                                                                                                                                                                             |
| canCreateTeam            | boolean        | 否  | Whether members of this role may create Agent Teams; the Team permission is still required.                                                                                                                 |
| canCreatePersonalSkill   | boolean        | 否  | Whether members of this role may create personal skills (skills only they can see and use). A member in several roles may if any of them allows it. Turning it off keeps existing personal skills but no... |
| canCreateVoiceAgent      | boolean        | 否  | Whether members of this role may create voice agents; the Voice Agent permission is still required.                                                                                                         |
| maigptCanCodeInterpreter | boolean        | 否  | Whether members of this role may use the code interpreter built-in tool in MaiGPT.                                                                                                                          |
| maigptCanRag             | boolean        | 否  | Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT.                                                                                                                        |
| maigptCanDeepResearch    | boolean        | 否  | Whether members of this role may use Deep Research in MaiGPT. Deep Research reaches the public internet through its own built-in search, so a role that revokes the official web-search tools needs this... |
| maigptCanBrowserTool     | boolean        | 否  | Whether members of this role may use the browser built-in tool in MaiGPT.                                                                                                                                   |
| maigptCanCloudDesktop    | boolean        | 否  | Whether members of this role may use the cloud desktop in MaiGPT.                                                                                                                                           |
| maigptCanVoiceInput      | boolean        | 否  | Whether members of this role may use voice input in MaiGPT, billed by the seconds recorded.                                                                                                                 |
| maigptAllLlms            | boolean        | 否  | Whether members of this role may use every organization-available LLM in MaiGPT. Off = only the bound LLMs; an empty binding then means none.                                                               |
| maigptAllTools           | boolean        | 否  | Whether members of this role may call every official (global) tool in MaiGPT. Off = only the bound tools; an empty binding then means none.                                                                 |
| maigptAllConnectors      | boolean        | 否  | Whether members of this role may call every official (global) MCP connector in MaiGPT. Off = only the bound connectors; an empty binding then means none.                                                   |
| maigptAllSkills          | boolean        | 否  | Whether members of this role may use every official (global) skill in MaiGPT. Off = only the bound skills; an empty binding then means none.                                                                |
| usageStatisticsScope     | object         | 否  | What this role's usage statistics permission shows: the whole organization, or only the AI assistants granted to the member's roles. A member with any organization-wide granting role sees the whole or... |
| allowedLlms              | array\[string] | 否  |                                                                                                                                                                                                             |
| allowedTools             | array\[string] | 否  |                                                                                                                                                                                                             |
| allowedConnectors        | array\[string] | 否  |                                                                                                                                                                                                             |
| allowedSkills            | array\[string] | 否  |                                                                                                                                                                                                             |

**請求結構範例**

```typescript
{
  "name"?: string // 非必填
  "organization"?: string (uuid) // 非必填
  "permissions"?: [ // 非必填
    string (uuid)
  ]
  "canCreateChatbot"?: boolean // 非必填
  "canCreateKnowledgeBase"?: boolean // 非必填
  "canCreateInbox"?: boolean // 非必填
  "canCreateDatabase"?: boolean // 非必填
  "canCreateTool"?: boolean // 非必填
  "canCreateAgentUiTool"?: boolean // 非必填
  "canCreateSkill"?: boolean // 非必填
  "canCreateTeam"?: boolean // Whether members of this role may create Agent Teams; the Team permission is still required. (非必填)
  "canCreatePersonalSkill"?: boolean // Whether members of this role may create personal skills (skills only they can see and use). A member in several roles may if any of them allows it. Turning it off keeps existing personal skills but no new ones can be created. (非必填)
  "canCreateVoiceAgent"?: boolean // Whether members of this role may create voice agents; the Voice Agent permission is still required. (非必填)
  "maigptCanCodeInterpreter"?: boolean // Whether members of this role may use the code interpreter built-in tool in MaiGPT. (非必填)
  "maigptCanRag"?: boolean // Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT. (非必填)
  "maigptCanDeepResearch"?: boolean // Whether members of this role may use Deep Research in MaiGPT. Deep Research reaches the public internet through its own built-in search, so a role that revokes the official web-search tools needs this switch too. (非必填)
  "maigptCanBrowserTool"?: boolean // Whether members of this role may use the browser built-in tool in MaiGPT. (非必填)
  "maigptCanCloudDesktop"?: boolean // Whether members of this role may use the cloud desktop in MaiGPT. (非必填)
  "maigptCanVoiceInput"?: boolean // Whether members of this role may use voice input in MaiGPT, billed by the seconds recorded. (非必填)
  "maigptAllLlms"?: boolean // Whether members of this role may use every organization-available LLM in MaiGPT. Off = only the bound LLMs; an empty binding then means none. (非必填)
  "maigptAllTools"?: boolean // Whether members of this role may call every official (global) tool in MaiGPT. Off = only the bound tools; an empty binding then means none. (非必填)
  "maigptAllConnectors"?: boolean // Whether members of this role may call every official (global) MCP connector in MaiGPT. Off = only the bound connectors; an empty binding then means none. (非必填)
  "maigptAllSkills"?: boolean // Whether members of this role may use every official (global) skill in MaiGPT. Off = only the bound skills; an empty binding then means none. (非必填)
  "usageStatisticsScope"?:  // What this role's usage statistics permission shows: the whole organization, or only the AI assistants granted to the member's roles. A member with any organization-wide granting role sees the whole organization.

* `organization` - Organization-wide
* `accessible_chatbots` - Authorized AI assistants only (非必填)
  {
  }
  "allowedLlms"?: [ // 非必填
    string (uuid)
  ]
  "allowedTools"?: [ // 非必填
    string (uuid)
  ]
  "allowedConnectors"?: [ // 非必填
    string (uuid)
  ]
  "allowedSkills"?: [ // 非必填
    string (uuid)
  ]
}
```

**請求範例值**

```json
{
  "name": "範例名稱",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "permissions": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "canCreateChatbot": true,
  "canCreateKnowledgeBase": true,
  "canCreateInbox": true,
  "canCreateDatabase": true,
  "canCreateTool": true,
  "canCreateAgentUiTool": true,
  "canCreateSkill": true,
  "canCreateTeam": true,
  "canCreatePersonalSkill": true,
  "canCreateVoiceAgent": true,
  "maigptCanCodeInterpreter": true,
  "maigptCanRag": true,
  "maigptCanDeepResearch": true,
  "maigptCanBrowserTool": true,
  "maigptCanCloudDesktop": true,
  "maigptCanVoiceInput": true,
  "maigptAllLlms": true,
  "maigptAllTools": true,
  "maigptAllConnectors": true,
  "maigptAllSkills": true,
  "usageStatisticsScope": {},
  "allowedLlms": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "allowedTools": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "allowedConnectors": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "allowedSkills": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}
```

#### 程式碼範例

{% 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,
    "canCreateTool": true,
    "canCreateAgentUiTool": true,
    "canCreateSkill": true,
    "canCreateTeam": true,
    "canCreatePersonalSkill": true,
    "canCreateVoiceAgent": true,
    "maigptCanCodeInterpreter": true,
    "maigptCanRag": true,
    "maigptCanDeepResearch": true,
    "maigptCanBrowserTool": true,
    "maigptCanCloudDesktop": true,
    "maigptCanVoiceInput": true,
    "maigptAllLlms": true,
    "maigptAllTools": true,
    "maigptAllConnectors": true,
    "maigptAllSkills": true,
    "usageStatisticsScope": {},
    "allowedLlms": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedTools": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedConnectors": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedSkills": [
      "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 = {
    "name": "範例名稱",
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "permissions": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "canCreateChatbot": true,
    "canCreateKnowledgeBase": true,
    "canCreateInbox": true,
    "canCreateDatabase": true,
    "canCreateTool": true,
    "canCreateAgentUiTool": true,
    "canCreateSkill": true,
    "canCreateTeam": true,
    "canCreatePersonalSkill": true,
    "canCreateVoiceAgent": true,
    "maigptCanCodeInterpreter": true,
    "maigptCanRag": true,
    "maigptCanDeepResearch": true,
    "maigptCanBrowserTool": true,
    "maigptCanCloudDesktop": true,
    "maigptCanVoiceInput": true,
    "maigptAllLlms": true,
    "maigptAllTools": true,
    "maigptAllConnectors": true,
    "maigptAllSkills": true,
    "usageStatisticsScope": {},
    "allowedLlms": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedTools": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedConnectors": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedSkills": [
      "550e8400-e29b-41d4-a716-446655440000"
    ]
  };

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,
    "canCreateTool": True,
    "canCreateAgentUiTool": True,
    "canCreateSkill": True,
    "canCreateTeam": True,
    "canCreatePersonalSkill": True,
    "canCreateVoiceAgent": True,
    "maigptCanCodeInterpreter": True,
    "maigptCanRag": True,
    "maigptCanDeepResearch": True,
    "maigptCanBrowserTool": True,
    "maigptCanCloudDesktop": True,
    "maigptCanVoiceInput": True,
    "maigptAllLlms": True,
    "maigptAllTools": True,
    "maigptAllConnectors": True,
    "maigptAllSkills": True,
    "usageStatisticsScope": {},
    "allowedLlms": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedTools": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedConnectors": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "allowedSkills": [
        "550e8400-e29b-41d4-a716-446655440000"
    ]
}

response = requests.patch(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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,
            'canCreateTool' => true,
            'canCreateAgentUiTool' => true,
            'canCreateSkill' => true,
            'canCreateTeam' => true,
            'canCreatePersonalSkill' => true,
            'canCreateVoiceAgent' => true,
            'maigptCanCodeInterpreter' => true,
            'maigptCanRag' => true,
            'maigptCanDeepResearch' => true,
            'maigptCanBrowserTool' => true,
            'maigptCanCloudDesktop' => true,
            'maigptCanVoiceInput' => true,
            'maigptAllLlms' => true,
            'maigptAllTools' => true,
            'maigptAllConnectors' => true,
            'maigptAllSkills' => true,
            'usageStatisticsScope' => new \stdClass(),
            'allowedLlms' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'allowedTools' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'allowedConnectors' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'allowedSkills' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ]
        ]
    ]);
    
    $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": [
    object
  ]
  "membersPreview": [
    string
  ]
  "membersCount": integer // 返回剩餘成員數量（扣除列表顯示的 3 人後），用於前端 +N badge 顯示

與資源 count 不同：
- members_count: 返回 total - 3（用於 +N badge），None 表示總數 <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: 返回總數量
  "chatbotsCount": integer
  "chatbotsPreview": [
    string
  ]
  "knowledgeBasesCount": integer
  "knowledgeBasesPreview": [
    string
  ]
  "inboxesCount": integer
  "inboxesPreview": [
    string
  ]
  "databasesCount": integer
  "databasesPreview": [
    string
  ]
  "canCreateChatbot"?: boolean // 非必填
  "canCreateKnowledgeBase"?: boolean // 非必填
  "canCreateInbox"?: boolean // 非必填
  "canCreateDatabase"?: boolean // 非必填
  "canCreateTool"?: boolean // 非必填
  "canCreateAgentUiTool"?: boolean // 非必填
  "canCreateSkill"?: boolean // 非必填
  "canCreateTeam"?: boolean // Whether members of this role may create Agent Teams; the Team permission is still required. (非必填)
  "canCreatePersonalSkill"?: boolean // Whether members of this role may create personal skills (skills only they can see and use). A member in several roles may if any of them allows it. Turning it off keeps existing personal skills but no new ones can be created. (非必填)
  "canCreateVoiceAgent"?: boolean // Whether members of this role may create voice agents; the Voice Agent permission is still required. (非必填)
  "maigptCanCodeInterpreter"?: boolean // Whether members of this role may use the code interpreter built-in tool in MaiGPT. (非必填)
  "maigptCanRag"?: boolean // Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT. (非必填)
  "maigptCanDeepResearch"?: boolean // Whether members of this role may use Deep Research in MaiGPT. Deep Research reaches the public internet through its own built-in search, so a role that revokes the official web-search tools needs this switch too. (非必填)
  "maigptCanBrowserTool"?: boolean // Whether members of this role may use the browser built-in tool in MaiGPT. (非必填)
  "maigptCanCloudDesktop"?: boolean // Whether members of this role may use the cloud desktop in MaiGPT. (非必填)
  "maigptCanVoiceInput"?: boolean // Whether members of this role may use voice input in MaiGPT, billed by the seconds recorded. (非必填)
  "maigptAllLlms"?: boolean // Whether members of this role may use every organization-available LLM in MaiGPT. Off = only the bound LLMs; an empty binding then means none. (非必填)
  "maigptAllTools"?: boolean // Whether members of this role may call every official (global) tool in MaiGPT. Off = only the bound tools; an empty binding then means none. (非必填)
  "maigptAllConnectors"?: boolean // Whether members of this role may call every official (global) MCP connector in MaiGPT. Off = only the bound connectors; an empty binding then means none. (非必填)
  "maigptAllSkills"?: boolean // Whether members of this role may use every official (global) skill in MaiGPT. Off = only the bound skills; an empty binding then means none. (非必填)
  "usageStatisticsScope"?:  // What this role's usage statistics permission shows: the whole organization, or only the AI assistants granted to the member's roles. A member with any organization-wide granting role sees the whole organization.

* `organization` - Organization-wide
* `accessible_chatbots` - Authorized AI assistants only (非必填)
  {
  }
  "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,
  "canCreateTool": false,
  "canCreateAgentUiTool": false,
  "canCreateSkill": false,
  "canCreateTeam": false,
  "canCreatePersonalSkill": false,
  "canCreateVoiceAgent": false,
  "maigptCanCodeInterpreter": false,
  "maigptCanRag": false,
  "maigptCanDeepResearch": false,
  "maigptCanBrowserTool": false,
  "maigptCanCloudDesktop": false,
  "maigptCanVoiceInput": false,
  "maigptAllLlms": false,
  "maigptAllTools": false,
  "maigptAllConnectors": false,
  "maigptAllSkills": false,
  "usageStatisticsScope": {},
  "createdAt": "回應字串"
}
```

***

### 刪除角色 <a href="#organizations-groups-destroy" id="organizations-groups-destroy"></a>

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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 |

***

### 移除角色成員 <a href="#organizations-groups-group-members-destroy" id="organizations-groups-group-members-destroy"></a>

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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 助理 <a href="#organizations-groups-group-chatbots-destroy" id="organizations-groups-group-chatbots-destroy"></a>

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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 |

***

### 移除角色裡的收件匣 <a href="#organizations-groups-group-inboxes-destroy" id="organizations-groups-group-inboxes-destroy"></a>

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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 |

***

### 移除角色裡的知識庫 <a href="#organizations-groups-group-knowledge-bases-destroy" id="organizations-groups-group-knowledge-bases-destroy"></a>

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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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 |

***

### 移除角色裡的資料庫 <a href="#organizations-groups-group-databases-destroy" id="organizations-groups-group-databases-destroy"></a>

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
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/api/api-reference/jue-se-he-quan-xian.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
