Groups API

Group management endpoints

19 endpoints.

Method	Path	Summary
`GET`	`/api/communities/{communityId}/groups`	List all groups in a community
`POST`	`/api/communities/{communityId}/groups`	Create a new group (Moderator+ only)
`DELETE`	`/api/communities/{communityId}/groups/{groupId}`	Delete a group (Moderator+ only)
`GET`	`/api/communities/{communityId}/groups/{groupId}`	Get a single group by ID
`PUT`	`/api/communities/{communityId}/groups/{groupId}`	Update a group (Moderator+ only)
`PATCH`	`/api/communities/{communityId}/groups/{groupId}/hide`	Hide a group (Moderator+ only)
`POST`	`/api/communities/{communityId}/groups/{groupId}/join`	Join a group
`GET`	`/api/communities/{communityId}/groups/{groupId}/join-requests`	Get all join requests for a group (Admin/Moderator only)
`POST`	`/api/communities/{communityId}/groups/{groupId}/join-requests`	Request to join a private group
`DELETE`	`/api/communities/{communityId}/groups/{groupId}/join-requests/{requestId}`	Cancel a join request (by the requester)
`PATCH`	`/api/communities/{communityId}/groups/{groupId}/join-requests/{requestId}/approve`	Approve a join request (Admin/Moderator only)
`PATCH`	`/api/communities/{communityId}/groups/{groupId}/join-requests/{requestId}/reject`	Reject a join request (Admin/Moderator only)
`GET`	`/api/communities/{communityId}/groups/{groupId}/join-requests/my-status`	Get current user's join request status for a group
`POST`	`/api/communities/{communityId}/groups/{groupId}/leave`	Leave a group
`GET`	`/api/communities/{communityId}/groups/{groupId}/members`	Get all members of a group
`GET`	`/api/communities/{communityId}/groups/{groupId}/membership-status`	Check membership status for current user in a group
`PATCH`	`/api/communities/{communityId}/groups/{groupId}/unhide`	Unhide a group (Moderator+ only)
`GET`	`/api/communities/{communityId}/groups/join-requests`	Community-wide aggregate of group join requests (Moderator+ only)
`GET`	`/api/communities/{communityId}/groups/member/{userId}`	Groups a given member belongs to, filtered to what the viewer may see

List all groups in a community

GET /api/communities/{communityId}/groups

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	Community ID
`page`	query	no	integer	Page number
`limit`	query	no	integer	Items per page
`type`	query	no	enum: `PRIVATE`, `PUBLIC`	Filter by group type
`search`	query	no	string	Search in group names
`hasSpace`	query	no	boolean	Filter groups with available space

Responses

Status	Description	Body
`200`	List of groups with pagination	object
`400`	Invalid request parameters	—
`401`	Authentication required	—
`404`	Community not found	—

Create a new group (Moderator+ only)

POST /api/communities/{communityId}/groups

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—

Request body (required) — multipart/form-data

Field	Type	Required	Description
`nameArabic`	string	yes	Group name in Arabic
`name`	string	yes	Group name in English
`descriptionArabic`	string	yes	Group description in Arabic
`description`	string	yes	Group description in English
`type`	enum: `PRIVATE`, `PUBLIC`	yes	Group privacy type
`memberCount`	integer	yes	Member limit (-1 for unlimited, positive number for limit)
`canChat`	boolean	yes	Enable chat functionality
`email`	string (email)	no	Optional group email
`website`	string (uri)	no	Optional group website
`icon`	string (binary)	yes	Group icon (required, max 2MB, image types only)
`coverImage`	string (binary)	no	Group cover image (optional, max 5MB, image types only)

Responses

Status	Description	Body
`201`	Group created successfully	object
`400`	Invalid request or validation error	—
`401`	Authentication required	—
`403`	Insufficient permissions (Moderator+ required)	—
`404`	Community not found	—

Delete a group (Moderator+ only)

