> 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/en/api-reference/jue-se-he-quan-xian.md).

# Roles and Permissions

### Create a Role <a href="#organizations-groups-create" id="organizations-groups-create"></a>

POST `/api/v1/organizations/{organizationPk}/groups/`

#### Parameters

| Parameter Name   | Required | Type   | Description                                    |
| ---------------- | -------- | ------ | ---------------------------------------------- |
| `organizationPk` | ✅        | string | A UUID string identifying this Organization ID |

#### Request Body

**Request Parameters**

| Field                    | Type           | Required | Description                                                                                                                                                                                                 |
| ------------------------ | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                     | string         | Yes      |                                                                                                                                                                                                             |
| organization             | string (uuid)  | No       |                                                                                                                                                                                                             |
| permissions              | array\[string] | Yes      |                                                                                                                                                                                                             |
| canCreateChatbot         | boolean        | No       |                                                                                                                                                                                                             |
| canCreateKnowledgeBase   | boolean        | No       |                                                                                                                                                                                                             |
| canCreateInbox           | boolean        | No       |                                                                                                                                                                                                             |
| canCreateDatabase        | boolean        | No       |                                                                                                                                                                                                             |
| canCreateTool            | boolean        | No       |                                                                                                                                                                                                             |
| canCreateAgentUiTool     | boolean        | No       |                                                                                                                                                                                                             |
| canCreateSkill           | boolean        | No       |                                                                                                                                                                                                             |
| maigptCanCodeInterpreter | boolean        | No       | Whether members of this role may use the code interpreter built-in tool in MaiGPT.                                                                                                                          |
| maigptCanRag             | boolean        | No       | Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT.                                                                                                                        |
| maigptCanDeepResearch    | boolean        | No       | 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        | No       | Whether members of this role may use the browser built-in tool in MaiGPT.                                                                                                                                   |
| maigptAllLlms            | boolean        | No       | 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        | No       | 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        | No       | 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        | No       | 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         | No       | 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] | No       |                                                                                                                                                                                                             |
| allowedTools             | array\[string] | No       |                                                                                                                                                                                                             |
| allowedConnectors        | array\[string] | No       |                                                                                                                                                                                                             |
| allowedSkills            | array\[string] | No       |                                                                                                                                                                                                             |

**Request Schema Example**

```typescript
{
  "name": string
  "organization"?: string (uuid) // Optional
  "permissions": [
    string (uuid)
  ]
  "canCreateChatbot"?: boolean // Optional
  "canCreateKnowledgeBase"?: boolean // Optional
  "canCreateInbox"?: boolean // Optional
  "canCreateDatabase"?: boolean // Optional
  "canCreateTool"?: boolean // Optional
  "canCreateAgentUiTool"?: boolean // Optional
  "canCreateSkill"?: boolean // Optional
  "maigptCanCodeInterpreter"?: boolean // Whether members of this role may use the code interpreter built-in tool in MaiGPT. (Optional)
  "maigptCanRag"?: boolean // Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT. (Optional)
  "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. (Optional)
  "maigptCanBrowserTool"?: boolean // Whether members of this role may use the browser built-in tool in MaiGPT. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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 (Optional)
  {
  }
  "allowedLlms"?: [ // Optional
    string (uuid)
  ]
  "allowedTools"?: [ // Optional
    string (uuid)
  ]
  "allowedConnectors"?: [ // Optional
    string (uuid)
  ]
  "allowedSkills"?: [ // Optional
    string (uuid)
  ]
}
```

**Example Request Values**

```json
{
  "name": "Example 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,
  "maigptCanCodeInterpreter": true,
  "maigptCanRag": true,
  "maigptCanDeepResearch": true,
  "maigptCanBrowserTool": 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"
  ]
}
```

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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": "Example 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,
    "maigptCanCodeInterpreter": true,
    "maigptCanRag": true,
    "maigptCanDeepResearch": true,
    "maigptCanBrowserTool": 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"
    ]
  }'

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request Body (payload)
const data = {
    "name": "Example 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,
    "maigptCanCodeInterpreter": true,
    "maigptCanRag": true,
    "maigptCanDeepResearch": true,
    "maigptCanBrowserTool": 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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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"
}

# Request Body (payload)
data = {
    "name": "Example 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,
    "maigptCanCodeInterpreter": True,
    "maigptCanRag": True,
    "maigptCanDeepResearch": True,
    "maigptCanBrowserTool": 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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", 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' => 'Example 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,
            'maigptCanCodeInterpreter' => true,
            'maigptCanRag' => true,
            'maigptCanDeepResearch' => true,
            'maigptCanBrowserTool' => 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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

**Status Code: 201**

**Response Schema Example**

```typescript
{
  "id": string (uuid)
  "name": string
  "type": 
  {
  }
  "permissions": [
    object
  ]
  "membersPreview": [
    string
  ]
  "membersCount": integer // Returns the number of remaining members (after subtracting the 3 shown in the list), for the frontend +N badge

Unlike resource counts:
- members_count: Returns total - 3 (for the +N badge); None indicates a total <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: Returns the total count
  "chatbotsCount": integer
  "chatbotsPreview": [
    string
  ]
  "knowledgeBasesCount": integer
  "knowledgeBasesPreview": [
    string
  ]
  "inboxesCount": integer
  "inboxesPreview": [
    string
  ]
  "databasesCount": integer
  "databasesPreview": [
    string
  ]
  "canCreateChatbot"?: boolean // Optional
  "canCreateKnowledgeBase"?: boolean // Optional
  "canCreateInbox"?: boolean // Optional
  "canCreateDatabase"?: boolean // Optional
  "canCreateTool"?: boolean // Optional
  "canCreateAgentUiTool"?: boolean // Optional
  "canCreateSkill"?: boolean // Optional
  "maigptCanCodeInterpreter"?: boolean // Whether members of this role may use the code interpreter built-in tool in MaiGPT. (Optional)
  "maigptCanRag"?: boolean // Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT. (Optional)
  "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. (Optional)
  "maigptCanBrowserTool"?: boolean // Whether members of this role may use the browser built-in tool in MaiGPT. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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 (Optional)
  {
  }
  "createdAt": string (timestamp)
}
```

**Example Response Values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "type": {},
  "permissions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Example response name",
      "description": "Example response description"
    }
  ],
  "membersPreview": [
    "Response string"
  ],
  "membersCount": 456,
  "chatbotsCount": 456,
  "chatbotsPreview": [
    "Response string"
  ],
  "knowledgeBasesCount": 456,
  "knowledgeBasesPreview": [
    "Response string"
  ],
  "inboxesCount": 456,
  "inboxesPreview": [
    "Response string"
  ],
  "databasesCount": 456,
  "databasesPreview": [
    "Response string"
  ],
  "canCreateChatbot": false,
  "canCreateKnowledgeBase": false,
  "canCreateInbox": false,
  "canCreateDatabase": false,
  "canCreateTool": false,
  "canCreateAgentUiTool": false,
  "canCreateSkill": false,
  "maigptCanCodeInterpreter": false,
  "maigptCanRag": false,
  "maigptCanDeepResearch": false,
  "maigptCanBrowserTool": false,
  "maigptAllLlms": false,
  "maigptAllTools": false,
  "maigptAllConnectors": false,
  "maigptAllSkills": false,
  "usageStatisticsScope": {},
  "createdAt": "Response string"
}
```

***

### Bulk Add Role Members <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/`

#### Parameters

| Parameter Name   | Required | Type   | Description                                    |
| ---------------- | -------- | ------ | ---------------------------------------------- |
| `groupPk`        | ✅        | string |                                                |
| `organizationPk` | ✅        | string | A UUID string identifying this organization ID |

#### Request Body

**Request Parameters**

| Field   | Type           | Required | Description |
| ------- | -------------- | -------- | ----------- |
| members | array\[string] | Yes      |             |

**Example Request Structure**

```typescript
{
  "members": [
    string (uuid)
  ]
}
```

**Example Request Values**

```json
{
  "members": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}
```

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# Example API call (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"
    ]
  }'

# Make sure to replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request body (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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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"
}

# Request body (payload)
data = {
    "members": [
        "550e8400-e29b-41d4-a716-446655440000"
    ]
}

