> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/open-webui/open-webui/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Groups

Group management endpoints for creating, updating, and managing user groups.

## List Groups

<CodeGroup>
  ```bash GET /api/groups theme={null}
  curl -X GET "https://your-domain.com/api/groups" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</CodeGroup>

Retrieves all groups accessible to the authenticated user.

### Query Parameters

<ParamField query="share" type="boolean" optional>
  Filter by share permission. For non-admin users, filters groups based on membership and share settings.
</ParamField>

### Response

<ResponseField name="groups" type="array">
  Array of group objects

  <Expandable title="Group Object">
    <ResponseField name="id" type="string">
      Unique group identifier
    </ResponseField>

    <ResponseField name="user_id" type="string">
      ID of user who created the group
    </ResponseField>

    <ResponseField name="name" type="string">
      Group name
    </ResponseField>

    <ResponseField name="description" type="string">
      Group description
    </ResponseField>

    <ResponseField name="data" type="object" optional>
      Additional group data including configuration

      <Expandable title="Data Object">
        <ResponseField name="config" type="object">
          Configuration settings

          <ResponseField name="share" type="string">
            Share permission: `true`, `false`, or `members`
          </ResponseField>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="meta" type="object" optional>
      Metadata about the group
    </ResponseField>

    <ResponseField name="permissions" type="object" optional>
      Group-specific permissions
    </ResponseField>

    <ResponseField name="member_count" type="integer">
      Number of members in the group
    </ResponseField>

    <ResponseField name="created_at" type="integer">
      Unix timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="integer">
      Unix timestamp of last update
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Create Group

<CodeGroup>
  ```bash POST /api/groups/create theme={null}
  curl -X POST "https://your-domain.com/api/groups/create" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Engineering Team",
      "description": "Engineering department group",
      "permissions": {},
      "data": {
        "config": {
          "share": "members"
        }
      }
    }'
  ```
</CodeGroup>

Creates a new group. Requires admin authentication.

### Request Body

<ParamField body="name" type="string" required>
  Group name
</ParamField>

<ParamField body="description" type="string" required>
  Group description
</ParamField>

<ParamField body="permissions" type="object" optional>
  Group-specific permissions
</ParamField>

<ParamField body="data" type="object" optional>
  Additional group data. If not provided, default share configuration is applied.
</ParamField>

***

## Get Group

<CodeGroup>
  ```bash GET /api/groups/id/{id} theme={null}
  curl -X GET "https://your-domain.com/api/groups/id/group-123" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</CodeGroup>

Retrieves detailed information about a specific group. Requires admin authentication.

### Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the group
</ParamField>

***

## Update Group

<CodeGroup>
  ```bash POST /api/groups/id/{id}/update theme={null}
  curl -X POST "https://your-domain.com/api/groups/id/group-123/update" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Updated Group Name",
      "description": "Updated description",
      "permissions": {}
    }'
  ```
</CodeGroup>

Updates group information. Requires admin authentication.

### Request Body

<ParamField body="name" type="string" required>
  Updated group name
</ParamField>

<ParamField body="description" type="string" required>
  Updated group description
</ParamField>

<ParamField body="permissions" type="object" optional>
  Updated permissions
</ParamField>

<ParamField body="data" type="object" optional>
  Updated group data
</ParamField>

***

## Add Users to Group

<CodeGroup>
  ```bash POST /api/groups/id/{id}/users/add theme={null}
  curl -X POST "https://your-domain.com/api/groups/id/group-123/users/add" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "user_ids": ["user-1", "user-2", "user-3"]
    }'
  ```
</CodeGroup>

Adds users to a group. Requires admin authentication.

### Request Body

<ParamField body="user_ids" type="array" optional>
  Array of user IDs to add to the group. Invalid user IDs are automatically filtered out.
</ParamField>

***

## Remove Users from Group

<CodeGroup>
  ```bash POST /api/groups/id/{id}/users/remove theme={null}
  curl -X POST "https://your-domain.com/api/groups/id/group-123/users/remove" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "user_ids": ["user-1", "user-2"]
    }'
  ```
</CodeGroup>

Removes users from a group. Requires admin authentication.

### Request Body

<ParamField body="user_ids" type="array" optional>
  Array of user IDs to remove from the group
</ParamField>

***

## Get Group Users

<CodeGroup>
  ```bash POST /api/groups/id/{id}/users theme={null}
  curl -X POST "https://your-domain.com/api/groups/id/group-123/users" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</CodeGroup>

Retrieves all users in a specific group. Requires admin authentication.

### Response

Returns an array of user objects with basic information:

```json theme={null}
[
  {
    "id": "user-123",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "user",
    "bio": "Software developer",
    "groups": [],
    "is_active": true
  }
]
```

***

## Export Group

<CodeGroup>
  ```bash GET /api/groups/id/{id}/export theme={null}
  curl -X GET "https://your-domain.com/api/groups/id/group-123/export" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</CodeGroup>

Exports complete group information including all user IDs. Requires admin authentication.

### Response

Returns group object with additional `user_ids` field:

<ResponseField name="user_ids" type="array">
  Array of all user IDs in the group
</ResponseField>

***

## Delete Group

<CodeGroup>
  ```bash DELETE /api/groups/id/{id}/delete theme={null}
  curl -X DELETE "https://your-domain.com/api/groups/id/group-123/delete" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</CodeGroup>

Deletes a group and all member associations. Requires admin authentication.

### Response

Returns `true` if successful, error otherwise.

***

## Notes

* Admin users can access all groups regardless of membership
* Non-admin users can only see groups they are members of (unless group share is set to `true`)
* Group share settings:
  * `true` or `"true"`: Anyone can share to this group
  * `false` or `"false"`: Nobody can share to this group
  * `"members"`: Only group members can share to this group
* Adding duplicate users to a group is silently ignored
* Invalid user IDs are automatically filtered when adding users
* All group operations update the `updated_at` timestamp