DELETE /api/communities/{communityId}/groups/{groupId}

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`groupId`	path	yes	string (uuid)	—

Responses

Status	Description	Body
`200`	Group deleted successfully	—
`401`	Authentication required	—
`403`	Insufficient permissions (Moderator+ required)	—
`404`	Group not found	—

Get a single group by ID

GET /api/communities/{communityId}/groups/{groupId}

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`groupId`	path	yes	string (uuid)	—

Responses

Status	Description	Body
`200`	Group details	object
`401`	Authentication required	—
`404`	Group not found	—

Update a group (Moderator+ only)

PUT /api/communities/{communityId}/groups/{groupId}

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`groupId`	path	yes	string (uuid)	—

Request body (required) — multipart/form-data

Field	Type	Required	Description
`nameArabic`	string	no	—
`name`	string	no	—
`descriptionArabic`	string	no	—
`description`	string	no	—
`type`	enum: `PRIVATE`, `PUBLIC`	no	—
`memberCount`	integer	no	—
`canChat`	boolean	no	—
`email`	string (email)	no	—
`website`	string (uri)	no	—
`icon`	string (binary)	no	New group icon (optional, max 2MB)
`coverImage`	string (binary)	no	New group cover image (optional, max 5MB)
`removeCoverImage`	boolean	no	Clear the current cover image. Ignored when a coverImage file is uploaded in the same request. There is no equivalent for the icon, which is required.

Responses

Status	Description	Body
`200`	Group updated successfully	—
`400`	Invalid request or validation error	—
`401`	Authentication required	—
`403`	Needs groups:manage or groups:moderate (groups:create does NOT edit groups), RESTRICTION_BLOCKED, or storage quota exceeded	—
`404`	Group not found	—

Hide a group (Moderator+ only)

PATCH /api/communities/{communityId}/groups/{groupId}/hide

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`groupId`	path	yes	string (uuid)	—

Responses

Status	Description	Body
`200`	Group hidden successfully	object
`400`	Group is already hidden	—
`401`	Authentication required	—
`403`	Insufficient permissions (Moderator+ required)	—
`404`	Group not found	—

Join a group

POST /api/communities/{communityId}/groups/{groupId}/join

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`groupId`	path	yes	string (uuid)	—

Responses

Status	Description	Body
`200`	Successfully joined group	—
`403`	User is restricted from joining groups	—

Get all join requests for a group (Admin/Moderator only)

GET /api/communities/{communityId}/groups/{groupId}/join-requests

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`groupId`	path	yes	string (uuid)	—
`page`	query	no	integer	—
`limit`	query	no	integer	—
`status`	query	no	enum: `PENDING`, `APPROVED`, `REJECTED`, `CANCELLED`	—

Responses

Status	Description	Body
`200`	Paginated list of join requests	—
`403`	Permission denied	—

Request to join a private group

POST /api/communities/{communityId}/groups/{groupId}/join-requests

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`groupId`	path	yes	string (uuid)	—

Request body — application/json

Field	Type	Required	Description
`message`	string	no	Optional message to group admins

Responses

Status	Description	Body
`201`	Join request submitted successfully	—
`403`	User is restricted from joining groups	—

Cancel a join request (by the requester)

DELETE /api/communities/{communityId}/groups/{groupId}/join-requests/{requestId}

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`groupId`	path	yes	string (uuid)	—
`requestId`	path	yes	string (uuid)	—

Responses

Status	Description	Body
`200`	Join request cancelled successfully	—
`403`	Not authorized to cancel this request	—
`404`	Join request not found	—

Approve a join request (Admin/Moderator only)

PATCH /api/communities/{communityId}/groups/{groupId}/join-requests/{requestId}/approve

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`groupId`	path	yes	string (uuid)	—
`requestId`	path	yes	string (uuid)	—

Responses

Status	Description	Body
`200`	Join request approved and user added to group	—
`403`	Permission denied	—
`404`	Join request not found	—
`409`	JOIN_REQUEST_NOT_PENDING — already decided (including by a reviewer acting at the same moment)	—

