# Groups

API endpoints for managing groups within the Wellesley platform. Groups are community spaces that can be public or private, support forums, and have their own membership and permission systems. Groups can be federated via ActivityPub for cross-instance communication.

## Create a new group

 - [POST /api/v1/groups](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups/post.md): Creates a new group owned by the currently authenticated user. The user becomes the group owner with full administrative privileges. The group name must be unique across the platform. A default channel is automatically created for the group.

## Get all user's groups with comprehensive sorting

 - [GET /api/v1/groups/my-groups](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups~1my-groups/get.md): Returns user's groups in order:
            1) pinned by pin number,
            2) owned unpinned by creation date,
            3) member unpinned by creation date.
            Each group includes viewer context: isMember (always true), pin (if pinned), and canManage.

## Get group by name

 - [GET /api/v1/groups/name/{groupname}](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups~1name~1%7Bgroupname%7D/get.md): Retrieves a group using its unique name (slug). The group name is case-insensitive and must follow username validation rules (alphanumeric, underscores, hyphens). This endpoint is publicly accessible (@PermitAll) and is useful for human-readable URLs. Stats visibility is controlled by group settings.

## Search groups by name

 - [GET /api/v1/groups/search](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups~1search/get.md): Searches for groups whose names contain the specified substring. The search is case-insensitive. If no substring is provided or it's empty, returns all visible groups. Results respect visibility and membership: returns VISIBLE groups (public or private) and any groups the user is a member of if UNLISTED (HIDDEN groups never appear in search or listings). This endpoint is publicly accessible (@PermitAll). Results are paginated.

## Get mutual groups with another user

 - [GET /api/v1/groups/users/{userId}/mutual](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups~1users~1%7Buserid%7D~1mutual/get.md): Retrieves groups that both the current user and the specified user are members of. Only returns groups where both users have active memberships (MEMBER status). Useful for finding common communities and shared interests between users.

## Update group information

 - [PUT /api/v1/groups/{groupId}](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups~1%7Bgroupid%7D/put.md): Updates the group's basic information including name, display name, description, and privacy settings. Requires GroupData.Manage permission. The group owner and administrators can perform this operation. Changes to privacy settings may affect member access and visibility.

RBAC: requires GroupData.Manage

## Get group by ID

 - [GET /api/v1/groups/{groupId}](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups~1%7Bgroupid%7D/get.md): Retrieves detailed information about a specific group including metadata, settings, and upload references. Accessible for public groups without membership. Hidden groups return 404 for non-members to maintain privacy. Includes real-time statistics. Stats visibility is controlled by group settings.

## Delete a group

 - [DELETE /api/v1/groups/{groupId}](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups~1%7Bgroupid%7D/delete.md): Permanently deletes a group and all associated data including memberships, roles, and channel content. This operation is irreversible. Requires the Group.Delete RBAC permission (typically group owner). The deletion is federated via ActivityPub to notify remote instances.

RBAC: requires Group.Delete

## Update group branding

 - [PUT /api/v1/groups/{groupId}/branding](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1branding/put.md): Updates the visual branding elements of a group including color theme, banner image, and avatar. Color must be in HEX format. Banner and avatar are references to previously uploaded media. Setting banner or avatar to null removes them. Requires the GroupSettings.Manage RBAC permission (group admin).

RBAC: requires GroupSettings.Manage

## Get group details with membership info

 - [GET /api/v1/groups/{groupId}/details](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1details/get.md): Retrieves group details combined with the viewer's membership information.
            For remote (federated) groups, refreshes data from the remote server if stale.

            The response includes:
            - Full group information (same as GET /groups/{groupId})
            - Viewer's membership state (MEMBER, PENDING_JOIN, PENDING_INVITE, or NONE)
            - Related objects (membership details, join request, or pending invite)

            This endpoint is useful for displaying group pages where the viewer's
            relationship to the group is relevant, such as showing Accept/Reject
            buttons for pending invites.

## Get group feed

 - [GET /api/v1/groups/{groupId}/feed](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1feed/get.md): Returns a merged feed of posts across channels in the group. Members with channel subscriptions see posts from subscribed channels only. Non-members or members without subscriptions see posts from all public channels. Use allChannels=true to bypass subscription gating and show all accessible channels. Post visibility otherwise follows the standard post privacy rules.