response = requests.post(url, json=data, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", 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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Content

**Status code: 201**

**Example Response Structure**

```typescript
[
  {
    "id"?: string (uuid) // Role member ID (optional)
    "member"?: { // optional
    {
      "id"?: string (uuid) // Member ID (optional)
      "name"?: string // Member name (optional)
      "email"?: string (email) // Member email (optional)
      "organization"?: { // optional
      {
        "id"?: string (uuid) // Organization ID (optional)
        "name"?: string // Organization name (optional)
        "createdAt"?: string // Organization creation timestamp (optional)
        "usageStatistics"?: { // optional
        {
          "chatbotsCount"?: integer // Number of chatbots (optional)
          "countableChatbotsCount"?: integer // Number of chatbots that count toward the creation quota (chatbots whose mode is not in the plan allowlist are excluded) (optional)
          "exemptChatbotsByMode"?: object // Number of chatbots exempt from the quota, grouped by the mode that exempts them (optional)
          "canCreateChatbot"?: boolean // Whether chatbots can be created (optional)
          "createChatbotLimit"?: integer // Maximum number of chatbots that can be created (-1 means unlimited, 0 means creation is disabled) (optional)
          "currentMonthWordsCountTotal"?: integer // Total word limit for the current month (optional)
          "currentMonthUsedWordsCountTotal"?: integer // Words used in the current month (optional)
          "currentMonthUsedConversationsCountTotal"?: integer // Conversations used in the current month (optional)
          "availableUploadFilesSizeTotal"?: integer // Total size of files that can be uploaded (optional)
          "usedUploadFileSizeTotal"?: integer // Size of uploaded files used (optional)
        }
        }
        "organizationPlan"?: { // optional
        {
          "id"?: string (uuid) // Plan ID (optional)
          "planName"?: string // Plan name (optional)
          "expiredAt"?: string // Plan expiration time (optional)
        }
        }
      }
      }
      "isOwner"?: boolean // Whether the member is the organization owner (optional)
      "permissions"?: { // optional
      {
        "hasOrganizationAccessPermission"?: boolean // Whether the member has organization access permission (optional)
        "hasChatAccessPermission"?: boolean // Whether the member has chat access permission (optional)
        "hasConversationAccessPermission"?: boolean // Whether the member has conversation access permission (optional)
        "hasChatbotAccessPermission"?: boolean // Whether the member has chatbot access permission (optional)
      }
      }
      "createdAt"?: string // Member creation timestamp (optional)
    }
    }
    "createdAt"?: string // Role member creation timestamp (optional)
  }
]
```

**Example Response Values**

```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": "Free Plan",
          "expiredAt": null
        }
      },
      "isOwner": false,
      "permissions": {
        "hasMaigptAccessPermission": false,
        "hasChatbotAccessPermission": false,
        "hasAgentopsAccessPermission": false,
        "hasConversationAccessPermission": false,
        "hasChatAccessPermission": false,
        "hasDeveloperAccessPermission": false,
        "hasOrganizationAccessPermission": true
      },
      "createdAt": "1748335331000"
    },
    "createdAt": "1748341252000"
  }
]
```

***

### Bulk assign AI assistants to a role <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/`

#### Parameters

| Parameter name   | Required | Type    | Description                                    |
| ---------------- | -------- | ------- | ---------------------------------------------- |
| `groupPk`        | ✅        | string  |                                                |
| `organizationPk` | ✅        | string  | A UUID string identifying this organization ID |
| `page`           | ❌        | integer | A page number within the paginated result set. |
| `pageSize`       | ❌        | integer | Number of results to return per page.          |
| `query`          | ❌        | string  |                                                |
| `search`         | ❌        | string  |                                                |

#### Request body

**Request parameters**

| Field    | Type           | Required | Description |
| -------- | -------------- | -------- | ----------- |
| chatbots | array\[string] | Yes      |             |

**Example request schema**

```typescript
{
  "chatbots": [
    string (uuid)
  ]
}
```

**Example request values**

```json
{
  "chatbots": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}
```

#### Code examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# Example API call (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"
    ]
  }'

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request body (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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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"
}

# Request body (payload)
data = {
    "chatbots": [
        "550e8400-e29b-41d4-a716-446655440000"
    ]
}

response = requests.post(url, json=data, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", 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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response body

**Status code: 201**

**Example response schema**

```typescript
{
  "count": integer
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "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) // The large language model used by the chatbot to generate responses (including the organization's custom AI Gateway models). On creation, this can only be omitted if the organization has configured a default model in its AI assistant defaults.
        "llm":  // The bound model's id, name, and retirement information, read directly from the foreign key. Returned even if the organization has disabled the model.
        {
          "id": string (uuid)
          "name": string
          "retiresAt": string (date) // The provider's retirement date. Once reached, the daily scheduled job switches assistants to the replacement and disables this model. null means no retirement is scheduled.
          "replacement":  // The replacement model after retirement (id and name). null means no replacement is specified and no automatic migration occurs on retirement.
          {
            "id": string (uuid)
            "name": string
          }
        }
        "organizationEnforcedSettings": [ // Setting codes enforced on this assistant by the organization's AI assistant defaults (matching the keys in the AI assistant defaults API). These fields return the enforced values; updates with different values are rejected (read-only; empty for official built-in Agents and MaiGPT).
          string
        ]
        "embeddingModel"?: string (uuid) // The embedding model used to vectorize text; optional (Optional)
        "rerankerModel"?: string (uuid) // The model used for reranking; optional (Optional)
        "instructions"?: string // Role instructions describing the chatbot's role and behavior. (Optional)
        "knowledgeBases"?: [ // Knowledge bases accessible to the chatbot (Optional)
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "databases"?: [ // SQL databases accessible to the chatbot (for Text-to-SQL) (Optional)
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "updatedAt": string (timestamp)
        "organization"?: string (uuid) // The organization the chatbot belongs to. If empty, this is a personal chatbot. (Optional)
        "replyMode"?:  // Reply mode: normal or streaming replies

* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `agent` - Agent (Optional)
        {
        }
        "template"?: string // Template used by Template and Hybrid modes. (Optional)
        "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (Optional)
        "totalWordsCount"?: integer (int64) // Accumulated total word count used. (Optional)
        "outputMode"?:  // Output mode: text, table, or custom format

* `text` - Text
* `json_schema` - JSON Schema (Optional)
        {
        }
        "rawOutputFormat"?: object // JSON schema definition for the custom output format (Optional)
        "groups"?: [ // Groups accessible to the chatbot (Optional)
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "tools"?: [ // Tools available to the chatbot (Optional)
          {
            "id": string (uuid)
            "name": string
            "description": string
            "displayName": string
            "toolType": string
          }
        ]
        "skills"?: [ // Skills associated with the chatbot (Optional)
          {
            "id": string (uuid)
            "name": string
            "description": string
          }
        ]
        "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (Optional)
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "agentMode"?:  // Agent mode: normal, SQL, or workflow mode

* `normal` - Normal
* `canvas` - Canvas
* `team` - Team (Optional)
        {
        }
        "numberOfRetrievedChunks"?: integer // Number of reference chunks to retrieve. Defaults to 12; minimum: 1. (Optional)
        "defaultLabelRelations"?: object // Assistant-level default knowledge base label filter, using the same format as query_metadata.label_relations. null means no filtering. Applied as the lowest-priority fallback only when the caller omits query_metadata. (Optional)
        "useFullRetrievalRange"?: boolean // When enabled, ignores the LLM's top_k truncation and returns the full reranker results. (Optional)
        "enableEvaluation"?: boolean // Optional
        "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (Optional)
        "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (Optional)
        "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (Optional)
        "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (Optional)
        "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. (Optional)
        "customMaxLlmOutputTokens"?: integer // Custom maximum number of LLM output tokens; minimum: 512. (Optional)
        "voiceConfig"?: { // Optional
        {
          "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. (Optional)
          "voiceAgentType"?: string (uuid) // Voice agent mode type. (Optional)
          "sttProvider"?: string (uuid) // Speech-to-Text service provider. (Optional)
          "sttConfig"?: object // STT configuration parameters (JSON). (Optional)
          "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (Optional)
          "ttsConfig"?: object // TTS configuration parameters (JSON). (Optional)
          "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (Optional)
          "realtimeConfig"?: object // Realtime configuration parameters (JSON). (Optional)
          "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (Optional)
          "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (Optional)
          "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (Optional)
        }
        }
        "thinkingConfig"?: object // Thinking level: null (model default) or {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (Optional)
        "enableToolSearching"?: boolean // Legacy field; use tool_loading_mode instead. Writing true is equivalent to tool_loading_mode=search, and false to all. If both are provided, tool_loading_mode takes precedence. Reading returns whether the tool loading mode is anything other than load all. (Optional)
        "toolLoadingMode"?:  // Tool loading mode: auto (selected automatically based on the tools available for the turn and the model), all (load all), or search (dynamic search). New assistants default to auto. Existing assistants without this setting return a value derived from the legacy toggle (on → search, off → all).

* `auto` - Auto
* `all` - Load all
* `search` - Dynamic search (Optional)
        {
        }
        "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (Optional)
        "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (Optional)
        "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (Optional)
        "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. (Optional)
        "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.). (Optional)
        "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (Optional)
        "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. (Optional)
        "longTermMemoryTopK"?: integer // Number of memory nodes returned per long-term memory retrieval (similarity_top_k for vector retrieval). Defaults to 10; range: 1–50. (Optional)
        "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. (Optional)
        "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. (Optional)
        "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (Optional)
        "gatewayFallbackGroup"?: string (uuid) // Optional
        "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (Optional)
        "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (Optional)
        "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (Optional)
        "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (Optional)
        "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (Optional)
        "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (Optional)
        "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. (Optional)
        "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. (Optional)
        "fileWorkspaceMode"?:  // File workspace mode in Work internal conversations: none, bound or user_mount.

* `none` - None
* `bound` - Bound workspace
* `user_mount` - User mount (Optional)
        {
        }
        "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (Optional)
        "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 // Optional
      "canUpdate"?: boolean // Optional
      "canDelete"?: boolean // Optional
      "createdAt": string (timestamp)
    }
  ]
}
```

**Example response values**

```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": "Response string",
        "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
        "llm": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Response string",
          "retiresAt": "Response string",
          "replacement": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Response string"
          }
        },
        "organizationEnforcedSettings": [
          "Response string"
        ],
        "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
        "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
        "instructions": "Response string",
        "knowledgeBases": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Response string"
          }
        ],
        "databases": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Response string"
          }
        ],
        "updatedAt": "Response string",
        "organization": "550e8400-e29b-41d4-a716-446655440000",
        "replyMode": {},
        "template": "Response string",
        "unanswerableTemplate": "Response string",
        "totalWordsCount": 456,
        "outputMode": {},
        "rawOutputFormat": null,
        "groups": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Response string"
          }
        ],
        "tools": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Response string",
            "description": "Response string",
            "displayName": "Response string",
            "toolType": "Response string"
          }
        ],
        "skills": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Response string",
            "description": "Response string"
          }
        ],
        "connectors": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Response string"
          }
        ],
        "agentMode": {},
        "numberOfRetrievedChunks": 456,
        "defaultLabelRelations": null,
        "useFullRetrievalRange": false,
        "enableEvaluation": false,
        "enableInlineCitations": false,
        "enableCodeInterpreter": false,
        "enableBrowserTool": false,
        "enableImageSearch": false,
        "enableClaudeStreamRetry": 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": "Response string",
          "turnHandling": null,
          "enableVoiceReply": false
        },
        "thinkingConfig": null,
        "enableToolSearching": false,
        "toolLoadingMode": {},
        "maxAgentIterations": 456,
        "agentTimeoutSeconds": 456,
        "agentTimeoutMessage": "Response string",
        "requireTextWithFlexCards": false,
        "isMultimodalLlm": false,
        "enableSizeBasedToolResultTruncation": false,
        "toolResultMaxChars": 456,
        "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": "Response string"
        },
        "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": "Response string"
    }
  ]
}
```

***

### Bulk Assign Inboxes to Role <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/`

#### Parameters

| Parameter        | Required | Type   | Description                                    |
| ---------------- | -------- | ------ | ---------------------------------------------- |
| `groupPk`        | ✅        | string |                                                |
| `organizationPk` | ✅        | string | A UUID string identifying this organization ID |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# Example API call (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"

# Make sure to replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// Request body (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('Successfully retrieved response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", 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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

| Status Code | Description      |
| ----------- | ---------------- |
| 200         | No response body |

***

### Bulk Assign Knowledge Bases to a Role <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/`

#### Parameters

| Parameter        | Required | Type    | Description                                    |
| ---------------- | -------- | ------- | ---------------------------------------------- |
| `groupPk`        | ✅        | string  |                                                |
| `organizationPk` | ✅        | string  | A UUID string identifying this Organization ID |
| `page`           | ❌        | integer | A page number within the paginated result set. |
| `pageSize`       | ❌        | integer | Number of results to return per page.          |
| `query`          | ❌        | string  |                                                |
| `search`         | ❌        | string  |                                                |

#### Request

**Request Parameters**

| Field          | Type           | Required | Description |
| -------------- | -------------- | -------- | ----------- |
| knowledgeBases | array\[string] | Yes      |             |

**Request Schema**

```typescript
{
  "knowledgeBases": [
    string (uuid)
  ]
}
```

**Request Example**

```json
{
  "knowledgeBases": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}
```

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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"
    ]
  }'

