# 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 forum is automatically created for the group with default categories.

## 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

## 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 is useful for human-readable URLs.

## Check if group name is already in use

 - [GET /api/v1/groups/namecheck/{groupname}](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups~1namecheck~1%7Bgroupname%7D/get.md): Used for inline validation during group creation. Checks all local groups regardless of privacy settings. Returns a result object indicating whether the username is taken. Publicly accessible to allow group name validation during signup.

## Get user's pinned groups

 - [GET /api/v1/groups/pinned](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups~1pinned/get.md): Retrieve all groups pinned by the current user, ordered by pin number

## 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 settings - only returns if group is public && visible or user is a member. 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. Returns full group data including metadata, settings, and upload references. Hidden groups return 404 for non-members to maintain privacy.

## 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 forum content. This operation is irreversible.

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 group ownership or admin privileges.

RBAC: requires GroupSettings.Manage

## Join a group

 - [POST /api/v1/groups/{groupId}/join](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1join/post.md): Request to join a group. The behavior depends on the group's join mode:
            OPEN groups accept members immediately with MEMBER role, APPROVAL groups create a PENDING membership
            requiring admin approval, and INVITE_ONLY groups require an invitation. Groups may also have
            entry questions that require a valid answerToken from completing the group's questionnaire.
            Users cannot join a group they're already a member of.

## Cancel group join request

 - [DELETE /api/v1/groups/{groupId}/join](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1join/delete.md): Cancel a join request for a group. This allows users to withdraw their request
            to join a group that requires approval. Only the user who made
            the original join request can cancel it.

## List join requests for a group

 - [GET /api/v1/groups/{groupId}/join-requests](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1join-requests/get.md): Get a list of join requests for a group with optional filtering by status, username, and date range.
            Only group admins can access this endpoint

RBAC: requires GroupMembers.Manage

## Reject a join request

 - [DELETE /api/v1/groups/{groupId}/join-requests/{groupJoinRequestId}](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1join-requests~1%7Bgroupjoinrequestid%7D/delete.md): Reject a user's join request for a group. This removes the request
            without creating a membership. Only group admins can reject join requests.

RBAC: requires GroupMembers.Manage

## Approve a join request

 - [PUT /api/v1/groups/{groupId}/join-requests/{groupJoinRequestId}](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1join-requests~1%7Bgroupjoinrequestid%7D/put.md): Approve a join request for a group. This converts the request
            into an active group membership with MEMBER role. Only group admins can approve join requests.

RBAC: requires GroupMembers.Manage

## Unpin a group

 - [DELETE /api/v1/groups/{groupId}/pin](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1pin/delete.md): Remove pin from a group. User must be a member of the group.

## Pin a group

 - [PUT /api/v1/groups/{groupId}/pin](https://docs.wellesley.social/openapi/groups/paths/~1api~1v1~1groups~1%7Bgroupid%7D~1pin/put.md): Pin a group with optional pin number. User must be a member of the group