Reject a join request (Admin/Moderator only)

PATCH /api/communities/{communityId}/groups/{groupId}/join-requests/{requestId}/reject

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`groupId`	path	yes	string (uuid)	—
`requestId`	path	yes	string (uuid)	—

Request body — application/json

Field	Type	Required	Description
`reason`	string	no	Optional rejection reason

Responses

Status	Description	Body
`200`	Join request rejected	—
`403`	Permission denied	—
`404`	Join request not found	—
`409`	JOIN_REQUEST_NOT_PENDING — already decided (including by a reviewer acting at the same moment)	—

Get current user's join request status for a group

GET /api/communities/{communityId}/groups/{groupId}/join-requests/my-status

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`groupId`	path	yes	string (uuid)	—

Responses

Status	Description	Body
`200`	User's join request status	—
`404`	No join request found	—

Leave a group

POST /api/communities/{communityId}/groups/{groupId}/leave

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`groupId`	path	yes	string (uuid)	—

Responses

Status	Description	Body
`200`	Successfully left group	—
`400`	Cannot leave (e.g., sole admin)	—
`403`	User is restricted from leaving groups	—

Get all members of a group

GET /api/communities/{communityId}/groups/{groupId}/members

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`groupId`	path	yes	string (uuid)	—
`page`	query	no	integer	—
`limit`	query	no	integer	—

Responses

Status	Description	Body
`200`	Paginated list of group members	—
`403`	Not authorized to view members (private group)	—

Check membership status for current user in a group

GET /api/communities/{communityId}/groups/{groupId}/membership-status

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`groupId`	path	yes	string (uuid)	—

Responses

Status	Description	Body
`200`	Membership status	object

Unhide a group (Moderator+ only)

PATCH /api/communities/{communityId}/groups/{groupId}/unhide

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`groupId`	path	yes	string (uuid)	—

Responses

Status	Description	Body
`200`	Group unhidden successfully	object
`400`	Group is already visible	—
`401`	Authentication required	—
`403`	Insufficient permissions (Moderator+ required)	—
`404`	Group not found	—

Community-wide aggregate of group join requests (Moderator+ only)

GET /api/communities/{communityId}/groups/join-requests

Returns join requests across ALL groups in the community in a single paginated response — replaces the per-group fan-out the badge / modal used to do. Call with ?status=PENDING&limit=1 to read just the pending count from pagination.total.

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`status`	query	no	enum: `PENDING`, `APPROVED`, `REJECTED`, `CANCELLED`	—
`page`	query	no	integer	—
`limit`	query	no	integer	—

Responses

Status	Description	Body
`200`	Aggregated list of join requests with embedded group + user info	—
`403`	Insufficient permissions (Moderator+ required)	—

Groups a given member belongs to, filtered to what the viewer may see

GET /api/communities/{communityId}/groups/member/{userId}

Backs the المجموعات tab on a member's profile.

Unlike GET /groups, which returns every group in the community (hidden ones included) and leaves filtering to the client, this endpoint filters SERVER-SIDE, because a membership fact is a different secret from a group's existence:

a hidden group is omitted unless the viewer holds groups:manage or groups:moderate
a private group is omitted unless the viewer is a member of it, or holds one of those two permissions

Rows are dropped silently — never 403 — so the response cannot be used to probe whether a particular private group exists. Same convention as POST /groups/members/batch.

Auth: Bearer JWT required.

Parameters

Name	In	Required	Type	Description
`communityId`	path	yes	string (uuid)	—
`userId`	path	yes	string (uuid)	The PROFILE OWNER's User.id (not a CommunityMember id)
`page`	query	no	integer	—
`limit`	query	no	integer	—

Responses

Status	Description	Body
`200`	Visible groups for that member	—
`400`	Invalid member user ID	—
`403`	Not a member of this community	—