# Make sure to replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request 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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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"
}

# Request payload
data = {
    "knowledgeBases": [
        "550e8400-e29b-41d4-a716-446655440000"
    ]
}

response = requests.post(url, json=data, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", 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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

**Status Code: 201**

**Response Schema**

```typescript
{
  "count": integer
  "next"?: string (uri) // optional
  "previous"?: string (uri) // optional
  "results": [
    {
      "id": string (uuid)
      "group": string (uuid)
      "knowledgeBase": 
      {
        "id": string (uuid)
        "createdBy": 
        {
          "id": string (uuid)
          "name": string
        }
        "organization"?: string (uuid) // optional
        "embeddingModel": string (uuid)
        "rerankerModel": string (uuid)
        "name": string
        "description"?: string // optional
        "numberOfRetrievedChunks"?: integer // Number of retrieved reference chunks. Default is 12, minimum is 1 (optional)
        "enableHyde"?: boolean // Enable HyDE. Default is False (optional)
        "similarityCutoff"?: number (double) // Similarity threshold. Default is 0.0, range 0.0-1.0 (optional)
        "enableRerank"?: boolean // Whether to enable reranking. Default is True (optional)
        "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (optional)
        "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai
* `synxdb` - SynxDB (optional)
        {
        }
        "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"). (optional)
        "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (optional)
        "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (optional)
        "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (optional)
        "oracleUser"?: string // Oracle database username. (optional)
        "oraclePassword"?: string // Oracle database password. (optional)
        "synxdbUser"?: string // SynxDB database username. (optional)
        "synxdbPassword"?: string // SynxDB database password. (optional)
        "labels": [
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "chatbots"?: [ // optional
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "groups"?: [ // List of groups that can access the knowledge base (optional)
          {
            "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 // optional
      "canUpdate"?: boolean // optional
      "canDelete"?: boolean // optional
      "createdAt": string (timestamp)
    }
  ]
}
```

**Response Example**

```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": "response string"
        },
        "organization": "550e8400-e29b-41d4-a716-446655440000",
        "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
        "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
        "name": "response string",
        "description": "response string",
        "numberOfRetrievedChunks": 456,
        "enableHyde": false,
        "similarityCutoff": 456,
        "enableRerank": false,
        "enableRrf": false,
        "vectorDatabaseType": {},
        "vectorDatabaseUrl": "response string",
        "vectorDatabaseApiKey": "response string",
        "opensearchUsername": "response string",
        "opensearchPassword": "response string",
        "oracleUser": "response string",
        "oraclePassword": "response string",
        "synxdbUser": "response string",
        "synxdbPassword": "response string",
        "labels": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "response string"
          }
        ],
        "chatbots": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "response string"
          }
        ],
        "groups": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "response string"
          }
        ],
        "filesCount": 456,
        "vectorStorageSize": 456,
        "chunksCount": 456,
        "canUpdate": false,
        "canDelete": false,
        "createdAt": "response string",
        "updatedAt": "response string"
      },
      "canRead": false,
      "canUpdate": false,
      "canDelete": false,
      "createdAt": "response string"
    }
  ]
}
```

***

### Bulk Assign Databases to a Role <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/`

#### Parameters

| Parameter        | Required | Type    | Description                                    |
| ---------------- | -------- | ------- | ---------------------------------------------- |
| `groupPk`        | ✅        | string  |                                                |
| `organizationPk` | ✅        | string  | A UUID string identifying this Organization ID |
| `page`           | ❌        | integer | A page number within the paginated result set. |
| `pageSize`       | ❌        | integer | Number of results to return per page.          |
| `query`          | ❌        | string  |                                                |
| `search`         | ❌        | string  |                                                |

#### Request

**Request Parameters**

| Field     | Type           | Required | Description |
| --------- | -------------- | -------- | ----------- |
| databases | array\[string] | Yes      |             |

**Request Schema**

```typescript
{
  "databases": [
    string (uuid)
  ]
}
```

**Request Example**

```json
{
  "databases": [
    "550e8400-e29b-41d4-a716-446655440000"
  ]
}
```

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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"
    ]
  }'

# Make sure to replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request 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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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"
}

# Request payload
data = {
    "databases": [
        "550e8400-e29b-41d4-a716-446655440000"
    ]
}

response = requests.post(url, json=data, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", 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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

**Status Code: 201**

**Response Schema**

```typescript
{
  "count": integer
  "next"?: string (uri) // optional
  "previous"?: string (uri) // optional
  "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 (optional)
            "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) (optional)
                "description"?: string // Description of the column for better Text-to-SQL understanding (optional)
                "isPrimaryKey"?: boolean // optional
                "isNullable"?: boolean // optional
                "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 // optional
      "canUpdate"?: boolean // optional
      "canDelete"?: boolean // optional
      "createdAt": string (timestamp)
    }
  ]
}
```

**Response Example**

```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": "response string",
        "description": "response string",
        "databaseType": {},
        "includeTables": null,
        "isActive": false,
        "status": {},
        "deletedAt": "response string",
        "tables": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "tableName": "response string",
            "sheetName": "response string",
            "description": "response string",
            "status": {},
            "errorMessage": "response string",
            "sourceFile": {
              "id": "550e8400-e29b-41d4-a716-446655440000",
              "name": "response string",
              "isFromKnowledgeBase": false
            },
            "columns": [
              {
                "id": "550e8400-e29b-41d4-a716-446655440000",
                "columnName": "response string",
                "columnType": "response string",
                "description": "response string",
                "isPrimaryKey": false,
                "isNullable": false,
                "createdAt": "response string",
                "updatedAt": "response string"
              }
            ],
            "createdAt": "response string",
            "updatedAt": "response string"
          }
        ],
        "chatbots": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "response string"
          }
        ],
        "groups": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "response string"
          }
        ],
        "createdAt": "response string",
        "updatedAt": "response string"
      },
      "canRead": false,
      "canUpdate": false,
      "canDelete": false,
      "createdAt": "response string"
    }
  ]
}
```

***

### List Permissions <a href="#permissions-list" id="permissions-list"></a>

GET `/api/v1/permissions/`

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/permissions/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Make sure to replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/permissions/", config)
  .then(response => {
    console.log('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", 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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

**Status Code: 200**

**Response Schema**

```typescript
[
  {
    "id": string (uuid)
    "name": string
    "value": string
    "description": string
    "children": [
      object
    ]
  }
]
```

**Example Response Values**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response string",
    "value": "Response string",
    "description": "Response string",
    "children": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Response example name",
        "description": "Response example description"
      }
    ]
  }
]
```

***

### List Roles <a href="#organizations-groups-list" id="organizations-groups-list"></a>

GET `/api/v1/organizations/{organizationPk}/groups/`

#### Parameters

| Parameter Name   | Required | Type    | Description                                                             |
| ---------------- | -------- | ------- | ----------------------------------------------------------------------- |
| `organizationPk` | ✅        | string  | A UUID string identifying this organization 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; |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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=custom" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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=custom", config)
  .then(response => {
    console.log('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred during the request:');
    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=custom"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", 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=custom", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

**Status Code: 200**

**Response Schema Example**

```typescript
{
  "count": integer
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "results": [
    {
      "id": string (uuid)
      "name": string
      "type": 
      {
      }
      "permissions": [
        object
      ]
      "membersPreview": [
        string
      ]
      "membersCount": integer // Returns the remaining number of members (after deducting the 3 shown in the list), used for the frontend +N badge display

Unlike resource counts:
- members_count: returns total - 3 (used for the +N badge); None means the total is <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: return the total count
      "chatbotsCount": integer
      "chatbotsPreview": [
        string
      ]
      "knowledgeBasesCount": integer
      "knowledgeBasesPreview": [
        string
      ]
      "inboxesCount": integer
      "inboxesPreview": [
        string
      ]
      "databasesCount": integer
      "databasesPreview": [
        string
      ]
      "canCreateChatbot"?: boolean // Optional
      "canCreateKnowledgeBase"?: boolean // Optional
      "canCreateInbox"?: boolean // Optional
      "canCreateDatabase"?: boolean // Optional
      "canCreateTool"?: boolean // Optional
      "canCreateAgentUiTool"?: boolean // Optional
      "canCreateSkill"?: boolean // Optional
      "maigptCanCodeInterpreter"?: boolean // Whether members of this role may use the code interpreter built-in tool in MaiGPT. (Optional)
      "maigptCanRag"?: boolean // Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT. (Optional)
      "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. (Optional)
      "maigptCanBrowserTool"?: boolean // Whether members of this role may use the browser built-in tool in MaiGPT. (Optional)
      "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. (Optional)
      "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. (Optional)
      "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. (Optional)
      "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. (Optional)
      "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 (Optional)
      {
      }
      "createdAt": string (timestamp)
    }
  ]
}
```

**Response Example Value**

```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": "response string",
      "type": {},
      "permissions": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "response example name",
          "description": "response example description"
        }
      ],
      "membersPreview": [
        "response string"
      ],
      "membersCount": 456,
      "chatbotsCount": 456,
      "chatbotsPreview": [
        "response string"
      ],
      "knowledgeBasesCount": 456,
      "knowledgeBasesPreview": [
        "response string"
      ],
      "inboxesCount": 456,
      "inboxesPreview": [
        "response string"
      ],
      "databasesCount": 456,
      "databasesPreview": [
        "response string"
      ],
      "canCreateChatbot": false,
      "canCreateKnowledgeBase": false,
      "canCreateInbox": false,
      "canCreateDatabase": false,
      "canCreateTool": false,
      "canCreateAgentUiTool": false,
      "canCreateSkill": false,
      "maigptCanCodeInterpreter": false,
      "maigptCanRag": false,
      "maigptCanDeepResearch": false,
      "maigptCanBrowserTool": false,
      "maigptAllLlms": false,
      "maigptAllTools": false,
      "maigptAllConnectors": false,
      "maigptAllSkills": false,
      "usageStatisticsScope": {},
      "createdAt": "response string"
    }
  ]
}
```

***

### Get Role Details <a href="#organizations-groups-retrieve" id="organizations-groups-retrieve"></a>

GET `/api/v1/organizations/{organizationPk}/groups/{id}/`

#### Parameters

| Parameter Name   | Required | Type   | Description                                    |
| ---------------- | -------- | ------ | ---------------------------------------------- |
| `id`             | ✅        | string | A UUID string identifying this Group.          |
| `organizationPk` | ✅        | string | A UUID string identifying this organization ID |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred during the request:');
    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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", 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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

**Status Code: 200**

**Response Schema Example**

```typescript
{
  "id": string (uuid)
  "name": string
  "type": 
  {
  }
  "permissions": [
    object
  ]
  "membersPreview": [
    string
  ]
  "membersCount": integer // Returns the remaining number of members (after deducting the 3 shown in the list), used for the frontend +N badge display

Unlike resource counts:
- members_count: returns total - 3 (used for the +N badge); None means the total is <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: return the total count
  "chatbotsCount": integer
  "chatbotsPreview": [
    string
  ]
  "knowledgeBasesCount": integer
  "knowledgeBasesPreview": [
    string
  ]
  "inboxesCount": integer
  "inboxesPreview": [
    string
  ]
  "databasesCount": integer
  "databasesPreview": [
    string
  ]
  "canCreateChatbot"?: boolean // Optional
  "canCreateKnowledgeBase"?: boolean // Optional
  "canCreateInbox"?: boolean // Optional
  "canCreateDatabase"?: boolean // Optional
  "canCreateTool"?: boolean // Optional
  "canCreateAgentUiTool"?: boolean // Optional
  "canCreateSkill"?: boolean // Optional
  "maigptCanCodeInterpreter"?: boolean // Whether members of this role may use the code interpreter built-in tool in MaiGPT. (Optional)
  "maigptCanRag"?: boolean // Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT. (Optional)
  "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. (Optional)
  "maigptCanBrowserTool"?: boolean // Whether members of this role may use the browser built-in tool in MaiGPT. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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 (Optional)
  {
  }
  "createdAt": string (timestamp)
}
```

**Response Example Value**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "response string",
  "type": {},
  "permissions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "response example name",
      "description": "response example description"
    }
  ],
  "membersPreview": [
    "response string"
  ],
  "membersCount": 456,
  "chatbotsCount": 456,
  "chatbotsPreview": [
    "response string"
  ],
  "knowledgeBasesCount": 456,
  "knowledgeBasesPreview": [
    "response string"
  ],
  "inboxesCount": 456,
  "inboxesPreview": [
    "response string"
  ],
  "databasesCount": 456,
  "databasesPreview": [
    "response string"
  ],
  "canCreateChatbot": false,
  "canCreateKnowledgeBase": false,
  "canCreateInbox": false,
  "canCreateDatabase": false,
  "canCreateTool": false,
  "canCreateAgentUiTool": false,
  "canCreateSkill": false,
  "maigptCanCodeInterpreter": false,
  "maigptCanRag": false,
  "maigptCanDeepResearch": false,
  "maigptCanBrowserTool": false,
  "maigptAllLlms": false,
  "maigptAllTools": false,
  "maigptAllConnectors": false,
  "maigptAllSkills": false,
  "usageStatisticsScope": {},
  "createdAt": "response string"
}
```

***

### List Role Members <a href="#organizations-groups-group-members-list" id="organizations-groups-group-members-list"></a>

GET `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-members/`

#### Parameters

| Parameter Name   | Required | Type    | Description                                    |
| ---------------- | -------- | ------- | ---------------------------------------------- |
| `groupPk`        | ✅        | string  |                                                |
| `organizationPk` | ✅        | string  | A UUID string identifying this organization ID |
| `page`           | ❌        | integer | A page number within the paginated result set. |
| `pageSize`       | ❌        | integer | Number of results to return per page.          |
| `query`          | ❌        | string  |                                                |
| `search`         | ❌        | string  |                                                |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", 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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

**Status Code: 200**

**Response Schema Example**

```typescript
{
  "count": integer
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "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 // Check whether the member is an organization owner (via the OWNER Group)

Use caching to avoid repeated queries within the same request
Cache lifetime: valid for the lifetime of the member instance

Prefer annotation results, if available, to avoid repeated queries
        "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.
          object
        ]
        "groups": [
          object
        ]
        "creditQuotaRequired"?: boolean // When True, member must have an active quota to consume credits (Optional)
        "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)
    }
  ]
}
```

**Example Response Values**

```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": "response string",
        "displayName": "response string",
        "accountName": "response string",
        "isScimManaged": false,
        "email": "response string",
        "isActive": false,
        "isOwner": false,
        "permissions": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Example response name",
            "description": "Example response description"
          }
        ],
        "groups": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Example response name",
            "description": "Example response description"
          }
        ],
        "creditQuotaRequired": false,
        "activeQuota": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Example response name",
          "description": "Example response description"
        },
        "metadata": null,
        "availabilityStatus": {},
        "createdAt": "response string"
      },
      "createdAt": "response string"
    }
  ]
}
```

***

### Retrieve a Role Member <a href="#organizations-groups-group-members-retrieve" id="organizations-groups-group-members-retrieve"></a>

GET `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-members/{id}/`

#### Parameters

| Parameter Name   | Required | Type   | Description                                    |
| ---------------- | -------- | ------ | ---------------------------------------------- |
| `groupPk`        | ✅        | string |                                                |
| `id`             | ✅        | string | A UUID string identifying this Group Member.   |
| `organizationPk` | ✅        | string | A UUID string identifying this organization ID |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", 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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

**Status Code: 200**

**Response Schema Example**

```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 // Check whether the member is an organization owner (via the OWNER Group)

Use caching to avoid repeated queries within the same request
Cache lifetime: valid for the lifetime of the member instance

Prefer annotation results, if available, to avoid repeated queries
    "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.
      object
    ]
    "groups": [
      object
    ]
    "creditQuotaRequired"?: boolean // When True, member must have an active quota to consume credits (Optional)
    "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)
}
```

**Example Response Values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "member": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "response string",
    "displayName": "response string",
    "accountName": "response string",
    "isScimManaged": false,
    "email": "response string",
    "isActive": false,
    "isOwner": false,
    "permissions": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Example response name",
        "description": "Example response description"
      }
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Example response name",
        "description": "Example response description"
      }
    ],
    "creditQuotaRequired": false,
    "activeQuota": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Example response name",
      "description": "Example response description"
    },
    "metadata": null,
    "availabilityStatus": {},
    "createdAt": "response string"
  },
  "createdAt": "response string"
}
```

***

### List AI Assistants for a Role <a href="#organizations-groups-group-chatbots-list" id="organizations-groups-group-chatbots-list"></a>

GET `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-chatbots/`

#### Parameters

| Parameter Name   | Required | Type    | Description                                    |
| ---------------- | -------- | ------- | ---------------------------------------------- |
| `groupPk`        | ✅        | string  |                                                |
| `organizationPk` | ✅        | string  | A UUID string identifying this organization ID |
| `page`           | ❌        | integer | A page number within the paginated result set. |
| `pageSize`       | ❌        | integer | Number of results to return per page.          |
| `query`          | ❌        | string  |                                                |
| `search`         | ❌        | string  |                                                |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", 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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

**Status Code: 200**

**Response Schema Example**

```typescript
{
  "count": integer
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "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) // The large language model the chatbot uses to generate responses (including custom AI Gateway models configured by the organization); it can be omitted during creation only if the organization has set a default model in its AI assistant defaults
        "llm":  // The linked model's id, name, and retirement information, read directly from the FK; returned even if the organization has disabled the model
        {
          "id": string (uuid)
          "name": string
          "retiresAt": string (date) // The provider's retirement date; once reached, the daily scheduled task switches the assistant to the replacement and disables this model. null means no retirement is scheduled
          "replacement":  // The replacement model after retirement (id and name); null means none is specified and no automatic migration occurs on the retirement date
          {
            "id": string (uuid)
            "name": string
          }
        }
        "organizationEnforcedSettings": [ // Setting codes enforced for this assistant by the organization's AI assistant defaults (matching the keys in the AI assistant defaults API); these fields return the enforced values, and updates with different values are rejected (read-only; empty for official built-in Agents and MaiGPT)
          string
        ]
        "embeddingModel"?: string (uuid) // Embedding model used to vectorize text; optional (Optional)
        "rerankerModel"?: string (uuid) // Model used for reranking; optional (Optional)
        "instructions"?: string // Role instructions describing the chatbot's role and behavior. (Optional)
        "knowledgeBases"?: [ // Knowledge bases the chatbot can access (Optional)
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "databases"?: [ // SQL databases the chatbot can access (for Text-to-SQL) (Optional)
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "updatedAt": string (timestamp)
        "organization"?: string (uuid) // The organization the chatbot belongs to; if empty, this is a personal chatbot (Optional)
        "replyMode"?:  // Reply mode: standard or streaming responses

* `normal` - Normal
* `template` - Template
* `hybrid` - Hybrid
* `agent` - Agent (Optional)
        {
        }
        "template"?: string // Template used by Template and Hybrid modes. (Optional)
        "unanswerableTemplate"?: string // Template used by Template and Hybrid modes when the question cannot be answered. (Optional)
        "totalWordsCount"?: integer (int64) // Accumulated total word count used. (Optional)
        "outputMode"?:  // Output mode: text, table, or custom format

* `text` - Text
* `json_schema` - JSON Schema (Optional)
        {
        }
        "rawOutputFormat"?: object // JSON schema definition for the custom output format (Optional)
        "groups"?: [ // Groups the chatbot can access (Optional)
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "tools"?: [ // Tools available to the chatbot (Optional)
          {
            "id": string (uuid)
            "name": string
            "description": string
            "displayName": string
            "toolType": string
          }
        ]
        "skills"?: [ // Skills associated with the chatbot (Optional)
          {
            "id": string (uuid)
            "name": string
            "description": string
          }
        ]
        "connectors"?: [ // Connectors associated with this chatbot, gating per-contact OAuth authorization (Optional)
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "agentMode"?:  // Agent mode: normal, SQL, or workflow mode

* `normal` - Normal
* `canvas` - Canvas
* `team` - Team (Optional)
        {
        }
        "numberOfRetrievedChunks"?: integer // Number of reference chunks to retrieve; defaults to 12, minimum 1 (Optional)
        "defaultLabelRelations"?: object // Default assistant-level knowledge base label filters, using the same format as query_metadata.label_relations; null means no filtering. Applied as the lowest-priority fallback only when the caller omits query_metadata. (Optional)
        "useFullRetrievalRange"?: boolean // When enabled, ignores LLM top_k truncation and returns the full reranker results (Optional)
        "enableEvaluation"?: boolean // Optional
        "enableInlineCitations"?: boolean // Enables inline citations, inserting citation markers such as [1][2] into responses. (Optional)
        "enableCodeInterpreter"?: boolean // When enabled, provides the Code Interpreter tool to run code in an isolated container. (Optional)
        "enableBrowserTool"?: boolean // Enable browser automation tool for web tasks (Optional)
        "enableImageSearch"?: boolean // Provide the image_search tool when any attached knowledge base uses a multimodal embedding model. Disable to remove the tool entirely. (Optional)
        "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. (Optional)
        "customMaxLlmOutputTokens"?: integer // Custom maximum number of LLM output tokens, minimum 512 (Optional)
        "voiceConfig"?: { // Optional
        {
          "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. (Optional)
          "voiceAgentType"?: string (uuid) // Voice agent mode type. (Optional)
          "sttProvider"?: string (uuid) // Speech-to-Text service provider. (Optional)
          "sttConfig"?: object // STT configuration parameters (JSON). (Optional)
          "ttsProvider"?: string (uuid) // Text-to-Speech service provider. (Optional)
          "ttsConfig"?: object // TTS configuration parameters (JSON). (Optional)
          "realtimeProvider"?: string (uuid) // Realtime end-to-end voice model provider. (Optional)
          "realtimeConfig"?: object // Realtime configuration parameters (JSON). (Optional)
          "realtimeInstructions"?: string // Prompt dedicated to the realtime voice session; falls back to chatbot instructions when empty (Optional)
          "turnHandling"?: object // Turn-taking and interruption settings for the voice agent. (Optional)
          "enableVoiceReply"?: boolean // When disabled, the voice agent replies in text only and does not speak (Optional)
        }
        }
        "thinkingConfig"?: object // Reasoning level: null (model default) or {"reasoning_effort": "off|minimal|low|medium|high|xhigh|max"} (Optional)
        "enableToolSearching"?: boolean // Legacy field; use tool_loading_mode instead. Writing true is equivalent to tool_loading_mode=search, and false to all; tool_loading_mode takes precedence when both are provided. On read, returns whether the tool loading mode is other than all. (Optional)
        "toolLoadingMode"?:  // Tool loading mode: auto (selected automatically based on the number of available tools and the model for the current turn), all (load all), or search (dynamic search). New assistants default to auto; existing assistants without an explicit setting return a value derived from the previous toggle (on → search, off → all).

* `auto` - Auto
* `all` - Load all
* `search` - Dynamic search (Optional)
        {
        }
        "maxAgentIterations"?: integer // Maximum number of iterations for AgentWorkflow (1-100, default: 20) (Optional)
        "agentTimeoutSeconds"?: integer // Timeout in seconds for AgentWorkflow execution (30-1200, default: 600) (Optional)
        "agentTimeoutMessage"?: string // Custom user-facing message shown when AgentWorkflow times out (max 500 chars). Leave empty to use the system default. (Optional)
        "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. (Optional)
        "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.). (Optional)
        "toolResultMaxChars"?: integer // Character threshold for size-based tool result truncation (500-50000). Only effective when enable_size_based_tool_result_truncation is True. (Optional)
        "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. (Optional)
        "longTermMemoryTopK"?: integer // Number of long-term memory nodes retrieved per search (similarity_top_k for vector retrieval); defaults to 10, range 1–50 (Optional)
        "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. (Optional)
        "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. (Optional)
        "useGatewayFallback"?: boolean // When enabled, use the fallback group instead of the single LLM (Optional)
        "gatewayFallbackGroup"?: string (uuid) // Optional
        "enableSearchMessagesTool"?: boolean // Allow the AI to search past messages in the current conversation. (Optional)
        "enableGetMessageContextTool"?: boolean // Allow the AI to retrieve messages surrounding a specific message for context. (Optional)
        "enableReadAttachmentFullTextTool"?: boolean // Allow the AI to read the full text of plain-text attachments. AGENT mode only. (Optional)
        "enableParseAttachmentContentTool"?: boolean // Allow the AI to parse PDF, Office, audio, and other attachments. AGENT mode only. (Optional)
        "enableListAvailableParsersTool"?: boolean // Allow the AI to list available parsers and their capabilities. AGENT mode only. (Optional)
        "enableGetDownloadLinkTool"?: boolean // Allow the AI to generate shareable download links for produced content. AGENT mode only. (Optional)
        "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. (Optional)
        "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. (Optional)
        "fileWorkspaceMode"?:  // File workspace mode in Work internal conversations: none, bound or user_mount.

* `none` - None
* `bound` - Bound workspace
* `user_mount` - User mount (Optional)
        {
        }
        "fileWorkspaceFolder"?: string (uuid) // The bound workspace (folder id); required when the mode is bound, cleared otherwise. (Optional)
        "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 // Optional
      "canUpdate"?: boolean // Optional
      "canDelete"?: boolean // Optional
      "createdAt": string (timestamp)
    }
  ]
}
```

**Example response values**

```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": "Response string",
        "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
        "llm": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Response string",
          "retiresAt": "Response string",
          "replacement": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Response string"
          }
        },
        "organizationEnforcedSettings": [
          "Response string"
        ],
        "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
        "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
        "instructions": "Response string",
        "knowledgeBases": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Response string"
          }
        ],
        "databases": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Response string"
          }
        ],
        "updatedAt": "Response string",
        "organization": "550e8400-e29b-41d4-a716-446655440000",
        "replyMode": {},
        "template": "Response string",
        "unanswerableTemplate": "Response string",
        "totalWordsCount": 456,
        "outputMode": {},
        "rawOutputFormat": null,
        "groups": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Response string"
          }
        ],
        "tools": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Response string",
            "description": "Response string",
            "displayName": "Response string",
            "toolType": "Response string"
          }
        ],
        "skills": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Response string",
            "description": "Response string"
          }
        ],
        "connectors": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Response string"
          }
        ],
        "agentMode": {},
        "numberOfRetrievedChunks": 456,
        "defaultLabelRelations": null,
        "useFullRetrievalRange": false,
        "enableEvaluation": false,
        "enableInlineCitations": false,
        "enableCodeInterpreter": false,
        "enableBrowserTool": false,
        "enableImageSearch": false,
        "enableClaudeStreamRetry": 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": "Response string",
          "turnHandling": null,
          "enableVoiceReply": false
        },
        "thinkingConfig": null,
        "enableToolSearching": false,
        "toolLoadingMode": {},
        "maxAgentIterations": 456,
        "agentTimeoutSeconds": 456,
        "agentTimeoutMessage": "Response string",
        "requireTextWithFlexCards": false,
        "isMultimodalLlm": false,
        "enableSizeBasedToolResultTruncation": false,
        "toolResultMaxChars": 456,
        "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": "Response string"
        },
        "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": "Response string"
    }
  ]
}
```

***

### List Role Inboxes <a href="#organizations-groups-group-inboxes-list" id="organizations-groups-group-inboxes-list"></a>

GET `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-inboxes/`

#### Parameters

| Parameter Name   | Required | Type    | Description                                                                                                                                                                                                                       |
| ---------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `groupPk`        | ✅        | string  |                                                                                                                                                                                                                                   |
| `organizationPk` | ✅        | string  | A UUID string identifying this organization 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  |                                                                                                                                                                                                                                   |

#### Code Examples

{% tabs %} {% tab title="Shell/Bash" %}

```bash
# Example API call (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"

# Make sure to replace YOUR_API_KEY and verify the request data before running.
```

```javascript
const axios = require('axios');

// Set request headers
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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", 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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

#### Response Content

**Status code: 200**

**Example Response Structure**

```typescript
{
  "count": integer
  "next"?: string (uri) // optional
  "previous"?: string (uri) // optional
  "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 // optional
      "canUpdate"?: boolean // optional
      "canDelete"?: boolean // optional
      "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. (optional)
      "createdAt": string (timestamp)
    }
  ]
}
```

**Example Response Values**

```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": "Example response string",
        "unreadConversationsCount": 456,
        "accessType": "Example response string"
      },
      "canRead": false,
      "canUpdate": false,
      "canDelete": false,
      "canViewConversations": false,
      "createdAt": "Example response string"
    }
  ]
}
```

***

### List Role Knowledge Bases <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/`

#### Parameters

| Parameter Name   | Required | Type    | Description                                    |
| ---------------- | -------- | ------- | ---------------------------------------------- |
| `groupPk`        | ✅        | string  |                                                |
| `organizationPk` | ✅        | string  | A UUID string identifying this organization ID |
| `page`           | ❌        | integer | A page number within the paginated result set. |
| `pageSize`       | ❌        | integer | Number of results to return per page.          |
| `query`          | ❌        | string  |                                                |
| `search`         | ❌        | string  |                                                |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# Example API call (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"

# Make sure to replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", 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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Content

**Status code: 200**

**Example Response Structure**

```typescript
{
  "count": integer
  "next"?: string (uri) // optional
  "previous"?: string (uri) // optional
  "results": [
    {
      "id": string (uuid)
      "group": string (uuid)
      "knowledgeBase": 
      {
        "id": string (uuid)
        "createdBy": 
        {
          "id": string (uuid)
          "name": string
        }
        "organization"?: string (uuid) // optional
        "embeddingModel": string (uuid)
        "rerankerModel": string (uuid)
        "name": string
        "description"?: string // optional
        "numberOfRetrievedChunks"?: integer // Number of retrieved reference chunks. Default is 12, minimum is 1 (optional)
        "enableHyde"?: boolean // Enable HyDE. Default is False (optional)
        "similarityCutoff"?: number (double) // Similarity threshold. Default is 0.0, range 0.0-1.0 (optional)
        "enableRerank"?: boolean // Whether to enable reranking. Default is True (optional)
        "enableRrf"?: boolean // Enable Reciprocal Rank Fusion for hybrid search. Disable this if using a custom Elasticsearch without enterprise license. (optional)
        "vectorDatabaseType"?:  // Type of vector database: elasticsearch or opensearch.

* `elasticsearch` - Elasticsearch
* `opensearch` - OpenSearch
* `oracle` - Oracle AI Database 26ai
* `synxdb` - SynxDB (optional)
        {
        }
        "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"). (optional)
        "vectorDatabaseApiKey"?: string // API Key for Elasticsearch. Not used for OpenSearch. (optional)
        "opensearchUsername"?: string // Username for OpenSearch Basic Auth. (optional)
        "opensearchPassword"?: string // Password for OpenSearch Basic Auth. (optional)
        "oracleUser"?: string // Oracle database username. (optional)
        "oraclePassword"?: string // Oracle database password. (optional)
        "synxdbUser"?: string // SynxDB database username. (optional)
        "synxdbPassword"?: string // SynxDB database password. (optional)
        "labels": [
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "chatbots"?: [ // optional
          {
            "id": string (uuid)
            "name": string
          }
        ]
        "groups"?: [ // List of groups that can access the knowledge base (optional)
          {
            "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 // optional
      "canUpdate"?: boolean // optional
      "canDelete"?: boolean // optional
      "createdAt": string (timestamp)
    }
  ]
}
```

**Example Response Values**

```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": "Example response string"
        },
        "organization": "550e8400-e29b-41d4-a716-446655440000",
        "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
        "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Example response string",
        "description": "Example response string",
        "numberOfRetrievedChunks": 456,
        "enableHyde": false,
        "similarityCutoff": 456,
        "enableRerank": false,
        "enableRrf": false,
        "vectorDatabaseType": {},
        "vectorDatabaseUrl": "Example response string",
        "vectorDatabaseApiKey": "Example response string",
        "opensearchUsername": "Example response string",
        "opensearchPassword": "Example response string",
        "oracleUser": "Example response string",
        "oraclePassword": "Example response string",
        "synxdbUser": "Example response string",
        "synxdbPassword": "Example response string",
        "labels": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Example response string"
          }
        ],
        "chatbots": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Example response string"
          }
        ],
        "groups": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Example response string"
          }
        ],
        "filesCount": 456,
        "vectorStorageSize": 456,
        "chunksCount": 456,
        "canUpdate": false,
        "canDelete": false,
        "createdAt": "Example response string",
        "updatedAt": "Example response string"
      },
      "canRead": false,
      "canUpdate": false,
      "canDelete": false,
      "createdAt": "Example response string"
    }
  ]
}
```

***

### List Role Databases <a href="#organizations-groups-group-databases-list" id="organizations-groups-group-databases-list"></a>

GET `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-databases/`

#### Parameters

| Parameter Name   | Required | Type    | Description                                    |
| ---------------- | -------- | ------- | ---------------------------------------------- |
| `groupPk`        | ✅        | string  |                                                |
| `organizationPk` | ✅        | string  | A UUID string identifying this organization ID |
| `page`           | ❌        | integer | A page number within the paginated result set. |
| `pageSize`       | ❌        | integer | Number of results to return per page.          |
| `query`          | ❌        | string  |                                                |
| `search`         | ❌        | string  |                                                |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# Example API call (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"

# Make sure to replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", 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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Content

**Status code: 200**

**Example Response Structure**

```typescript
{
  "count": integer
  "next"?: string (uri) // optional
  "previous"?: string (uri) // optional
  "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 (optional)
            "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) (optional)
                "description"?: string // Description of the column for better Text-to-SQL understanding (optional)
                "isPrimaryKey"?: boolean // optional
                "isNullable"?: boolean // optional
                "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 // optional
      "canUpdate"?: boolean // optional
      "canDelete"?: boolean // optional
      "createdAt": string (timestamp)
    }
  ]
}
```

**Example Response Values**

```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": "Example response string",
        "description": "Example response string",
        "databaseType": {},
        "includeTables": null,
        "isActive": false,
        "status": {},
        "deletedAt": "Example response string",
        "tables": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "tableName": "Example response string",
            "sheetName": "Example response string",
            "description": "Example response string",
            "status": {},
            "errorMessage": "Example response string",
            "sourceFile": {
              "id": "550e8400-e29b-41d4-a716-446655440000",
              "name": "Example response string",
              "isFromKnowledgeBase": false
            },
            "columns": [
              {
                "id": "550e8400-e29b-41d4-a716-446655440000",
                "columnName": "Example response string",
                "columnType": "Example response string",
                "description": "Example response string",
                "isPrimaryKey": false,
                "isNullable": false,
                "createdAt": "Example response string",
                "updatedAt": "Example response string"
              }
            ],
            "createdAt": "Example response string",
            "updatedAt": "Example response string"
          }
        ],
        "chatbots": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Example response string"
          }
        ],
        "groups": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Example response string"
          }
        ],
        "createdAt": "Example response string",
        "updatedAt": "Example response string"
      },
      "canRead": false,
      "canUpdate": false,
      "canDelete": false,
      "createdAt": "Example response string"
    }
  ]
}
```

***

### Update a Role <a href="#organizations-groups-update" id="organizations-groups-update"></a>

PUT `/api/v1/organizations/{organizationPk}/groups/{id}/`

#### Parameters

| Parameter Name   | Required | Type   | Description                                    |
| ---------------- | -------- | ------ | ---------------------------------------------- |
| `id`             | ✅        | string | A UUID string identifying this Group.          |
| `organizationPk` | ✅        | string | A UUID string identifying this Organization ID |

#### Request Body

**Request Parameters**

| Field                    | Type           | Required | Description                                                                                                                                                                                                 |
| ------------------------ | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                     | string         | Yes      |                                                                                                                                                                                                             |
| organization             | string (uuid)  | No       |                                                                                                                                                                                                             |
| permissions              | array\[string] | Yes      |                                                                                                                                                                                                             |
| canCreateChatbot         | boolean        | No       |                                                                                                                                                                                                             |
| canCreateKnowledgeBase   | boolean        | No       |                                                                                                                                                                                                             |
| canCreateInbox           | boolean        | No       |                                                                                                                                                                                                             |
| canCreateDatabase        | boolean        | No       |                                                                                                                                                                                                             |
| canCreateTool            | boolean        | No       |                                                                                                                                                                                                             |
| canCreateAgentUiTool     | boolean        | No       |                                                                                                                                                                                                             |
| canCreateSkill           | boolean        | No       |                                                                                                                                                                                                             |
| maigptCanCodeInterpreter | boolean        | No       | Whether members of this role may use the code interpreter built-in tool in MaiGPT.                                                                                                                          |
| maigptCanRag             | boolean        | No       | Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT.                                                                                                                        |
| maigptCanDeepResearch    | boolean        | No       | 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        | No       | Whether members of this role may use the browser built-in tool in MaiGPT.                                                                                                                                   |
| maigptAllLlms            | boolean        | No       | 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        | No       | 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        | No       | 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        | No       | 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         | No       | 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] | No       |                                                                                                                                                                                                             |
| allowedTools             | array\[string] | No       |                                                                                                                                                                                                             |
| allowedConnectors        | array\[string] | No       |                                                                                                                                                                                                             |
| allowedSkills            | array\[string] | No       |                                                                                                                                                                                                             |

**Request Schema Example**

```typescript
{
  "name": string
  "organization"?: string (uuid) // Optional
  "permissions": [
    string (uuid)
  ]
  "canCreateChatbot"?: boolean // Optional
  "canCreateKnowledgeBase"?: boolean // Optional
  "canCreateInbox"?: boolean // Optional
  "canCreateDatabase"?: boolean // Optional
  "canCreateTool"?: boolean // Optional
  "canCreateAgentUiTool"?: boolean // Optional
  "canCreateSkill"?: boolean // Optional
  "maigptCanCodeInterpreter"?: boolean // Whether members of this role may use the code interpreter built-in tool in MaiGPT. (Optional)
  "maigptCanRag"?: boolean // Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT. (Optional)
  "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. (Optional)
  "maigptCanBrowserTool"?: boolean // Whether members of this role may use the browser built-in tool in MaiGPT. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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 (Optional)
  {
  }
  "allowedLlms"?: [ // Optional
    string (uuid)
  ]
  "allowedTools"?: [ // Optional
    string (uuid)
  ]
  "allowedConnectors"?: [ // Optional
    string (uuid)
  ]
  "allowedSkills"?: [ // Optional
    string (uuid)
  ]
}
```

**Example Request Values**

```json
{
  "name": "Example 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,
  "maigptCanCodeInterpreter": true,
  "maigptCanRag": true,
  "maigptCanDeepResearch": true,
  "maigptCanBrowserTool": 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"
  ]
}
```

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# Example API call (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": "Example 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,
    "maigptCanCodeInterpreter": true,
    "maigptCanRag": true,
    "maigptCanDeepResearch": true,
    "maigptCanBrowserTool": 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"
    ]
  }'

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request Body (payload)
const data = {
    "name": "Example 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,
    "maigptCanCodeInterpreter": true,
    "maigptCanRag": true,
    "maigptCanDeepResearch": true,
    "maigptCanBrowserTool": 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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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"
}

# Request Body (payload)
data = {
    "name": "Example 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,
    "maigptCanCodeInterpreter": True,
    "maigptCanRag": True,
    "maigptCanDeepResearch": True,
    "maigptCanBrowserTool": 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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", 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' => 'Example 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,
            'maigptCanCodeInterpreter' => true,
            'maigptCanRag' => true,
            'maigptCanDeepResearch' => true,
            'maigptCanBrowserTool' => 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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

**Status Code: 200**

**Response Schema Example**

```typescript
{
  "id": string (uuid)
  "name": string
  "type": 
  {
  }
  "permissions": [
    object
  ]
  "membersPreview": [
    string
  ]
  "membersCount": integer // Returns the number of remaining members (after subtracting the 3 shown in the list), for the frontend +N badge

Unlike resource counts:
- members_count: Returns total - 3 (for the +N badge); None indicates a total <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: Returns the total count
  "chatbotsCount": integer
  "chatbotsPreview": [
    string
  ]
  "knowledgeBasesCount": integer
  "knowledgeBasesPreview": [
    string
  ]
  "inboxesCount": integer
  "inboxesPreview": [
    string
  ]
  "databasesCount": integer
  "databasesPreview": [
    string
  ]
  "canCreateChatbot"?: boolean // Optional
  "canCreateKnowledgeBase"?: boolean // Optional
  "canCreateInbox"?: boolean // Optional
  "canCreateDatabase"?: boolean // Optional
  "canCreateTool"?: boolean // Optional
  "canCreateAgentUiTool"?: boolean // Optional
  "canCreateSkill"?: boolean // Optional
  "maigptCanCodeInterpreter"?: boolean // Whether members of this role may use the code interpreter built-in tool in MaiGPT. (Optional)
  "maigptCanRag"?: boolean // Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT. (Optional)
  "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. (Optional)
  "maigptCanBrowserTool"?: boolean // Whether members of this role may use the browser built-in tool in MaiGPT. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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 (Optional)
  {
  }
  "createdAt": string (timestamp)
}
```

**Example Response Values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "type": {},
  "permissions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Example response name",
      "description": "Example response description"
    }
  ],
  "membersPreview": [
    "Response string"
  ],
  "membersCount": 456,
  "chatbotsCount": 456,
  "chatbotsPreview": [
    "Response string"
  ],
  "knowledgeBasesCount": 456,
  "knowledgeBasesPreview": [
    "Response string"
  ],
  "inboxesCount": 456,
  "inboxesPreview": [
    "Response string"
  ],
  "databasesCount": 456,
  "databasesPreview": [
    "Response string"
  ],
  "canCreateChatbot": false,
  "canCreateKnowledgeBase": false,
  "canCreateInbox": false,
  "canCreateDatabase": false,
  "canCreateTool": false,
  "canCreateAgentUiTool": false,
  "canCreateSkill": false,
  "maigptCanCodeInterpreter": false,
  "maigptCanRag": false,
  "maigptCanDeepResearch": false,
  "maigptCanBrowserTool": false,
  "maigptAllLlms": false,
  "maigptAllTools": false,
  "maigptAllConnectors": false,
  "maigptAllSkills": false,
  "usageStatisticsScope": {},
  "createdAt": "Response string"
}
```

***

### Partially Update a Role <a href="#organizations-groups-partial-update" id="organizations-groups-partial-update"></a>

PATCH `/api/v1/organizations/{organizationPk}/groups/{id}/`

#### Parameters

| Parameter Name   | Required | Type   | Description                                    |
| ---------------- | -------- | ------ | ---------------------------------------------- |
| `id`             | ✅        | string | A UUID string identifying this Group.          |
| `organizationPk` | ✅        | string | A UUID string identifying this Organization ID |

#### Request Body

**Request Parameters**

| Field                    | Type           | Required | Description                                                                                                                                                                                                 |
| ------------------------ | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name                     | string         | No       |                                                                                                                                                                                                             |
| organization             | string (uuid)  | No       |                                                                                                                                                                                                             |
| permissions              | array\[string] | No       |                                                                                                                                                                                                             |
| canCreateChatbot         | boolean        | No       |                                                                                                                                                                                                             |
| canCreateKnowledgeBase   | boolean        | No       |                                                                                                                                                                                                             |
| canCreateInbox           | boolean        | No       |                                                                                                                                                                                                             |
| canCreateDatabase        | boolean        | No       |                                                                                                                                                                                                             |
| canCreateTool            | boolean        | No       |                                                                                                                                                                                                             |
| canCreateAgentUiTool     | boolean        | No       |                                                                                                                                                                                                             |
| canCreateSkill           | boolean        | No       |                                                                                                                                                                                                             |
| maigptCanCodeInterpreter | boolean        | No       | Whether members of this role may use the code interpreter built-in tool in MaiGPT.                                                                                                                          |
| maigptCanRag             | boolean        | No       | Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT.                                                                                                                        |
| maigptCanDeepResearch    | boolean        | No       | 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        | No       | Whether members of this role may use the browser built-in tool in MaiGPT.                                                                                                                                   |
| maigptAllLlms            | boolean        | No       | 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        | No       | 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        | No       | 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        | No       | 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         | No       | 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] | No       |                                                                                                                                                                                                             |
| allowedTools             | array\[string] | No       |                                                                                                                                                                                                             |
| allowedConnectors        | array\[string] | No       |                                                                                                                                                                                                             |
| allowedSkills            | array\[string] | No       |                                                                                                                                                                                                             |

**Request Schema Example**

```typescript
{
  "name"?: string // Optional
  "organization"?: string (uuid) // Optional
  "permissions"?: [ // Optional
    string (uuid)
  ]
  "canCreateChatbot"?: boolean // Optional
  "canCreateKnowledgeBase"?: boolean // Optional
  "canCreateInbox"?: boolean // Optional
  "canCreateDatabase"?: boolean // Optional
  "canCreateTool"?: boolean // Optional
  "canCreateAgentUiTool"?: boolean // Optional
  "canCreateSkill"?: boolean // Optional
  "maigptCanCodeInterpreter"?: boolean // Whether members of this role may use the code interpreter built-in tool in MaiGPT. (Optional)
  "maigptCanRag"?: boolean // Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT. (Optional)
  "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. (Optional)
  "maigptCanBrowserTool"?: boolean // Whether members of this role may use the browser built-in tool in MaiGPT. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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 (Optional)
  {
  }
  "allowedLlms"?: [ // Optional
    string (uuid)
  ]
  "allowedTools"?: [ // Optional
    string (uuid)
  ]
  "allowedConnectors"?: [ // Optional
    string (uuid)
  ]
  "allowedSkills"?: [ // Optional
    string (uuid)
  ]
}
```

**Example Request Values**

```json
{
  "name": "Example 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,
  "maigptCanCodeInterpreter": true,
  "maigptCanRag": true,
  "maigptCanDeepResearch": true,
  "maigptCanBrowserTool": 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"
  ]
}
```

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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": "Example 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,
    "maigptCanCodeInterpreter": true,
    "maigptCanRag": true,
    "maigptCanDeepResearch": true,
    "maigptCanBrowserTool": 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"
    ]
  }'

# Make sure to replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request Body (payload)
const data = {
    "name": "Example 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,
    "maigptCanCodeInterpreter": true,
    "maigptCanRag": true,
    "maigptCanDeepResearch": true,
    "maigptCanBrowserTool": 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('Successfully retrieved the response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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"
}

# Request Body (payload)
data = {
    "name": "Example 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,
    "maigptCanCodeInterpreter": True,
    "maigptCanRag": True,
    "maigptCanDeepResearch": True,
    "maigptCanBrowserTool": 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("Successfully retrieved the response:")
    print(response.json())
except Exception as e:
    print("Request error:", 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' => 'Example 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,
            'maigptCanCodeInterpreter' => true,
            'maigptCanRag' => true,
            'maigptCanDeepResearch' => true,
            'maigptCanBrowserTool' => 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 "Successfully retrieved the response:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

**Status Code: 200**

**Response Schema Example**

```typescript
{
  "id": string (uuid)
  "name": string
  "type": 
  {
  }
  "permissions": [
    object
  ]
  "membersPreview": [
    string
  ]
  "membersCount": integer // Returns the remaining member count (after deducting the 3 shown in the list), used for the frontend +N badge display

Unlike the resource counts:
- members_count: returns total - 3 (used for the +N badge); None means the total is <= 3
- chatbots_count/knowledge_bases_count/inboxes_count: returns the total count
  "chatbotsCount": integer
  "chatbotsPreview": [
    string
  ]
  "knowledgeBasesCount": integer
  "knowledgeBasesPreview": [
    string
  ]
  "inboxesCount": integer
  "inboxesPreview": [
    string
  ]
  "databasesCount": integer
  "databasesPreview": [
    string
  ]
  "canCreateChatbot"?: boolean // Optional
  "canCreateKnowledgeBase"?: boolean // Optional
  "canCreateInbox"?: boolean // Optional
  "canCreateDatabase"?: boolean // Optional
  "canCreateTool"?: boolean // Optional
  "canCreateAgentUiTool"?: boolean // Optional
  "canCreateSkill"?: boolean // Optional
  "maigptCanCodeInterpreter"?: boolean // Whether members of this role may use the code interpreter built-in tool in MaiGPT. (Optional)
  "maigptCanRag"?: boolean // Whether members of this role may use the knowledge base RAG built-in tool in MaiGPT. (Optional)
  "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. (Optional)
  "maigptCanBrowserTool"?: boolean // Whether members of this role may use the browser built-in tool in MaiGPT. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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. (Optional)
  "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 (Optional)
  {
  }
  "createdAt": string (timestamp)
}
```

**Example Response Values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Response string",
  "type": {},
  "permissions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Response example name",
      "description": "Response example description"
    }
  ],
  "membersPreview": [
    "Response string"
  ],
  "membersCount": 456,
  "chatbotsCount": 456,
  "chatbotsPreview": [
    "Response string"
  ],
  "knowledgeBasesCount": 456,
  "knowledgeBasesPreview": [
    "Response string"
  ],
  "inboxesCount": 456,
  "inboxesPreview": [
    "Response string"
  ],
  "databasesCount": 456,
  "databasesPreview": [
    "Response string"
  ],
  "canCreateChatbot": false,
  "canCreateKnowledgeBase": false,
  "canCreateInbox": false,
  "canCreateDatabase": false,
  "canCreateTool": false,
  "canCreateAgentUiTool": false,
  "canCreateSkill": false,
  "maigptCanCodeInterpreter": false,
  "maigptCanRag": false,
  "maigptCanDeepResearch": false,
  "maigptCanBrowserTool": false,
  "maigptAllLlms": false,
  "maigptAllTools": false,
  "maigptAllConnectors": false,
  "maigptAllSkills": false,
  "usageStatisticsScope": {},
  "createdAt": "Response string"
}
```

***

### Delete Role <a href="#organizations-groups-destroy" id="organizations-groups-destroy"></a>

DELETE `/api/v1/organizations/{organizationPk}/groups/{id}/`

#### Parameters

| Parameter        | Required | Type   | Description                                    |
| ---------------- | -------- | ------ | ---------------------------------------------- |
| `id`             | ✅        | string | A UUID string identifying this Group.          |
| `organizationPk` | ✅        | string | A UUID string identifying this Organization ID |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# Example API call (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"

# Make sure to replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// Request 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('Successfully received response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Successfully received response:")
    print(response.json())
except Exception as e:
    print("Request error:", 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 "Successfully received response:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

| Status Code | Description      |
| ----------- | ---------------- |
| 204         | No response body |

***

### Remove Role Member <a href="#organizations-groups-group-members-destroy" id="organizations-groups-group-members-destroy"></a>

DELETE `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-members/{id}/`

#### Parameters

| Parameter        | Required | Type   | Description                                    |
| ---------------- | -------- | ------ | ---------------------------------------------- |
| `groupPk`        | ✅        | string |                                                |
| `id`             | ✅        | string | A UUID string identifying this Group Member.   |
| `organizationPk` | ✅        | string | A UUID string identifying this Organization ID |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# Example API call (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"

# Make sure to replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// Request 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('Successfully received response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Successfully received response:")
    print(response.json())
except Exception as e:
    print("Request error:", 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 "Successfully received response:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

| Status Code | Description      |
| ----------- | ---------------- |
| 204         | No response body |

***

### Remove AI Assistant from Role <a href="#organizations-groups-group-chatbots-destroy" id="organizations-groups-group-chatbots-destroy"></a>

DELETE `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-chatbots/{id}/`

#### Parameters

| Parameter        | Required | Type   | Description                                    |
| ---------------- | -------- | ------ | ---------------------------------------------- |
| `groupPk`        | ✅        | string |                                                |
| `id`             | ✅        | string | A UUID string identifying this Group Chatbot.  |
| `organizationPk` | ✅        | string | A UUID string identifying this Organization ID |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# Example API call (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"

# Make sure to replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// Request 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('Successfully received response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Successfully received response:")
    print(response.json())
except Exception as e:
    print("Request error:", 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 "Successfully received response:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

| Status Code | Description      |
| ----------- | ---------------- |
| 204         | No response body |

***

### Remove Inbox from Role <a href="#organizations-groups-group-inboxes-destroy" id="organizations-groups-group-inboxes-destroy"></a>

DELETE `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-inboxes/{id}/`

#### Parameters

| Parameter        | Required | Type   | Description                                    |
| ---------------- | -------- | ------ | ---------------------------------------------- |
| `groupPk`        | ✅        | string |                                                |
| `id`             | ✅        | string | A UUID string identifying this Group Inbox.    |
| `organizationPk` | ✅        | string | A UUID string identifying this Organization ID |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# Example API call (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"

# Make sure to replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// Request 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('Successfully received response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request 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("Successfully received response:")
    print(response.json())
except Exception as e:
    print("Request error:", 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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

| Status Code | Description      |
| ----------- | ---------------- |
| 204         | No response body |

***

### Remove Knowledge Base from Role <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}/`

#### Parameters

| Parameter Name   | Required | Type   | Description                                         |
| ---------------- | -------- | ------ | --------------------------------------------------- |
| `groupPk`        | ✅        | string |                                                     |
| `id`             | ✅        | string | A UUID string identifying this Group KnowledgeBase. |
| `organizationPk` | ✅        | string | A UUID string identifying this Organization ID      |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// Request Body (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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred during the request:');
    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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", 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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

| Status Code | Description      |
| ----------- | ---------------- |
| 204         | No response body |

***

### Remove Database from Role <a href="#organizations-groups-group-databases-destroy" id="organizations-groups-group-databases-destroy"></a>

DELETE `/api/v1/organizations/{organizationPk}/groups/{groupPk}/group-databases/{id}/`

#### Parameters

| Parameter Name   | Required | Type   | Description                                    |
| ---------------- | -------- | ------ | ---------------------------------------------- |
| `groupPk`        | ✅        | string |                                                |
| `id`             | ✅        | string | A UUID string identifying this Group Database. |
| `organizationPk` | ✅        | string | A UUID string identifying this Organization ID |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (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"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// Request Body (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('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred during the request:');
    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("Response received successfully:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", 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 "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

| Status Code | Description      |
| ----------- | ---------------- |
| 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/en/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.